plugin-compass

프로젝트 유형을 감지하고 Claude Code / Codex에 맞는 플러그인·스킬·MCP를 Global / Local / On-demand 범위로 추천하는 라우팅 스킬.

작동 방식

1. 설치 시 가이드 문서를 ~/.plugin-compass/에 배치하고, SKILL.md를 Claude Code · Codex의 스킬 디렉토리에 복사한다.
2. 전역 설정 파일(~/.claude/CLAUDE.md, ~/.codex/AGENTS.md)을 백업한 뒤 <!-- PLUGIN-COMPASS:START/END --> 마커 사이에 @ 참조를 추가한다. 마커 밖의 기존 내용은 건드리지 않는다.
3. 이후 모든 Claude Code · Codex 세션에서 에이전트가 가이드를 자동으로 참조한다.

추천/라우팅 대상

plugin-compass가 직접 설치하는 것은 plugin-compass 스킬과 가이드 문서다. 아래 도구들은 프로젝트 유형에 따라 Global / Local / On-demand 범위로 추천하거나 점검한다.

| 범위 | 도구/스킬 | | --- | --- | | Global (공통) | RTK, caveman, agentmemory, design-diversity, modern-web-guidance | | Global (Claude Code 전용) | OMC, codex-plugin-cc, tokensave | | Global (Codex 전용) | OMX, tightened-slide | | Codex App 내장 | Browser, Documents, Presentations, Spreadsheets | | Local | codegraph (Global CLI + Local 인덱스), beads, Slidev, 프로젝트 CLAUDE.md / AGENTS.md, .claude/planning/, reports/, slides/, data/, rag/ | | On-demand | mgrep, Alumnium, agent-browser, Chrome DevTools MCP, Playwright MCP, Exa MCP, Context7, GitHub MCP, Sequential Thinking MCP, harness-diagnostic | | 연구/RAG | Docling, LlamaIndex, Kuzu, Qdrant, Chroma, Zotero MCP, Semantic Scholar MCP, arXiv MCP | | 문서/데이터 | planning-with-files, AI-Research-SKILLs |

요구사항

• Node.js 18 이상
• Claude Code 또는 Codex CLI 중 하나 이상 설치

설치

npm (권장)

npm install -g plugin-compass
plugin-compass install

npm install은 CLI만 등록한다. 전역 파일 수정은 plugin-compass install을 명시적으로 실행해야 시작된다.

plugin-compass install이 처리하는 작업:

| 작업 | 경로 | | --- | --- | | 가이드 문서 복사 | ~/.plugin-compass/ | | Claude Code 스킬 설치 | ~/.claude/skills/plugin-compass/SKILL.md | | Codex 스킬 설치 | ~/.codex/skills/plugin-compass/SKILL.md | | 전역 파일 백업 | ~/.claude/CLAUDE.md.plugin-compass.bak 등 | | 전역 파일 @ 참조 추가 | ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md |

git clone (심볼릭 링크 방식)

git clone https://github.com/sohee-zoe/plugin-compass.git
cd plugin-compass
bash install.sh

~/.plugin-compass가 레포의 guides/ 폴더를 가리키는 심볼릭 링크로 생성된다. git pull 만 해도 가이드가 즉시 반영된다.

npm vs git clone 차이

• npm: 가이드를 ~/.plugin-compass/에 복사 (독립적, npm update로 갱신)
• git clone: ~/.plugin-compass를 레포 guides/에 심볼릭 링크 (git pull로 자동 반영)

설치 후 확인

plugin-compass where        # 설치 경로 확인
ls ~/.plugin-compass/       # 가이드 문서 확인
grep -n 'PLUGIN-COMPASS' ~/.claude/CLAUDE.md
grep -n 'PLUGIN-COMPASS' ~/.codex/AGENTS.md

사용법

Claude Code

새 프로젝트 폴더에서:

/plugin-compass

또는 자연어로:

