Skill Graph

A Claude Code 플러그인으로, 이미 보유한 스킬과 에이전트를 그래프로 변환하여 세션, 브라우저, 또는 데스크톱 앱에서 쿼리할 수 있게 해줍니다.

지정한 폴더의 모든 에이전트와 스킬을 카탈로그화하고, 실제로 서로를 언급하는 항목을 계산하며, 각 스킬이 실제로 설치된 프로젝트를 머신에서 스캔한 후, 이 모든 것을 MCP 도구로 노출합니다. 알고 있는 모든 정보는 실제 파일을 읽어서 얻습니다.

자세한 내용을 보려면 노드를 클릭하세요. 해당 노드를 참조하는 항목, 해당 노드가 참조하는 항목, 설치된 프로젝트, 그리고 사용자의 노트, 평점 및 태그를 확인할 수 있습니다:

설치

/plugin marketplace add QuantumWars/project-graphx
/plugin install skill-graph

그런 다음, 그래프를 원하는 프로젝트에서:

/skill-graph:setup     # say where your skills and agents live — then offers to build
/skill-graph:build     # rescan, whenever the sources change
/skill-graph:view      # look at it, in your browser

/skill-graph:setup은 빌드 전에 확인을 요청합니다. scanRoots가 설정된 빌드는 모든 스캔 루트를 탐색하기 때문입니다. 예라고 답하면 아무것도 없는 상태에서 바로 그래프를 얻을 수 있습니다.

각 프로젝트는 고유한 그래프를 가집니다. 모든 프로젝트가 공유하는 하나의 카탈로그를 원한다면 대신 /skill-graph:setup-global을 실행하세요 — 하나의 그래프, 또는 프로젝트별 그래프를 참조하세요.

/skill-graph:view는 다운로드가 필요 없습니다. 플러그인이 이미 요구하는 node에서 뷰어를 제공합니다. /skill-graph:app은 대신 동일한 뷰어를 네이티브 데스크톱 창으로 열며, 약 280MB의 일회성 Electron 설치가 필요합니다.

Related MCP server: skills-mcp

요구 사항

Windows는 /skill-graph:build를 지원하지 않습니다. 빌드 명령은 python3를 호출하는데, Windows Python 설치에서는 일반적으로 제공되지 않습니다 (python 또는 py). install_skill도 동일한 종속성을 가지며 파일을 복사한 후에 실패하므로, 반쯤 적용된 상태가 남을 수 있습니다. WSL은 작동합니다.

데스크톱 앱의 패키징 스크립트는 macOS arm64만 대상으로 합니다. 다른 플랫폼에서는 /skill-graph:view를 사용하거나, app/에서 npm start로 패키징 없이 실행하세요.

하나의 그래프, 또는 프로젝트별 그래프

기본적으로 데이터 디렉터리는 <project>/.claude/graph이므로, 두 프로젝트는 서로의 그래프를 볼 수 없습니다. 이것이 일반적으로 원하는 방식이며, 관련 없는 저장소 간에 아무것도 따라가지 않는 이유입니다.

GRAPH_DATA_DIR이 이를 재정의합니다. 설정하면 모든 프로젝트가 동일한 디렉터리를 읽고 씁니다:

dataDir = GRAPH_DATA_DIR  or  <project>/.claude/graph

/skill-graph:setup-global은 이를 처음부터 끝까지 수행합니다. 위치를 선택하고, 머신의 모든 소스를 찾고, 절대 경로로 설정된 config를 작성하고, ~/.claude/settings.json에 변수를 설정하고, 빌드합니다. MCP 서버가 프로세스 시작 시 환경을 읽기 때문에 다음 재시작 시 적용됩니다.

디렉터리를 공유하면 오버레이도 공유되므로, 노트, 평점, 태그가 저장소별이 아닌 머신 전체에 적용됩니다. 동일한 스킬은 모든 곳에서 원하지만 동일한 노트는 원하지 않는다면 변수를 설정하지 마세요. 각 프로젝트에 소스 루트가 절대 경로인 일반 config를 지정하세요. 상대 경로는 프로젝트 기준으로 해석되고, 절대 경로는 그렇지 않으므로 여러 프로젝트가 동일한 폴더를 카탈로그화하면서도 고유한 그래프를 유지할 수 있습니다.

