skilltree
WHAT: turn a flat .claude/skills folder (or any folder of skills) into a walkable coordinate-addressed tree so the model loads one layer at a time instead of the whole pile - the skilltree CLI (discover, cohere, emit, unemit, map, search, fold, project, validate, watch). WHEN: when the user mentions skilltree, skill tree, too many skills, skills all load at once, organize/structure my skills, progressive disclosure for skills, tree-ify a flat skills folder, or a skills folder has grown past the point where tool selection degrades (any of).
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- skilltree
- description
- WHAT: turn a flat .claude/skills folder (or any folder of skills) into a walkable coordinate-addressed tree so the model loads one layer at a time instead of the whole pile - the skilltree CLI (discover, cohere, emit, unemit, map, search, fold, project, validate, watch). WHEN: when the user mentions skilltree, skill tree, too many skills, skills all load at once, organize/structure my skills, progressive disclosure for skills, tree-ify a flat skills folder, or a skills folder has grown past the point where tool selection degrades (any of).
03 SKILL.md 正文
skilltree — walk the tree, never load the pile
The problem this solves: the platform auto-loads .claude/skills one layer
deep, so at scale EVERY skill lands in context EVERY turn and tool selection
degrades. skilltree imposes a coordinate-addressed tree on that flat substrate
using the three levers the runtime leaves open: path = coordinate
(0 -> 0.1 -> 0.1.1), depth = gate (a nested .claude never auto-loads,
so deeper nodes stay out of context until entered), Read = edge (the Read
tool injects a directory's layer; a shell cat injects nothing).
Setup (you do this yourself — the user never touches pip)
Check, and install if missing:
skilltree --help >/dev/null 2>&1 || pip install agent-skilltree
The commands
| Command | What it does |
|---|---|
skilltree tree <root> |
show the coordinate tree on disk |
skilltree cohere <root> |
report drift between reality and the coherent shape (a bare forest, stale breadcrumbs, flat drops) |
skilltree emit <root> [--root-forest] [--localize] |
re-cohere in place; --root-forest tree-ifies a flat forest (lossless — every move journaled); breadcrumbs portable unless --localize |
skilltree relink <root> [--localize] |
rewrite only the breadcrumb paths: portable (relative to each node's folder — what you commit and ship) or absolute for this machine (--localize, after installing a tree) |
skilltree unemit <root> |
reverse the last emit, byte-for-byte |
skilltree map <folder> [--write] |
render ANY flat folder as one coordinate-addressed index (progressive disclosure over a pile) |
skilltree search <folder> <query> [--scope <coord>] |
FTS5/BM25 retrieval; --scope restricts to a coordinate subtree |
skilltree fold <framework_dir> --into <node> --tree <root> |
bind a framework into a volume node's tome table (idempotent) |
skilltree project <root> <target> [--policy flat|progressive] |
deploy a tree into a skills dir as symlinks |
skilltree validate <root> |
gate: every breadcrumb must resolve |
skilltree watch <root> |
the decoherence cron — a drifted tree announces itself |
The one law that makes descent work
Breadcrumbs instruct you to use the Read tool on a child's SKILL.md — that
injects the child's layer. A shell cat of the same file injects NOTHING (the
bytes arrive, the skill does not load). Never descend with cat.
The lowest-cost first run (on the user's own skills)
skilltree cohere ~/.claude/skills # see the drift before changing anything
skilltree emit ~/.claude/skills --root-forest # tree-ify (reversible: unemit)
Going deeper
The full mechanics (verified runtime table, file geometry, invariants, source
path:line map) are in SkillTree's own repository, github.com/sancovp/skilltree:
README.md, papers/skilltree-paper.md and papers/flat-vs-tree.md. This file is a
copy of that repository's skills/skilltree/SKILL.md, kept for agents working here.
04 同仓库更多 Skills
skill2framework
Turn an already-built AIOS/package into a framework chapter — narrative blog + deep-dive blog → chapter → {aios}-volume index skill → plugin → folded into the author's SkillTome.
package-plugin
WHAT: package a framework as a Claude Code PLUGIN (its operational face) — run skill2framework.package_plugin to assemble plugin.json + skills/{aios}-volume/SKILL.md + the chapter bundled under resources/, with the skill's chapter links repathed to the bundle. WHEN: when a framework skill + chapter exist and need the installable plugin, or when the user says package the framework / plugin / skill2framework (any of).
narrative-blog
WHAT: produce Blog 1 of a framework CHAPTER — the narrative chapter-opener — for an already-built AIOS/package by reconstructing its journey from its own dir (CLAUDE.md, README, dev log) and FILLING skill2framework.JourneyCore, then rendering with render_blog1 (never hand-write the blog). WHEN: when making a framework/chapter from something already built, when you need the story post that opens a chapter, or when the user says blog organ / narrative blog / skill2framework (any of).
framework-skill
WHAT: generate the FRAMEWORK SKILL for an already-built AIOS — the {aios}-volume (its SkillVolume face): one skill that indexes the AIOS's skills + rules + how they relate (as a diagram), gives a decision tree for what to do when, and ROUTES the agent into the AIOS dir. WHEN: when producing the index/router face of a framework package, or when the user says framework skill / volume / skill2framework (any of).
fold-into-tome
WHAT: the TERMINAL stage — fold a finished framework into the author's SkillTome (the top-level holder + search of all their frameworks) by running skill2framework.fold_into_tome, which registers the framework as a row on a tome volume node's generated ## Frameworks table via skilltree's bind op. WHEN: when a framework package is finished and must be registered in the author's tome/volume, or when the user says fold into the tome / nomicon / skill2framework fold (any of).
deepdive-blog
WHAT: produce Blog 2 of a framework CHAPTER — the mechanical deep-dive ('how it actually works') — for an already-built AIOS/package by reading its impl docs (README architecture sections, design docs, the code's module docstrings) and assembling a faithful mechanics-only article that links back to Blog 1. WHEN: when producing the deep-dive half of a chapter, when you need the technical how-it-works post Blog 1 links to, or when the user says blog 2 / deep dive / skill2framework (any of).