Skill Graph

Un plugin de Claude Code que convierte las habilidades y agentes que ya tienes en un gráfico que puedes consultar — desde una sesión, en tu navegador o en una aplicación de escritorio.

Cataloga cada agente y habilidad en las carpetas que le indicas, cuenta cuáles de ellos mencionan realmente a otros, escanea tu máquina en busca de proyectos que realmente tengan instalado cada uno, y expone todo ello como herramientas MCP. Todo lo que sabe proviene de leer archivos reales.

Haz clic en cualquier nodo para ver qué lo referencia, qué referencia él, qué proyectos lo tienen instalado, y tus propias notas, valoraciones y etiquetas:

Instalar

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

Luego, en cualquier proyecto para el que quieras un gráfico:

/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 pregunta antes de construir en lugar de hacerlo directamente, porque una construcción con scanRoots configurado recorre cada raíz de escaneo. Di que sí y pasarás directamente de nada a un gráfico.

Cada proyecto obtiene su propio gráfico. Si prefieres tener un catálogo compartido por todos los proyectos, ejecuta /skill-graph:setup-global en su lugar — consulta Un gráfico, o uno por proyecto.

/skill-graph:view no necesita descarga — sirve el visor desde node, que el plugin ya requiere. /skill-graph:app abre el mismo visor como una ventana nativa de escritorio, a costa de una instalación única de Electron de ~280 MB.

Related MCP server: skills-mcp

Requisitos

Windows no es compatible con /skill-graph:build. Los comandos de construcción invocan python3, que las instalaciones de Python en Windows no suelen proporcionar (es python o py). install_skill tiene la misma dependencia y falla después de copiar archivos, por lo que puede dejar un estado parcialmente aplicado. WSL funciona.

El script de empaquetado de la aplicación de escritorio está dirigido solo a macOS arm64. En otras plataformas usa /skill-graph:view, o ejecútalo sin empaquetar con npm start desde app/.

Un gráfico, o uno por proyecto

Por defecto, el directorio de datos es <project>/.claude/graph, por lo que dos proyectos nunca ven los gráficos del otro. Eso suele ser lo que quieres, y es por lo que nada te sigue entre repositorios no relacionados.

GRAPH_DATA_DIR lo anula. Configúralo y cada proyecto lee y escribe el mismo directorio:

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

/skill-graph:setup-global hace eso de principio a fin — elige la ubicación, encuentra cada fuente en la máquina, escribe la configuración con raíces absolutas, establece la variable en ~/.claude/settings.json y construye. Tiene efecto en el próximo reinicio, porque un servidor MCP lee su entorno al iniciar el proceso.

Compartir el directorio también comparte la superposición, por lo que las notas, valoraciones y etiquetas se vuelven de toda la máquina en lugar de por repositorio. Si quieres las mismas skills en todas partes pero no las mismas notas, no establezcas la variable — dale a cada proyecto una configuración normal cuyas raíces de origen sean absolutas. Las raíces relativas se resuelven respecto al proyecto; las absolutas no, por lo que varios proyectos pueden catalogar las mismas carpetas y aún así mantener sus propios gráficos.

Los gráficos por proyecto nunca se eliminan al volverse global. Elimina la variable y vuelven a estar activos.

Dónde viven las cosas

El código se distribuye con el plugin. Los datos pertenecen al proyecto:

<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

Nunca se escriben datos del gráfico en el directorio del plugin, que se borra en cada reinstalación. Dos proyectos en la misma máquina obtienen dos gráficos independientes y nunca se ven entre sí.

La única excepción es el propio Electron: /skill-graph:app lo instala en app/ del plugin, por lo que una actualización del plugin implica descargarlo de nuevo. /skill-graph:view no tiene nada que reinstalar, que es la razón principal por la que es el predeterminado.

graph-data.json se reconstruye desde cero en cada /skill-graph:build. Nunca lo edites a mano — tu edición desaparecerá. Todo lo que añadas a través de las herramientas va a overlay.json, que las construcciones nunca tocan.

Configuración

.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 — directorios que contienen los agentes y habilidades a catalogar. kind: "agent" para una carpeta de *.md; kind: "skill" para una carpeta de directorios <name>/SKILL.md. Las rutas relativas se resuelven respecto a la raíz del proyecto. Una raíz faltante se omite con una advertencia, no con un fallo.

