| name | skill-graph-builder |
| description | Build an interactive Obsidian skill-graph vault mapping which agents can access which skills across Claude Code, Codex, OpenClaw, and Hermes. Use this whenever the user wants to visualize, audit, or rebuild agent↔skill access, see which skills an agent can load, dedup duplicate skill copies, or asks to "build/rebuild/update the skill graph" or "skill graph 更新/重建" — even if they don't say "Obsidian". |
skill-graph-builder
Zero-config, interactive builder for an agent↔skill relationship-graph vault. User Scope only (v1).
Orchestration flow (no-argument /skill-graph-builder)
- Run
python3 -m scripts.discover → receive JSON. Discover uses the working directory at runtime (cwd) as the scan root ∪ standard locations ($CLAUDE_CONFIG_DIR/~/.claude, $CODEX_HOME/~/.codex, ~/.openclaw, ~/.hermes/profiles), finds agents via each platform's config marker (settings.json/config.toml/openclaw.json/profiles/*/config.yaml), and deduplicates by resolved path.
(Running from your agent workspace will scan the Claude/Codex/Hermes configs underneath it.)
- Use AskUserQuestion to present the results to the user as a multi-select: first ask "which platforms to include", then if needed "which agents". Anomalous entries (e.g. has
CLAUDE.md but no settings.json) are unchecked by default with the reason clearly listed.
- Vault location: suggest first, then let the user choose (never silently default). Use AskUserQuestion to offer three options:
~/skill-graph (Recommended) — standalone directory, outside any git repo, Obsidian won't hang, easy to regenerate.<existing Obsidian vault>/skill-graph — attach to an existing vault; ask the user for the vault root path and append /skill-graph as a subdirectory.- Custom path — user-supplied.
Guard: If the chosen path lies inside any git working tree, or any shared / version-controlled tree, warn about three risks first (① the symlink farm pollutes the shared working tree; ② machine-specific absolute paths will conflict across machines in version control, same as audit logs; ③ Obsidian will index the entire tree and may hang), and require explicit confirmation from the user before proceeding.
- Write the selection to
<vault>/.skill-graph-builder.manifest.toml (schema: see config.example.toml; claude_code/codex are per-config-directory lists). Set vault: in the manifest to the value chosen in step 3. If a manifest already exists at that path, reuse it safely (generate is idempotent).
- Run
python3 -m scripts.generate --vault <vault> → produce vault + log.
/skill-graph-builder discover: runs step 1 only and reports; does not generate, does not prompt.
/skill-graph-builder --non-interactive: skips steps 1–4 and runs
python3 -m scripts.generate --vault <vault> directly (vault must already contain a manifest, otherwise exits with a clear error).
OpenClaw note
OpenClaw is treated symmetrically with the other three platforms: discover looks for openclaw.json in the scan root / standard locations. If the OpenClaw gateway lives on a different machine (its openclaw.json is gitignored runtime state on that machine and is not synced as a file), not finding it locally is expected — sync or snapshot the openclaw.json back to the local machine to make it detectable (this is the user's sync-infrastructure responsibility; the skill does not perform cross-machine SSH).
Non-agent fallback
When AskUserQuestion is not available: present the discover JSON to the user, ask them to hand-write a TOML manifest using config.example.toml as the template, then run python3 -m scripts.generate --manifest <file>. The Python layer (discover/generate) is headless and testable, not tied to any specific runtime.
Deduplication and visibility
Multiple physical copies of the same skill that share a ContentIdentity (same sanitize(dirname) and normalized content hash) are merged into a single <id>.md symlink pointing to the lexicographically first canonical SKILL.md — the node is fully readable in Obsidian and the native graph is not broken. Skills with the same name but different content (version divergence) are kept as separate nodes. The run log includes a ## Skill provenance section listing every deduplicated skill's physical sources and the agents that use it (traceable for debugging).
