技能图谱

一个 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 提供查看器，而插件已要求 node。/skill-graph:app 则改为以原生桌面窗口打开相同的查看器，代价是一次性安装约 280 MB 的 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 端到端地完成此操作——选择位置，查找机器上的每个源，写入带有绝对根路径的配置，在 ~/.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 仅提取前置元数据；不会为导入计算交叉引用。导入的技能上零连接是对导入者的陈述，而不是对技能的陈述。这也是为什么导入一个您已经配置为源的目录比无用更糟糕，以及为什么它被拒绝的原因——见下文。

当两个东西同名时

两个不相关的仓库可能各自持有一个 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 可以区分它们，因为它们是同一个文件。它会在写入任何内容之前停止，指出已在图谱中的文件，并以“未导入任何内容”结束。

两个不同的仓库恰好共享一个技能名称是可以的，并且仍然可以导入；检查的是路径，而不是名称。

图谱是一个快照

它反映了最后一次构建。手动添加技能、更改源或在这些工具之外安装某些内容后，图谱将过时，直到您再次构建。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 安装，因此如果依赖项被提升而未更新锁文件，构建将失败而不是静默发布。

查看器可以直接运行，这是在 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。