A single skill file captures one capability. A skill graph captures an entire domain. The difference is whether your agent can follow instructions or reason through a field.
Author: James Phoenix | Date: March 2026
The Problem
Skills today are flat. One file, one capability. A skill for summarizing. A skill for code review. A skill for deployment. Each is self-contained, each lives in isolation, and each works fine for simple tasks.
But some domains resist compression into a single file. Consider a therapy skill. It needs cognitive behavioral patterns, attachment theory, active listening techniques, emotional regulation frameworks, and the connections between them. A trading skill needs risk management, market psychology, position sizing, technical analysis. A legal skill needs contract patterns, compliance requirements, jurisdiction specifics, precedent chains.
None of these fit in one file. The knowledge is too interconnected, too deep, and too relational. Flattening it into a monolithic SKILL.md either explodes context with everything upfront or loses the connections that make the knowledge useful.
The Insight: Skills as Graphs
A skill graph is a network of skill files connected with wikilinks. Instead of one large file, you have many small composable pieces that reference each other. Each file is one complete thought, technique, or claim. The wikilinks between them create a traversable graph.
This is the Zettelkasten principle applied to agent context: atomic notes with meaningful connections, where the structure itself carries information.
Traditional Skill:
SKILL.md (one file, one capability)
Skill Graph:
index.md
├── <a href="/posts/risk-management/">risk management</a> ── <a href="/posts/position-sizing/">position sizing</a>
├── <a href="/posts/market-psychology/">market psychology</a> ── <a href="/posts/emotional-regulation/">emotional regulation</a>
├── <a href="/posts/technical-analysis/">technical analysis</a> ── <a href="/posts/pattern-recognition/">pattern recognition</a>
└── connections between all of them
The key properties that make this work:
-
Wikilinks read as prose. They carry meaning, not just references. When a node says “this technique works because spreading activation reduces search cost,” the agent knows why it should follow that link.
-
YAML frontmatter enables scanning. Every node has a description the agent can evaluate without reading the full file. Most routing decisions happen at the metadata level.
-
Maps of Content (MOCs) organize clusters. When the graph gets large, MOCs group related nodes into navigable sub-topics. They act as intermediate entry points.
-
Depth is unbounded. Skill links to other skills which link to other skills. The graph goes as deep as the domain requires.
How Progressive Disclosure Works in a Skill Graph
This is progressive disclosure applied recursively inside the graph itself. The agent doesn’t load the entire graph. It navigates it.
Level 1: Index file (always loaded)
↓ agent reads descriptions, follows relevant links
Level 2: MOCs for relevant sub-topics
↓ agent identifies specific nodes
Level 3: Individual skill nodes
↓ agent follows inline wikilinks only when needed
Level 4+: Deep reference nodes
Most decisions happen before reading a single full file. The agent scans the index, understands the landscape, and follows the links that matter for the current conversation. Irrelevant branches are never loaded.
This is the same discovery pattern used at every level. The index points to MOCs. MOCs point to nodes. Nodes point to deeper nodes. The pattern is recursive and self-similar.
What a Skill Graph Looks Like
The Index (Entry Point)
The index is not a lookup table. It is an entry point that directs attention.
# knowledge-work
Agents need tools for thought too. Just as Zettelkasten, evergreen notes,
and memory palaces gave humans external structures to think with,
agent-operated knowledge systems give agents external structures to think with.
## Synthesis
Developed arguments about how the pieces fit together:
- <a href="/posts/the-system-is-the-argument/">the system is the argument</a> - philosophy with proof of work; every note,
link, and MOC demonstrates the methodology it describes
- <a href="/posts/coherent-architecture-emerges-from-wiki-links/">coherent architecture emerges from wiki links</a> - the foundational triangle
that answers what structure looks like, why it works, how agents navigate it
## Topic MOCs
The domain breaks into seven interconnected areas:
- <a href="/posts/graph-structure/">graph structure</a> - how wiki links, topology, and linking patterns create
traversable knowledge graphs
- <a href="/posts/agent-cognition/">agent cognition</a> - how agents think through external structures: traversal,
sessions, attention limits
- <a href="/posts/discovery-retrieval/">discovery retrieval</a> - how descriptions, progressive disclosure, and search
enable finding and loading content
- <a href="/posts/processing-workflow/">processing workflow</a> - how throughput, sessions, and handoffs move work
through the system
A Single Node (One Complete Thought)
Each node is a standalone claim or technique. It contains enough context to be useful on its own, but its wikilinks connect it to the broader graph.
---
name: spreading-activation-reduces-search-cost
description: >
Wiki links enable spreading activation where reading one node primes
related nodes for retrieval, reducing the search space the agent
must explore.
---
# Spreading Activation Reduces Search Cost
When an agent reads a node about <a href="/posts/risk-management/">risk management</a>, the inline links to
<a href="/posts/position-sizing/">position sizing</a> and <a href="/posts/drawdown-limits/">drawdown limits</a> are already primed in context.
The agent doesn't search the whole graph. It follows the paths that the
node's prose has already surfaced.
This mirrors how <a href="/posts/progressive-disclosure-context/">progressive disclosure</a>
works at the file system level, but operates within the knowledge structure
itself. The graph's topology does the filtering.
The wikilinks inside the prose tell the agent when and why to follow them. “This works because X” is both an explanation and a navigation instruction.
Maps of Content (MOCs)
MOCs organize sub-topics when the graph gets larger. They sit between the index and individual nodes.
---
name: agent-cognition
description: >
How agents think through external structures. Covers traversal patterns,
session management, attention limits, and cognitive load.
---
# Agent Cognition
## Core Claims
- <a href="/posts/spreading-activation-reduces-search-cost/">spreading activation reduces search cost</a> - why linked knowledge is
cheaper to retrieve than searched knowledge
- <a href="/posts/attention-limits-shape-graph-depth/">attention limits shape graph depth</a> - practical constraints on how
deep an agent can traverse before context fills
## Sub-topics
- <a href="/posts/agent-cognition-hooks/">agent cognition hooks</a> - hook enforcement, composition, and
cognitive science of automated quality
- <a href="/posts/agent-cognition-platforms/">agent cognition platforms</a> - platform capability tiers, abstraction
layers, context file architecture
Why This Matters for Agent Architecture
From Instructions to Understanding
A single skill file gives an agent instructions. A skill graph gives it understanding. The difference is structural.
With a flat skill file, the agent knows: “When the user asks about risk, apply these rules.” With a skill graph, the agent knows: “Risk management connects to position sizing, which connects to portfolio theory, which connects to drawdown limits. The user’s question about risk is really about whether their position sizing accounts for correlation.”
The graph enables the agent to reason across connections rather than pattern-match against a single document.
Token Efficiency Through Structure
A 250-file skill graph sounds expensive. It is not. The agent loads the index (~200 tokens), scans relevant MOC descriptions (~100 tokens each), and reads only the 2-3 nodes that matter for the current task (~500 tokens each). Total context loaded: ~1500 tokens from a knowledge base that contains 100,000+ tokens of domain expertise.
Full graph: ~250 files, ~100,000 tokens total
Loaded per task: ~5 files, ~1,500 tokens
Efficiency: 98.5% of knowledge available without loading
This is progressive disclosure at its most aggressive. The graph structure itself acts as the filtering mechanism.
Composability Across Domains
Skill graph nodes are composable. A node about “emotional regulation” in a therapy graph might link to a node about “position sizing psychology” in a trading graph. Cross-domain connections emerge naturally through wikilinks.
This is impossible with monolithic skill files. Each file is a silo. Graphs connect silos.
Building a Skill Graph
The Easy Way
Heinrich’s arscontexta Claude Code plugin automates the structure. Pick a research preset, point it at a topic, and it sets up the markdown folder structure. Then fill it with iterative research and synthesis passes.
The Manual Way
A skill graph does not need to live in .claude/skills/. The key requirement is an index file that tells the agent what exists and how to traverse it. The rest follows from three primitives:
-
Markdown files with YAML frontmatter. Each file has a
nameanddescriptionthat the agent can scan without reading the body. -
Wikilinks woven into prose. Not reference lists at the bottom. Links inside sentences that carry semantic meaning about when and why to follow them.
-
An index that directs attention. Not a flat list. A structured entry point that organizes the graph into navigable sections with descriptions.
The folder structure:
my-skill-graph/
├── index.md # Entry point
├── synthesis/ # Cross-cutting arguments
│ ├── core-argument-one.md
│ └── core-argument-two.md
├── topic-a/ # MOC + nodes
│ ├── index.md # MOC for this topic
│ ├── claim-one.md
│ └── claim-two.md
├── topic-b/
│ ├── index.md
│ ├── claim-three.md
│ └── claim-four.md
└── explorations/ # Open questions
└── missing-comparison.md
Connection to Existing Patterns
Skill graphs are not a new primitive. They combine several patterns already proven in agent context engineering.
Progressive disclosure provides the layering: index, MOC, node, deep reference. Each level loads only when needed. See Progressive Disclosure for the general pattern.
Hierarchical context provides the organizational principle: knowledge distributed across directory levels, loaded based on scope. See Hierarchical Context Patterns for how CLAUDE.md files work the same way.
Agent skill bootstrapping provides the growth mechanism: agents can extend skill graphs by adding new nodes when they discover gaps. See Agent Skill Bootstrapping for the self-extension pattern.
GraphRAG provides the retrieval model: semantic search finds entry points, then graph traversal expands context along meaningful edges. See GraphRAG for Production Agents for the enterprise-scale version of this idea.
Institutional memory provides the persistence model: learning files capture decisions and rationale, skill graphs capture domain knowledge. Both prevent re-derivation of known answers. See Institutional Memory via Learning Files.
The insight is that all of these patterns work together. A skill graph is a hierarchical, progressively-disclosed, graph-traversable knowledge structure that agents can extend over time.
Where Skill Graphs Apply
| Domain | What the Graph Contains |
|---|---|
| Trading | Risk management, market psychology, position sizing, technical analysis, each linked to related concepts |
| Therapy | CBT patterns, attachment theory, active listening, emotional regulation, with cross-references between approaches |
| Legal | Contract patterns, compliance requirements, jurisdiction specifics, precedent chains, all traversable from one entry point |
| Company knowledge | Org structure, product knowledge, processes, onboarding context, culture, competitive landscape |
| Engineering domain | Architecture decisions, system design patterns, failure modes, operational runbooks, connected through dependency links |
The common thread: domains where knowledge is relational and depth matters more than breadth. If your domain fits in one file, use one file. If it doesn’t, build a graph.
Risks
Graph Bloat
Adding nodes is easy. Maintaining connections is harder. Without periodic pruning, the graph accumulates orphaned nodes that nothing links to and stale claims that no longer hold.
Mitigation: Treat the graph like code. Review new nodes. Check that wikilinks resolve. Remove dead nodes.
Navigation Failure
If the index is poorly structured or node descriptions are vague, the agent wanders. It follows irrelevant links, loads unnecessary context, and burns tokens without reaching useful knowledge.
Mitigation: Descriptions must be specific enough for the agent to decide relevance without reading the full node. Index structure must reflect the domain’s actual topology, not an arbitrary categorization.
Over-Engineering Simple Skills
Not everything needs a graph. A deployment checklist is fine as a single file. A code review prompt works flat. The threshold for a graph is: multiple interconnected concepts where the connections carry meaning.
Mitigation: Start with a single skill file. Upgrade to a graph only when you find yourself wanting to reference concepts that live in other skill files or when a single file exceeds ~2000 tokens and covers multiple distinct sub-topics.
Key Insight
Skills are context engineering: curated knowledge injected where it matters. Skill graphs are the next step. Instead of one injection, the agent navigates a knowledge structure, pulling in exactly what the current situation requires.
This is the difference between an agent that follows instructions and an agent that understands a domain. The graph is the understanding.
Related
- Progressive Disclosure – The layering pattern that skill graphs apply recursively
- Hierarchical Context Patterns – Distributed knowledge across directory levels
- Agent Skill Bootstrapping – Agents that extend their own skill graphs
- GraphRAG for Production Agents – Graph-structured retrieval at enterprise scale
- Institutional Memory via Learning Files – Persistent decision tracking that complements domain knowledge graphs
- Information Theory for Coding Agents – Why structured traversal beats flat retrieval for signal efficiency
- Agent Memory Patterns – Memory primitives that skill graphs build on
References
- Heinrich (@arscontexta): Skill Graphs > SKILL.md – Original thread describing the skill graph pattern (February 2026)
- arscontexta Claude Code Plugin – Plugin that automates skill graph creation for knowledge systems