프로젝트별 그래프는 글로벌로 전환해도 삭제되지 않습니다. 변수를 제거하면 다시 활성화됩니다.

파일 위치

코드는 플러그인과 함께 제공됩니다. 데이터는 프로젝트에 속합니다:

<your project>/.claude/graph/
├── config.json        what to catalogue, what to scan   (you own this — commit it)
├── graph-data.json    the built graph                   (regenerated wholesale)
├── overlay.json       your notes, ratings, tags, edges  (survives rebuilds)
└── imported-repos/    shallow clones from add_repo

그래프 데이터는 플러그인 디렉터리에 절대 기록되지 않으며, 플러그인 디렉터리는 재설치 시마다 지워집니다. 동일한 머신의 두 프로젝트는 각각 독립적인 그래프를 가지며 서로를 볼 수 없습니다.

유일한 예외는 Electron 자체입니다: /skill-graph:app은 플러그인의 app/ 아래에 설치되므로, 플러그인 업데이트 시 다시 다운로드해야 합니다. /skill-graph:view는 재설치할 것이 없으며, 이것이 기본값인 주된 이유입니다.

graph-data.json은 모든 /skill-graph:build에서 처음부터 다시 빌드됩니다. 직접 편집하지 마세요 — 편집 내용은 사라집니다. 도구를 통해 추가하는 모든 것은 overlay.json에 저장되며, 빌드가 건드리지 않습니다.

구성

.claude/graph/config.json:

{
  "sources": [
    { "repo": "my-project", "root": ".claude/agents", "kind": "agent" },
    { "repo": "my-project", "root": ".claude/skills", "kind": "skill" }
  ],
  "scanRoots": ["~/code"],
  "scanExclude": ["/node_modules/"]
}

• sources — 카탈로그화할 에이전트와 스킬이 있는 디렉터리. *.md 파일 폴더의 경우 kind: "agent"; <name>/SKILL.md 디렉터리 폴더의 경우 kind: "skill". 상대 경로는 프로젝트 루트 기준으로 해석됩니다. 존재하지 않는 루트는 충돌 없이 경고와 함께 건너뜁니다.

• scanRoots — 해당 스킬이 설치된 프로젝트를 검색하는 트리. 이것이 "누가 실제로 이것을 사용하는지"를 채웁니다. []는 아무것도 스캔하지 않음을 의미하며, 그대로 존중됩니다.

• scanExclude — 이러한 하위 문자열 중 하나를 포함하는 경로를 제외합니다.

구성된 소스를 소유한 프로젝트는 자체 카탈로그의 사용자로 계산되지 않습니다. 그렇지 않으면, 자체 .claude/skills를 카탈로그화하는 저장소는 그 안의 모든 스킬을 사용자로 보고하게 되어 모든 사용 수가 1씩 부풀려집니다.

도구가 알려주는 것과 알려주지 않는 것

엣지는 언급 횟수입니다. 엣지는 한 파일의 텍스트가 다른 노드의 이름을 포함하기 때문에 존재합니다. 이는 실제로 재현 가능한 측정값이며, 두 항목이 함께 속한다는 큐레이션된 진술이 아닙니다. 일반적인 단어를 따서 명명된 스킬은 우연히 엣지를 수집합니다.

사용은 파일 시스템 사실입니다. usedBy는 파일이 실제로 존재하는지 확인하여 얻습니다. 없음은 "스캔 루트 아래에서 찾을 수 없음"을 의미하며, "사용되지 않음"이 아닙니다.

카테고리는 추측입니다. 빌드 시 키워드 휴리스틱에서 비롯되며, 이름을 먼저 읽고 이름이 아무것도 말해주지 않을 때만 설명을 참조합니다. python-testing이라는 것은 Python이고, 단지 Python을 언급만 하는 것은 아닙니다. 여전히 휴리스틱입니다: 일부 항목을 이상하게 분류할 수 있으며, 구분할 수 없을 때는 general이라고 표시합니다. 태그는 수동으로 적용되며 누군가가 결정한 의미를 갖습니다. 태그를 선호하세요.

