All insights
Principle AI Product Building Knowledge Systems AI Agents

Skill graphs enable progressive disclosure for complex domains

Single skill files hit a ceiling — complex domains need interconnected knowledge that agents navigate progressively from index to description to links to sections to full content

@arscontexta (Heinrich) — Twitter thread on skill graphs · · 14 connections

A single SKILL.md file is a really good book on one topic. A skill graph is a library where books reference each other. When domains get complex — therapy (CBT + attachment + regulation), trading (risk + psychology + sizing) — a monolithic file becomes unnavigable. Skill graphs solve this with progressive disclosure: the agent navigates progressively from metadata to wikilinks to specific sections to full content, loading only what’s relevant at each step.

The primitives are the same ones powering this knowledge graph: Files are the universal interface between humans and agents for the substrate, wikilinks in prose for meaningful connections, YAML frontmatter for scannable metadata, and MOCs for clustering. This is Similarity is not relevance — relevance requires reasoning applied to agent knowledge — the agent navigates by reasoning rather than searching by similarity. It extends Markdown skill files may replace expensive fine-tuning from single files to interconnected graphs, and connects to The context window is the fundamental constraint — everything else follows because progressive disclosure is fundamentally about loading only what’s relevant into a limited context window. At the market level, Domain-specific skill libraries are the real agent moat, not core infrastructure validates this architecture — when Excel AI agents were reverse-engineered, the real competitive advantage wasn’t core infrastructure but accumulated domain skill libraries that took years to build.

The same progressive disclosure works inside a single skill, as Thariq (@trq212) describes in “Lessons from Building Claude Code: How We Use Skills.” The common misconception is that skills are “just markdown files”; in practice a skill is a folder that can include scripts, assets, data and reference documents the agent discovers and reads at the step where it needs them. Split detailed API signatures into references/api.md, output templates into assets/ and helper libraries into scripts/, and keep SKILL.md as a workflow outline with pointers — the folder hierarchy becomes deliberate information architecture, not just file organization, the same move as CLAUDE.md should be a routing table, not a knowledge base.

Connected Insights

References (6)

→ The context window is the fundamental constraint — everything else follows → Domain-specific skill libraries are the real agent moat, not core infrastructure → Files are the universal interface between humans and agents → Markdown skill files may replace expensive fine-tuning → Similarity is not relevance — relevance requires reasoning → CLAUDE.md should be a routing table, not a knowledge base

Referenced by (8)

← Similarity is not relevance — relevance requires reasoning ← Tiered retrieval prevents context overload — summaries first, details on demand ← Tool design is continuous observation — see like an agent ← Context inefficiency compounds three penalties: cost, latency, and quality degradation ← Context layers supersede semantic layers for agent autonomy ← CLAUDE.md should be a routing table, not a knowledge base ← Agents need workflow-level tool strategies, not individual tool instructions — the hard part is how tools combine ← Compilation scales but curation compounds — two camps for knowledge graph construction