Stage 1: RUN GRAPH ANALYSIS
Run the analysis script from the skill directory:
SKILL_DIR="${CLAUDE_SKILL_DIR}"
uv run "$SKILL_DIR/scripts/analyze_vault_graph.py" "." --top 20
The script outputs JSON to stdout with:
summary: total notes, edges, orphans, density, clustering coefficienttop_pagerank: most influential notestop_betweenness: bridge concepts connecting clusterstop_in_degree: most referenced notestop_out_degree: most connecting notesorphans: notes with zero links in/outdead_ends: notes referenced but linking nowhereclusters: connected components with dominant typesmissing_links: wikilinks pointing to non-existent notestype_distribution: counts by note typestatus_distribution: counts by processing status
Requires uv installed (brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh). Dependencies auto-install on first run.
Stage 2: INTERPRET WITH AGENT
Read the agent definition from agents/graph-analyst.md in the skill directory.
Launch the analyst agent:
Agent(
subagent_type="general-purpose",
model="sonnet",
run_in_background=false,
prompt="You are Graph Analyst. Follow these instructions exactly:
[INSERT FULL CONTENT OF agents/graph-analyst.md HERE]
VAULT CONTEXT:
- This is a Zettelkasten-style Obsidian vault
- Note types: term (atomic concepts), thought (original synthesis),
paper/post/book (sources), note (explanations), decision-log
- Tags are inline (#topic), not frontmatter
- Cross-domain connections are the vault's highest-value links
GRAPH ANALYSIS RESULTS:
[INSERT JSON OUTPUT FROM STAGE 1 HERE]
Produce your analysis following the Output Format specified above."
)
Stage 3: PRESENT RESULTS
Present the agent's analysis to the user. Include:
- The health score and top findings
- Specific bridge concepts and orphans
- Missing notes worth creating
- Suggested new connections
If the user wants to ACT on suggestions (create notes, add links), help them
do so using standard vault tools (Edit, write_note, etc.).
$ARGUMENTS
1---2name: vault-graph3description: Use when analyzing vault structure, finding orphan notes, discovering missing connections, identifying bridge concepts, or checking vault health from a graph perspective. Triggers on "vault graph", "map vault", "find orphans", "missing links", "vault structure", "knowledge graph".4---56<Purpose>7Analyze the vault's wikilink structure as a directed graph. Computes PageRank8(most influential concepts), betweenness centrality (bridge nodes connecting9domains), orphan detection, cluster analysis, and missing-link discovery.10Combines deterministic graph computation (Python/NetworkX) with intelligent11interpretation (agent) to surface actionable insights.12</Purpose>1314<Use_When>15- User asks about vault structure, connections, or health16- User wants to find orphan notes (unlinked, isolated)17- User wants to discover missing connections between notes18- User wants to identify the most important concepts in the vault19- User asks "what should I link?" or "what's disconnected?"20- As part of /health workflow for structural metrics21- User says "map", "graph", "network", "connections", "orphans", "bridges"22</Use_When>2324<Do_Not_Use_When>25- User wants to search note CONTENT (use Grep/search_notes instead)26- User wants to process a single note (use /process)27- User wants tag analysis without graph structure (use /health)28</Do_Not_Use_When>2930<Execution_Policy>31- Run the Python script first — it handles all graph math deterministically32- Pipe script output to the graph-analyst agent for interpretation33- Report progress via TodoWrite34- If uv is not installed, provide install command and stop35- Script runs on the full vault — no sampling needed (handles 5000+ notes)36</Execution_Policy>3738<Steps>3940## Stage 1: RUN GRAPH ANALYSIS4142Run the analysis script from the skill directory:4344```bash45SKILL_DIR="${CLAUDE_SKILL_DIR}"46uv run "$SKILL_DIR/scripts/analyze_vault_graph.py" "." --top 2047```4849The script outputs JSON to stdout with:50- `summary`: total notes, edges, orphans, density, clustering coefficient51- `top_pagerank`: most influential notes52- `top_betweenness`: bridge concepts connecting clusters53- `top_in_degree`: most referenced notes54- `top_out_degree`: most connecting notes55- `orphans`: notes with zero links in/out56- `dead_ends`: notes referenced but linking nowhere57- `clusters`: connected components with dominant types58- `missing_links`: wikilinks pointing to non-existent notes59- `type_distribution`: counts by note type60- `status_distribution`: counts by processing status6162Requires `uv` installed (`brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`). Dependencies auto-install on first run.6364## Stage 2: INTERPRET WITH AGENT6566Read the agent definition from `agents/graph-analyst.md` in the skill directory.6768Launch the analyst agent:6970```71Agent(72 subagent_type="general-purpose",73 model="sonnet",74 run_in_background=false,75 prompt="You are Graph Analyst. Follow these instructions exactly:7677 [INSERT FULL CONTENT OF agents/graph-analyst.md HERE]7879 VAULT CONTEXT:80 - This is a Zettelkasten-style Obsidian vault81 - Note types: term (atomic concepts), thought (original synthesis),82 paper/post/book (sources), note (explanations), decision-log83 - Tags are inline (#topic), not frontmatter84 - Cross-domain connections are the vault's highest-value links8586 GRAPH ANALYSIS RESULTS:87 [INSERT JSON OUTPUT FROM STAGE 1 HERE]8889 Produce your analysis following the Output Format specified above."90)91```9293## Stage 3: PRESENT RESULTS9495Present the agent's analysis to the user. Include:961. The health score and top findings972. Specific bridge concepts and orphans983. Missing notes worth creating994. Suggested new connections100101If the user wants to ACT on suggestions (create notes, add links), help them102do so using standard vault tools (Edit, write_note, etc.).103104</Steps>105106<Tool_Usage>107- **Bash**: Run analyze_vault_graph.py script108- **Read**: Read agent definition from agents/graph-analyst.md109- **Agent**: Delegate interpretation to graph-analyst (sonnet)110- **TodoWrite**: Report progress at each stage111- **Grep/Glob**: Follow-up searches if user wants to explore specific findings112</Tool_Usage>113114<Examples>115<Good>116User: "Show me my vault's knowledge graph health"1171. Run script → JSON with 847 notes, 2341 edges, 43 orphans1182. Agent interprets → "Your ML cluster is dense but isolated from psychology.119 [[Reinforcement Learning]] and [[Operant Conditioning]] both describe120 reward-based behavior but aren't linked."1213. Present: 5 findings, 8 bridge suggestions, 12 orphans worth connecting122</Good>123124<Good>125User: "Find orphan notes"1261. Run script → 43 orphans identified1272. Agent filters → 15 are legitimately standalone (daily notes, clippings),128 28 should be connected1293. Present prioritized list: "[[Loss Aversion]] is a term note with zero130 links — should connect to [[Prospect Theory]] and [[Pricing Psychology]]"131</Good>132133<Bad>134User: "Map my vault"135- Dumps raw JSON metrics without interpretation136- Should: Run agent to explain what the numbers MEAN137</Bad>138</Examples>139140<Escalation_And_Stop_Conditions>141- **uv not installed**: Print install command (`brew install uv`), stop142- **Vault too small** (<10 notes): Warn that graph analysis needs mass to be useful143- **Script error**: Report error, don't proceed to interpretation144</Escalation_And_Stop_Conditions>145146$ARGUMENTS
tuan3w