가져온 저장소에는 엣지가 없습니다. add_repo는 프론트매터만 추출합니다. 가져오기에 대해 교차 참조가 계산되지 않습니다. 가져온 스킬의 연결 0개는 스킬에 대한 진술이 아니라 가져오기에 대한 진술입니다. 이것이 이미 소스로 구성한 디렉터리를 가져오는 것이 쓸모없는 것보다 나쁜 이유이며, 거부되는 이유입니다 — 아래 참조.

두 항목이 이름을 공유할 때

관련 없는 두 저장소가 각각 code-reviewer를 보유할 수 있으며, 둘 다 그래프에 속합니다. 따라서 이름으로 조회하면 진정으로 모호할 수 있으며, 대신 id를 명명한 답변이 반환됩니다:

{ "error": "ambiguous", "candidates": ["myproj:agent:code-reviewer", "import:other:agent:code-reviewer"] }

노드를 인수로 받는 모든 도구는 id도 허용하므로, 해당 목록의 후보를 바로 다시 전달하여 동점을 해결할 수 있습니다. install_skill과 uninstall_skill도 포함되며, 여기서 잘못된 것을 선택하면 실제 파일을 복사하거나 삭제합니다.

add_repo는 빌드가 이미 카탈로그화한 디렉터리를 거부합니다. 두 경로 모두 동일한 파일에 도달합니다. 빌드는 graph-data.json에 쓰고, 가져오기는 overlay.json에 저장하며, 읽을 때 병합됩니다. 따라서 그 아래의 모든 항목이 하나의 이름 아래에 두 번 나타나며, id로도 구분할 수 없습니다. 왜냐하면 동일한 파일이기 때문입니다. 아무것도 쓰기 전에 중단되며, 이미 그래프에 있는 파일을 명명하고 "Nothing was imported."로 끝납니다.

우연히 스킬 이름을 공유하는 두 개의 다른 저장소는 괜찮으며 여전히 가져옵니다. 검사는 이름이 아닌 경로에 대해 수행됩니다.

그래프는 스냅샷입니다

마지막 빌드를 반영합니다. 수동으로 스킬을 추가하거나, 소스를 변경하거나, 이 도구 외부에서 무언가를 설치하면 다시 빌드할 때까지 오래된 상태입니다. install_skill과 uninstall_skill은 스스로 다시 스캔합니다. 다른 것은 그렇지 않습니다.

개발

bun install --frozen-lockfile   # exactly the versions CI and the bundle were built from
bun test                        # unit + end-to-end
bun run bundle                  # rebuild server/server.bundle.mjs after editing server/

bun.lock은 커밋된 번들이 컴파일된 대상을 고정하고, app/package-lock.json은 데스크톱 앱이 테스트된 Electron을 고정합니다. CI는 --frozen-lockfile로 설치하므로, lockfile을 업데이트하지 않고 종속성을 올리면 조용히 배포되는 대신 실행이 실패합니다.

뷰어는 직접 실행할 수 있으며, 이는 app/에서 반복 작업하는 가장 빠른 방법입니다:

node server/viewer-server.js --data-dir <project>/.claude/graph

server/ 아래의 변경 사항 후에는 다시 번들링하세요. .mcp.json은 소스가 아닌 번들을 실행하므로, 번들링되지 않은 편집은 배포되지 않는 편집입니다. 종단간 테스트 스위트는 정확히 Claude Code가 하는 대로 번들을 실행하며, 번들이 오래되었으면 실패합니다. CI는 번들을 다시 빌드하고 커밋된 사본과 다르면 실패합니다.

bun run bundle은 scripts/normalize-bundle.js도 실행합니다. 이 스크립트는 번들러가 빌드 시 고정하는 __dirname 리터럴을 런타임 표현식으로 대체합니다. 이것이 없으면 아티팩트는 빌드한 사람의 절대 경로를 가지게 되며, 두 머신이 동일한 바이트를 생성할 수 없습니다. 이것이 CI 비교를 가능하게 하는 것입니다.

라이선스

MIT — LICENSE 참조.