• scanRoots — árboles buscados para proyectos que tengan esas habilidades instaladas. Esto es lo que completa "quién usa realmente esto". [] significa no escanear nada, y se respeta tal cual.

• scanExclude — descarta cualquier ruta que contenga una de estas subcadenas.

Un proyecto que posee una fuente configurada nunca se cuenta como usuario de su propio catálogo. Sin eso, un repositorio que catalogue su propio .claude/skills se reportaría a sí mismo como usuario de cada habilidad en él, y cada número de uso se inflaría en uno.

Lo que las herramientas te dicen, y lo que no

Las aristas son menciones contadas. Una arista existe porque el texto de un archivo contiene el nombre de otro nodo. Esa es una medición real y reproducible — no es una declaración curada de que dos cosas pertenecen juntas. Una habilidad nombrada después de una palabra común acumula aristas por coincidencia.

El uso es un hecho del sistema de archivos. usedBy proviene de verificar si el archivo está realmente allí. Ausente significa "no encontrado bajo tus raíces de escaneo", nunca "no usado".

Las categorías son una suposición. Provienen de una heurística de palabras clave en tiempo de construcción, que lee el nombre primero y solo recurre a la descripción cuando el nombre no dice nada — una cosa llamada python-testing es Python, una cosa que meramente menciona Python de paso no lo es. Sigue siendo una heurística: clasificará algunas cosas de manera extraña y dice general cuando no puede determinar. Las etiquetas son aplicadas manualmente y significan lo que alguien decidió. Prefiere las etiquetas.

Los repositorios importados no tienen aristas. add_repo extrae solo el frontmatter; no se calculan referencias cruzadas para las importaciones. Cero conexiones en una habilidad importada es una declaración sobre el importador, no sobre la habilidad. Esta es también la razón por la que importar un directorio que ya configuraste como fuente es peor que inútil, y por lo que se rechaza — ver más abajo.

Cuando dos cosas comparten un nombre

Dos repositorios no relacionados pueden tener cada uno un code-reviewer, y ambos pertenecen al gráfico. Por lo tanto, una búsqueda por nombre puede ser genuinamente ambigua, y la respuesta nombra los ids en su lugar:

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

Cada herramienta que toma un nodo también acepta un id, por lo que un candidato de esa lista se puede pasar directamente de vuelta para resolver el empate — incluyendo install_skill y uninstall_skill, donde elegir el incorrecto copia o elimina archivos reales.

add_repo rechaza un directorio que la construcción ya cataloga. Ambas rutas llegarían a los mismos archivos — la construcción los escribe en graph-data.json, una importación los almacena en overlay.json, y los dos se fusionan al leer — por lo que cada elemento debajo aparecería dos veces bajo un nombre, y ningún id podría distinguirlos porque son el mismo archivo. Se detiene antes de escribir nada, nombrando el archivo que ya está en el gráfico y terminando "No se importó nada."

Dos repositorios diferentes que casualmente comparten un nombre de habilidad están bien y aún se importan; la verificación es sobre rutas, no nombres.

El gráfico es una instantánea

Refleja la última construcción. Añade una habilidad manualmente, cambia una fuente, o instala algo fuera de estas herramientas, y estará desactualizado hasta que construyas de nuevo. install_skill y uninstall_skill se reescanan a sí mismos; nada más lo hace.

Desarrollo

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 fija de qué está compilado el bundle confirmado, y app/package-lock.json fija el Electron contra el que se probó la aplicación de escritorio. CI instala con --frozen-lockfile, por lo que una dependencia aumentada sin actualizar el lockfile falla la ejecución en lugar de enviarse silenciosamente.

El visor se puede ejecutar directamente, que es la forma más rápida de iterar en app/:

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

Re-empaqueta después de cualquier cambio en server/. .mcp.json ejecuta el bundle, no la fuente, por lo que una edición sin empaquetar es una edición que no se envía. El conjunto de pruebas de extremo a extremo lanza el bundle exactamente como lo hace Claude Code y fallará si está desactualizado, y CI lo reconstruye y falla si la copia confirmada difiere.

bun run bundle también ejecuta scripts/normalize-bundle.js, que reemplaza el literal __dirname que el empaquetador congela en tiempo de construcción con una expresión en tiempo de ejecución. Sin él, el artefacto llevaría la ruta absoluta de quien lo construyó, y dos máquinas nunca producirían los mismos bytes — que es lo que hace posible la comparación de CI.

Licencia

MIT — consulta LICENSE.