이 프로젝트 플러그인 세팅해줘

Codex

With $plugin-compass skill, 이 프로젝트 플러그인 세팅해줘

에이전트 동작 흐름

1. 프로젝트 루트의 CLAUDE.md / AGENTS.md와 디렉터리 구조를 스캔해 프로젝트 유형을 판별한다.
2. 판별 결과를 바탕으로 Global / Local / On-demand 도구를 추천한다.
3. 사용자 승인 후에만 설치 또는 초기화를 진행한다.

마커 시스템

전역 설정 파일의 마커 사이 내용만 관리한다. OMC · OMX 등 다른 도구가 관리하는 영역은 건드리지 않는다.

<!-- PLUGIN-COMPASS:START -->
@~/.plugin-compass/PLUGIN-DOCS-README.md
@~/.plugin-compass/PROJECT-PLUGIN-SETUP.md
@~/.plugin-compass/CLAUDE-PLUGINS.md
<!-- PLUGIN-COMPASS:END -->

• 마커가 없으면 파일 끝에 추가한다.
• 마커가 이미 있으면 마커 사이의 내용만 교체한다.
• START/END 쌍이 맞지 않으면 수정하지 않고 오류를 보고한다.
• 수정 전 항상 .plugin-compass.bak 파일로 백업한다.

CLI 명령

plugin-compass install     # 가이드 + 스킬 설치 및 전역 파일 @ 참조 추가
plugin-compass uninstall   # 가이드·스킬·전역 마커 블록 제거
plugin-compass update      # ~/.plugin-compass/ 가이드 재동기화 (npm 설치 시)
plugin-compass where       # 설치 경로 확인
plugin-compass version     # 설치된 CLI 버전 확인
plugin-compass help        # 도움말

업데이트

npm 설치 시

npm update -g plugin-compass
plugin-compass update

git clone 설치 시

cd plugin-compass
git pull
# 심볼릭 링크이므로 별도 작업 불필요

제거

npm 설치

plugin-compass uninstall
npm uninstall -g plugin-compass

git clone 설치

cd plugin-compass
node cli.js uninstall

uninstall 명령이 처리하는 작업:

• ~/.plugin-compass/ 삭제 (또는 심볼릭 링크 제거)
• ~/.claude/skills/plugin-compass/ 삭제
• ~/.codex/skills/plugin-compass/ 삭제
• ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md에서 PLUGIN-COMPASS 마커 블록 제거 (백업 포함)

가이드 문서

| 문서 | 역할 | | --- | --- | | PLUGIN-DOCS-README.md | 전체 인덱스 및 에이전트 라우팅 규칙 | | PROJECT-PLUGIN-SETUP.md | 프로젝트 유형별 자동 선택 규칙 | | CLAUDE-PLUGINS.md | Claude Code 플러그인 운영 가이드 | | AGENTS-PLUGINS.md | Codex 플러그인 운영 가이드 | | RESEARCH-RAG-PLUGINS.md | 연구 RAG / GraphRAG | | SLIDES-VISUAL-PLUGINS.md | 슬라이드 / 시각화 | | BROWSER-AUTOMATION-PLUGINS.md | 브라우저 자동화 | | CODEBASE-MEMORY-PLUGINS.md | 코드베이스 / 메모리 / 오케스트레이션 | | DOCUMENT-DATA-PLUGINS.md | 문서 / 데이터 / 보고서 |

보안 원칙

에이전트가 따르는 제약사항:

• mgrep — 비공개·기관·회사·개인정보 포함 프로젝트에서 사용하지 않는다.
• Alumnium, agent-browser, Chrome DevTools MCP — 허용된 계정과 약관 범위에서만 사용한다.
• tightened-slide — ~/.codex/skills/ 전용. Claude Code에는 설치하지 않는다.
• codex-plugin-cc — Claude Code 전용 브리지. Codex에는 설치하지 않는다.

라이선스

MIT