July 2026Level 3 · Context Skills

skilltree — the story

My skills all loaded at once every turn — so I stopped loading the pile and learned to walk it one layer at a time.

Where I was

I was watching my skill library grow past a hundred skills, and the platform auto-loads .claude/skills one layer deep — so every skill landed in context every single turn. At a handful of skills that is fine; at a hundred it is melt: the whole pile lands in context every turn, and tool selection degrades as the set grows. The substrate ships the nodes and forbids the edge.

The wall

I identified the real blocker when I looked at what the platform actually allows: a .claude nested inside another .claude never loads, and a skill's description can point at another skill but cannot cause that deeper skill to be injected. There is no first-class skill-to-skill edge. 'Progressive disclosure' was named for a tree but shipped as a star — one center, depth-one leaves, no descent — and a set of stars with no connecting edges is a flat forest, exactly at the scale where disclosure was the point.

The turn

I finally stopped fighting the substrate and used the only three levers it leaves open. Placement: each node is a plain directory carrying its own one-skill .claude/, so the path is the coordinate (0 -> 0.1 -> 0.1.1). The inert-nested-.claude boundary: only the top layer auto-loads, so deeper nodes stay out of context until entered. And breadcrumbs: each node's SKILL.md ends with a summary of its subtree plus an explicit instruction to Read its children — because in this runtime the Read tool injects that layer while a shell cat injects nothing. I built the CLI around it — discover, cohere, emit/unemit, map, search, fold, project, validate, watch.

Where I am now

And now I load one layer and walk; I never load the pile. The v1 tree ships: the Read-breadcrumb descent, the front-half self-coherence loop, the decoherence watch. It keeps itself coherent — discover reconstructs the tree from reality, cohere reports drift, emit tree-ifies a flat forest losslessly (journaling every move) and unemit reverses it byte-for-byte. The load mechanic was verified against the live runtime, not asserted, and the whole thing is held by a passing suite (70 tests as of v0.3.0).

The boon — what transfers

The transferable reframe is this: the relational structure a model needs to use its skills correctly already exists in the library — it is a fact about the skills, not about how they are stored — and a flat list discards it, forcing the model to reconstruct it on every task. When you expose an object in a shape that violates its natural structure, everyone downstream spends inference, tokens, tool calls, and harness code recovering the structure the interface destroyed. So front-load the structure, not the corpus.

See it

A demo points skilltree at a flat folder of skills and shows: discover reconstructing the on-disk tree; cohere flagging it as a bare forest; emit --root-forest tree-ifying it in place (each skill directory moved whole, every move journaled); walking it one layer at a time by Reading a child's SKILL.md; search --scope 0.1 ranking only within a coordinate subtree; and unemit restoring the original flat forest byte-for-byte.

Why this matters

These tools are not products, they are infrastructure: a population of builders stands on the platform's defaults, so a default that mis-shapes context is not one team's cost but a levy paid across every project, continuously. And the skill format is no longer one vendor's default — it has been released as an open standard and adopted across major agent platforms, so the gap it leaves is shared at the reach of the standard.

Take action

Point skilltree at your OWN flat .claude/skills (or any folder of skills): run cohere to see the drift, emit --root-forest to tree-ify it in place (reversible with unemit), and then descend it one layer at a time instead of loading the whole pile. map renders any flat folder as one coordinate-addressed index and search retrieves over it — so the structure your skills already have becomes something you navigate instead of reassemble.

Chapter links

Deep dive — how it works
Get the plugin: https://pypi.org/project/agent-skilltree/
Skill — skilltree CLI: https://pypi.org/project/agent-skilltree/

Install the plugin and run it yourself: https://pypi.org/project/agent-skilltree/