openbitfun/skill_tree

---

😩 The problem

Skills are great — until you have a lot of them. Every SKILL.md your agent can see has to be loaded or scanned on every turn. The more capabilities you add, the worse it gets:

• 🧠 Context bloat — dozens of full skill files compete for the window
• 🎯 Worse routing — the agent must read everything before deciding what to use
• 💸 Higher cost & latency — you pay for tokens you never needed this turn

BEFORE — flat skills, all loaded every turn
.claude/skills/
├── web-dev/SKILL.md        ┐
├── data-pipeline/SKILL.md  │
├── pdf-tools/SKILL.md      ├──▶  everything in context  ──▶  🧠💥 bloat
├── seo-audit/SKILL.md      │
└── …20 more/SKILL.md       ┘

✨ The solution

Skill Tree Generator restructures your skills into a tree of tiny routing files (ROOT.md → ROUTER.md → leaf SKILL.md). The agent reads a small routing table first, narrows down branch by branch, and loads only the leaves it needs — never the whole catalog.

AFTER — a routing tree, leaves loaded on demand
.claude/skills/my-tree/
├── ROOT.md             ◀── agent reads this first (a tiny routing table)
│      └─ narrows to one branch…
├── web-dev/ROUTER.md   ◀── …then one sub-branch…
│      └─ frontend/SKILL.md   ◀── ✅ this leaf is loaded on demand
└── data-pipeline/ROUTER.md

---

🌳 How it works

The agent follows a routing protocol before answering: read ROOT.md, match the intent, descend through ROUTER.md files, stop at the [LEAF NODE](s) it needs, and execute those — and only those. A focused prompt lands on a single leaf; a multi-intent or cross-domain prompt fans out to every matched leaf and reads them in parallel — you’re never locked to one branch.

flowchart TD
    P["💬 User prompt(single- or multi-intent)"] --> ROOT["ROOT.mdL1 routing table"]
    ROOT -->|frontend signals| R1["web-dev/ROUTER.mdL2 routing"]
    ROOT -->|data signals| R2["data/ROUTER.md"]
    R1 -->|match| L1["frontend/SKILL.md🍃 leaf · loaded on demand"]
    R1 --> L2["styling/SKILL.md 🍃"]
    R2 -->|match| L3["etl/SKILL.md🍃 also fires when intent spans both"]
    style L1 fill:#1f883d,color:#fff
    style L3 fill:#1f883d,color:#fff

It works in three modes:

---

🚀 Quickstart (≈60 seconds, Claude Code)

# 1. Put the generator into your skills directory
cp -r skill-tree-generator .claude/skills/

# 2. Scan your skills — this prints the exact command to run
./scripts/aggregate-skills.sh .claude/skills

Then paste the printed /skill-tree-generator … command into Claude Code. That’s it.

You get:

• 🌳 A skill tree at .claude/skills/{name}-tree/
• 📌 The routing protocol appended to your root CLAUDE.md (created if missing)

---

👀 See it in action

Run the generator on your skills, and you get a self-contained tree like this:

my-tree/
├── ROOT.md                     # L1: routing table (the entry point)
├── SKILL-TREE.md               # human-readable overview + capability map
├── GENERATION-REPORT.md        # evidence of how the tree was built
│
├── web-dev/
│   ├── ROUTER.md               # L2: narrows within the module
│   └── frontend/SKILL.md       # 🍃 [LEAF NODE] — the actual instructions
│
├── data-pipeline/
│   └── ROUTER.md
│       └── etl/SKILL.md        # 🍃 [LEAF NODE]
│
├── shared/                     # capabilities common to several skills (deduped)
│   └── export/SKILL.md         # 🍃 used by web-dev + data-pipeline
│
└── cross-cutting/
    └── SKILL.md                # multi-skill workflows (pipelines, combos)

…and a ROOT.md whose job is simply to point the agent at the right branch:

# My Domain Routing Protocol [MANDATORY]

## Step 1: L1 routing
| Task category        | Route to                          |
|----------------------|-----------------------------------|
| Frontend / UI        | Read `web-dev/ROUTER.md`          |
| Data / pipelines     | Read `data-pipeline/ROUTER.md`    |
| Export / reporting   | Read `shared/export/SKILL.md`     |

## Step 2: recurse until you hit a file marked [LEAF NODE], then execute it.

---

🎁 Features

• 🌱 Three modes — generate from one skill, aggregate many, or update a tree in place
• 🔌 Multi-agent — Claude Code, Codex CLI, OpenCode, OpenClaw, Bitfun, Hermes & any AGENTS.md reader
• 🍃 Load on demand — only the matched leaves enter context, never the whole catalog
• 🪢 Multi-leaf routing — a multi-intent prompt fans out to every matched leaf in parallel; you’re never locked to a single branch
• 🧩 Shared-capability dedup — overlapping abilities across skills collapse into one shared leaf
• 🔗 Cross-cutting workflows — multi-skill pipelines are first-class, not afterthoughts
• 📦 Self-contained leaves — no dangling external references; every leaf stands alone
• 🔍 Optional routing trace — say “debug routing” to watch which node actually fired
• ✅ Strict validation — coverage, reachability & content-preservation checks on every build
• 📚 Battle-tested — 16 documented lessons learned baked into the rules
• 🪶 Zero dependencies — pure Bash + Markdown, nothing to install

---

🤖 Supported agents & paths

Any other agent that reads AGENTS.md (Cursor, Aider, Jules…) works the same way.

---

📟 Calling the skill directly

# 1. Single skill → tree
/skill-tree-generator 

# 2. Multiple skills → one cross-domain tree
/skill-tree-generator --aggregate skill1,skill2,… [--domain domain-name]

# 3. Update an existing tree
/skill-tree-generator --update  --add 

---

💡 Tips

1. Make sure your memory file (e.g. CLAUDE.md) sits at the repo root and contains the routing protocol (template: skill-tree-generator/references/validation_template.md, Check 1).
2. After generating the tree, clear the other loose skills from your skills dir — it makes it much easier to confirm the tree is doing the routing.
3. Run a real task or prompt and check that routing “fires” the skill node you expected.

🔍 Routing trace (optional)

Include “debug routing” / “路由追踪” in your prompt to turn on trace mode — the agent prints which node it routed to, so you can verify the tree actually reached the right leaf. By default trace is off and the agent just executes.

---

🗂️ Project structure

---

🧪 Status

⚠️ Research Preview. APIs, file layouts, and routing conventions may change. Feedback and issues are very welcome.

🤝 Contributing

PRs and ideas are welcome — see CONTRIBUTING.md. If you hit a routing edge case, the lessons learned doc is the best place to capture it.

📄 License

MIT © Skill Tree Generator contributors