Skill Graph

Author Claude Skills as interlinked graphs, not monolithic SKILL.md files.

A methodology and toolkit for building Anthropic Claude Skills as modular reference networks — lean indexes, on-demand depth, validator-enforced invariants.

The problem

A monolithic SKILL.md loads everything into Claude’s context every turn — the table of contents, the rationale, the edge cases, the rarely-needed appendices, all of it. That works at 50 lines. By 500 lines it’s a tax: tokens are burned on instructions Claude doesn’t need, the signal-to-noise ratio drops, and behavior starts drifting because the model has to re-decide what’s relevant on every call.

The failure mode is structural, not stylistic. You can’t prompt-engineer your way out of a context budget.

The solution

Treat a skill like a small codebase. Split it into:

• A lean index (SKILL.md) — always loaded, kept short, contains only navigation
• Reference files — the actual depth, pulled in on demand via explicit links
• Category hubs (overview.md) — let the index point at a topic, not every leaf

Two design rules make the graph navigable:

• 2-hop reachability — every reference is reachable from SKILL.md in at most two link traversals
• No orphans — every file under references/ and scripts/ is linked from somewhere in the graph

Claude doesn’t read your whole skill. It navigates it — purposefully, one hop at a time.

Before / after

# Monolithic                          # Skill graph
skill-name/                           skill-name/
└── SKILL.md      (800+ lines,        ├── SKILL.md          (≤100 lines, index only)
                   loaded every       ├── references/
                   turn)              │   ├── core-principles/
                                      │   │   ├── overview.md     (hub)
                                      │   │   ├── conciseness.md
                                      │   │   └── decomposition.md
                                      │   ├── workflows.md
                                      │   └── output-patterns.md
                                      └── scripts/
                                          └── helper.py

Same content. The graph version loads the 80-line index every turn and pulls a single reference (≈40 lines) when relevant — typically a 5–10× reduction in always-on context.

Quickstart

The three scripts live in skill-graph-creator/scripts/:

# Scaffold a new skill graph from the template
python skill-graph-creator/scripts/init_skill_graph.py my-skill --path skills/bespoke

# Lint the graph (frontmatter, links, orphans, index size)
python skill-graph-creator/scripts/validate_graph.py skills/bespoke/my-skill