Skill Graph

Плагин для 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 открывает тот же просмотрщик в виде нативного десктопного окна, но ценой одноразовой установки Electron размером ~280 МБ.

Related MCP server: skills-mcp

Требования

Windows не поддерживается для /skill-graph:build. Команды сборки вызывают python3, который установки Python в Windows обычно не предоставляют (это python или py). install_skill имеет ту же зависимость и завершается ошибкой после копирования файлов, поэтому может оставить частично применённое состояние. WSL работает.

Скрипт упаковки десктопного приложения предназначен только для macOS arm64. На других платформах используйте /skill-graph:view или запускайте его без упаковки с помощью npm start из app/.

Один граф или по одному на проект

По умолчанию каталог данных — <project>/.claude/graph, поэтому два проекта никогда не видят графы друг друга. Обычно это то, что нужно, и именно поэтому ничего не следует за вами между несвязанными репозиториями.

GRAPH_DATA_DIR переопределяет это. Установите его, и каждый проект будет читать и записывать один и тот же каталог:

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

/skill-graph:setup-global делает это от начала до конца — выбирает местоположение, находит все источники на машине, записывает конфигурацию с абсолютными корнями, устанавливает переменную в ~/.claude/settings.json и выполняет сборку. Это вступает в силу после следующего перезапуска, потому что MCP-сервер читает своё окружение при запуске процесса.

Совместное использование каталога также распространяет наложение, поэтому заметки, оценки и теги становятся общесистемными, а не привязанными к репозиторию. Если вы хотите одни и те же навыки везде, но не одни и те же заметки, не устанавливайте переменную — дайте каждому проекту обычную конфигурацию, корни источников которой являются абсолютными. Относительные корни разрешаются относительно проекта; абсолютные — нет, поэтому несколько проектов могут каталогизировать одни и те же папки и при этом сохранять свои собственные графы.

Графы для каждого проекта никогда не удаляются при переходе на глобальный. Удалите переменную, и они снова станут активными.

Где что находится

Код поставляется с плагином. Данные принадлежат проекту:

<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 — каталоги, содержащих агентов и навыки для каталогизации. kind: "agent" для папки с файлами *.md; kind: "skill" для папки с каталогами <name>/SKILL.md. Относительные пути разрешаются относительно корня проекта. Отсутствующий корень пропускается с предупреждением, а не с ошибкой.

• scanRoots — деревья, в которых ищутся проекты, где установлены эти навыки. Это заполняет поле «кто на самом деле это использует». [] означает ничего не сканировать, и это соблюдается как написано.

• scanExclude — исключить любой путь, содержащий одну из этих подстрок.

Проект, которому принадлежит настроенный источник, никогда не учитывается как пользователь своего собственного каталога. Без этого репозиторий, каталогизирующий свои собственные .claude/skills, сообщал бы о себе как о пользователе каждого навыка в нём, и каждое число использования было бы завышено на единицу.

Что инструменты сообщают вам, а что нет

Рёбра — это подсчитанные упоминания. Ребро существует, потому что текст одного файла содержит имя другого узла. Это реальное, воспроизводимое измерение — это не курируемое утверждение, что две вещи принадлежат друг другу. Навык, названный в честь распространённого слова, собирает рёбра случайно.

Использование — это факт файловой системы. usedBy получается из проверки, действительно ли файл существует. Отсутствие означает «не найдено в ваших корнях сканирования», а не «не используется».

Категории — это догадка. Они получаются из эвристики по ключевым словам во время сборки, которая сначала читает имя и обращается к описанию только тогда, когда имя ничего не говорит — вещь с именем python-testing — это Python, а вещь, которая лишь упоминает Python вскользь, — нет. Это всё ещё эвристика: она будет классифицировать некоторые вещи странно и говорит general, когда не может определить. Теги применяются вручную и означают то, что решил кто-то. Предпочитайте теги.

Импортированные репозитории не имеют рёбер. add_repo извлекает только frontmatter; перекрёстные ссылки не вычисляются для импортов. Ноль связей у импортированного навыка — это утверждение об импортёре, а не о навыке. Это также причина, по которой импорт каталога, который вы уже настроили как источник, хуже, чем бесполезен, и почему он отклоняется — см. ниже.

Когда две вещи имеют одно имя

Два несвязанных репозитория могут содержать по code-reviewer, и оба должны быть в графе. Поэтому поиск по имени может быть действительно неоднозначным, и ответ называет идентификаторы вместо этого:

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

Каждый инструмент, принимающий узел, также принимает идентификатор, поэтому кандидата из этого списка можно передать обратно для разрешения неоднозначности — включая install_skill и uninstall_skill, где выбор неправильного копирует или удаляет реальные файлы.

add_repo отказывается от каталога, который сборка уже каталогизирует. Оба пути привели бы к одним и тем же файлам — сборка записывает их в graph-data.json, импорт сохраняет их в overlay.json, и они объединяются при чтении — поэтому каждый элемент в нём появлялся бы дважды под одним именем, и никакой идентификатор не смог бы их различить, потому что они являются одним и тем же файлом. Он останавливается до записи чего-либо, называя файл, который уже есть в графе, и заканчивая «Ничего не было импортировано».

Два разных репозитория, которые случайно имеют одно и то же имя навыка, — это нормально, и они всё равно импортируются; проверка выполняется по путям, а не по именам.

Граф — это снимок

Он отражает последнюю сборку. Добавьте навык вручную, измените источник или установите что-то вне этих инструментов — и он устареет, пока вы не выполните сборку снова. 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.