AGENT SKILL

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

sancovp
sancovp/chaincompiler

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.

★ 0
sancovp
sancovp/chaincompiler

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).

★ 0
sancovp
sancovp/chaincompiler

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).

★ 0
sancovp
sancovp/chaincompiler

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).

★ 0
sancovp
sancovp/chaincompiler

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).

★ 0
sancovp
sancovp/chaincompiler

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).

★ 0