maipianworni/skilltree/skill-tree-generator

Skill Tree Generator

Usage

/skill-tree-generator <skill-name-or-skill-path-or-description>
/skill-tree-generator --aggregate skill1,skill2,... [--domain domain-name] [--no-decompose]
/skill-tree-generator --update <tree-path> --add <skill>

可选 flag：

Overview

Transform monolithic skills into modular, hierarchical skill-trees (ROOT.md → ROUTER.md → SKILL.md) with dynamic routing. Use when:

• A skill has grown too complex and needs modularization
• Multiple distinct workflows exist within a single skill
• Multiple related skills need to be unified under one routing tree
• Cross-domain workflows span multiple skills
• Overlapping capabilities across skills need deduplication
• An existing skill-tree needs new skills or capabilities added

Strict Conformance

Before creating or modifying tree output, read and follow references/strict_conformance.md. Do not use substitute workflows, fast versions, heuristic-only splitting, or partial validation. If full conformance is impractical, stop and report the blocker before continuing.

Mode 1: Single Skill Tree Generation

Generate a routing tree for a single skill.

Input: Skill path or description Output: Complete tree structure in {skill-name}-tree/

Example:

/skill-tree-generator web-development

Mode 1 Step 1: Analyze Input Skill

First, analyze the input skill to identify:

1. Core domains - What major functional areas does the skill cover?
2. Sub-domains - Within each core domain, what sub-categories exist?
3. Leaf capabilities - What specific tasks/endpoints are at the lowest level?
4. Routing criteria - What signals distinguish one path from another?

Read the skill content:

$ARGUMENTS

If $ARGUMENTS is a file path, read that file. If it's a description, use it directly.

Mode 1 Step 2: Design Tree Structure

Based on analysis, design the hierarchy following these principles:

skill-tree/
├── ROOT.md                    # L1 routing protocol
├── {module1}/
│   ├── ROUTER.md              # L2 routing logic
│   ├── {submodule}/
│   │   ├── ROUTER.md          # L3 routing logic
│   │   └── {feature}/SKILL.md # Leaf node
└── {module2}/
    └── ...

Design Guidelines:

• L1 modules: Major functional domains (2-5 modules typical)
• L2 submodules: Sub-categories within each domain
• Leaf nodes: Specific, atomic tasks/capabilities
• Depth limit: 3-4 levels maximum for efficiency

Mode 1 Step 3: Generate ROOT.md

Read references/root_template.md and generate ROOT.md following the Single-Skill section template.

Mode 1 Step 4: Generate ROUTER.md Files

For each non-leaf level, read references/router_template.md and generate ROUTER.md following that template. The template's [MANDATORY] routing requirements and pre-write checklist are acceptance criteria; do not duplicate, weaken, or replace them in this workflow.

Mode 1 Step 5: Generate Leaf SKILL.md Files

前置检查: 执行 references/error_handling.md 中的 Error Severity & Handling Strategy — 源技能不可用（Fatal）则报错终止，局部缺失（Degraded）则生成回退内容。

For each leaf node, read references/leaf_template.md for the structure template. Extract the complete content from the original skill and fill it into the template. Do NOT replace any content with a file path reference or external link. Every instruction, code example, API reference, and constraint from the original skill must be inlined directly.

Source skill paths are generation-time inputs only. They may be recorded in GENERATION-REPORT.md for auditability, but leaf SKILL.md files must not tell the runtime agent to read the source skill path for full instructions. After generation, the tree must remain usable if the source skill directory is deleted or inaccessible.

引用处理: 执行 references/error_handling.md 中的 Reference File Processing Flow Step R1-R4（盘点 → 决策 → 清理 → 即时验证）。

自包含: 遵循 references/error_handling.md 中的 Self-Containment Rule，生成结果必须作为 skill tree 整体自包含；短引用内联到叶节点，大文件集必须拷贝到 tree 内并通过 tree 内部相对路径引用。

嵌套 skill 检测: 执行 references/error_handling.md 中的 Nested Skill Detection。生成前用 Glob 扫描源 skill 目录 src/<skill>/*/SKILL.md；若命中 ≥2 个，判定为嵌套（index 型）skill，在 GENERATION-REPORT.md 记录，并按两种承载方式之一处理：方式 A（路由分离型，{skill}/ROUTER.md + 入口 {skill}/SKILL.md，上游指向 ROUTER.md）或方式 B（路由内嵌型，路由表+全局约束直接承载在 {skill}/SKILL.md 标 [Ln ROUTING NODE] [NESTED SKILL SUBTREE]，不另设 ROUTER.md，上游指向 SKILL.md）。禁止方式 A 下只留 ROUTER.md 无入口 SKILL.md；禁止方式 B 下额外建只含指针的 ROUTER.md（与 SKILL.md 重复）；两种方式不得混用。

【强制】Pre-Write Content Completeness Check: 在 Write 每个叶节点之前，重新读取源 skill 文件。按叶节点类型分别执行：

• 独立叶节点（源 skill 不拆分，1 源 → 1 叶）：除 YAML frontmatter 外，源 skill 的全部内容必须逐字迁入叶节点；不接受内容损失；禁止"简化"、"概括"、"保留框架"。若因标题替换、tree 内部路径替换、引用文件拷贝等自包含处理导致行数不同，必须在 GENERATION-REPORT.md 中逐项解释差异，并确认无执行级内容丢失。
• 拆分型叶节点（1 源 → 多个子叶）：先建立 source section → leaf mapping；每个子叶包含对应章节/能力的完整内容；所有子叶合计覆盖源 skill 全部章节；若某子叶比映射到它的源段落短 >30%，必须逐段排查并修复或解释。

Mode 1 Step 6: Create Output Structure

Create all files in the target directory. Small files (≤10KB) use Write tool; large file sets (>5 files or >50KB) use staging + platform-native copy (`cp -a` on Unix/macOS, `robocopy` on Windows; `xcopy /E /I` only as last fallback) — never copy large directories file-by-file with Write. Treat `robocopy` return codes `< 8` as success.

.claude/skills/{skill-name}-tree/     # Claude Code
# or
.agent/skills/{skill-name}-tree/      # Codex CLI / other AGENTS.md-aware agents
# or
.zcode/skills/{skill-name}-tree/      # ZCode
├── ROOT.md
├── SKILL-TREE.md              # Directory structure overview
├── GENERATION-REPORT.md       # Required evidence (see Strict Conformance)
├── {module1}/
│   ├── ROUTER.md
│   └── {submodule}/
│       └── SKILL.md
└── ...

Mode 1 Step 7: Validation + Report

1. Validate: Execute every check in references/validation_template.md. Read the file and run each check sequentially — this is an executable checklist, not informational. Record pass/fail for each. If any check fails, fix the generated files and re-run that check.
2. Report: Once all checks pass, create GENERATION-REPORT.md in the tree root directory, following the Required Evidence section in references/strict_conformance.md. The validation results recorded in step 1 go into this report.

Mode 2: Multi-Skill Aggregate Tree

Generate a routing tree that covers multiple skills. Skills can be from the same domain or from different domains.

Input: --aggregate skill1,skill2,skill3 [--domain domain-name] Output: Unified tree with shared ROOT.md, each skill as a sub-tree

--domain is optional. When omitted, the tree covers cross-domain skills and ROOT.md routes by domain intent. When provided, the tree covers same-domain skills and ROOT.md routes by capability differences within that domain.

Examples:

# Cross-domain: coding + writing + security
/skill-tree-generator --aggregate web-dev,technical-writing,security-review
 
# Same-domain: frontend frameworks
/skill-tree-generator --aggregate react,vue,svelte --domain frontend

Multi-skill trees require a two-phase routing: Phase 1 selects one or more skills, Phase 2 selects one or more capabilities within each matched skill. Multi-intent prompts must preserve all matched route paths.

Mode 2 Step A: Per-Skill Capability Decomposition + Cross-Skill Collection

`--no-decompose` 快速路径：若用户传入 --no-decompose，跳过 A1 的结构化分析，对所有 skill 直接标记 decomposition decision = 单叶，然后直接执行 A2 建矩阵（每个 skill 视为单一能力组）。

A1: 逐 Skill 能力拆解（与 Mode 1 Step 1 等价）

对 --aggregate 列表中的每个 skill，读取其完整内容后执行以下结构化分析：

1. Core domains — 该 skill 覆盖哪些主要功能领域？
2. Sub-domains — 每个功能领域内有哪些子分类？
3. Leaf capabilities — 最底层的原子任务/端点是什么？
4. Routing criteria — 什么信号区分该 skill 内部的不同路径？

输出格式（每个 skill 一份）：

### Skill: {skill-name}
- Core domains: {domain1}, {domain2}, ...
- Sub-domains:
  - {domain1}: {sub1}, {sub2}, ...
  - {domain2}: {sub1}, {sub2}, ...
- Leaf capabilities:
  - {domain1}/{sub1}: {capability-a}, {capability-b}
  - {domain1}/{sub2}: {capability-c}
  - ...
- Routing criteria:
  - {capability-a} vs {capability-b}: {distinguishing signal}
  - ...
- Decomposition decision:
  - [ ] 单叶（该 skill 功能单一/原子化，不需再拆）
  - [ ] 多叶（该 skill 含 ≥2 个可独立路由的能力组，应拆为多个子叶）

Decomposition decision 判定规则：

• 若 skill 只有 1 个核心功能领域且无明显子分类 → 单叶
• 若 skill 含 ≥2 个独立的功能领域，或 ≥3 个可用不同信号区分的原子能力 → 多叶
• 已由 Nested Skill Detection 判定为嵌套 skill 的 → 必须为多叶

A2: 跨 Skill 能力比较矩阵

基于 A1 的拆解结果，将所有 skill 的 leaf capabilities 汇总为比较矩阵：

| 能力组 | Skill_A | Skill_B | Skill_C |
|--------|---------|---------|---------|
| project | ✓ create,open,save | ✓ create,save | ✗ |
| editing | ✓ add,remove,set | ✗ | ✓ add,remove |
| export  | ✓ render | ✓ export-pdf | ✓ render |
| session | ✓ undo,redo | ✗ | ✓ undo,redo |

注意：对于 A1 判定为「多叶」的 skill，矩阵中应列出其各子能力（而非将整个 skill 视为单一能力组）。

Mode 2 Step B: Shared vs Unique Classification

Classify every capability group:

Mode 2 Step C: Two-Phase Hierarchy Design

基于 Step A1 的拆解结果和 Step B 的分类，设计层级结构：

{domain}-tree/
├── ROOT.md                        # Phase 1: 选一个或多个 skill
├── SKILL-TREE.md                  # Overview with mapping table
├── GENERATION-REPORT.md           # Required evidence (see Strict Conformance)
├── {skill_a}/                     # Skill A（A1 判定单叶）
│   └── SKILL.md                   # 直接是 leaf
├── {skill_b}/                     # Skill B（A1 判定多叶）
│   ├── ROUTER.md                  # Phase 2: 选能力
│   ├── {capability1}/SKILL.md     # 子叶 1
│   └── {capability2}/SKILL.md     # 子叶 2
├── {skill_c}/                     # Skill C（A1 判定多叶）
│   ├── ROUTER.md
│   └── {capability}/SKILL.md
├── shared/                        # Shared-identical 能力
│   └── {capability}/SKILL.md      # 标注: 适用于 skill_a, skill_b
└── cross-cutting/
    └── SKILL.md                   # 跨 skill 工作流

注意：

• A1 判定为「单叶」的 skill → {skill}/SKILL.md 即为 leaf，无需 ROUTER.md
• A1 判定为「多叶」的 skill → {skill}/ROUTER.md + 多个 {capability}/SKILL.md
• 已有嵌套结构的 skill → 按 Nested Skill Detection 方式 A/B 处理

Mode 2 Step C1: Generate Skill Phase-2 Routing (per skill form)

综合 Step A1 的 Decomposition decision 和 references/error_handling.md Nested Skill Detection 判定每个 skill 的形态，决定是否生成 ROUTER.md：

形态判定输入源（两者取并集）：

1. Step A1 判定为「多叶」→ 该 skill 需要多叶结构
2. Nested Skill Detection 发现物理嵌套 SKILL.md 文件 → 该 skill 是嵌套 skill

两个条件任一满足即视为多能力 skill，需要 Phase 2 路由。

路由决策：

• 单叶 skill（A1 判定为「单叶」且无嵌套检测命中）：不生成 ROUTER.md。ROOT.md 直接路由到 {skill}/SKILL.md（即 leaf）。为单叶 skill 创建仅指向 ./SKILL.md 的 ROUTER.md 是冗余错误，禁止。
• A1 判定多叶但源为单文件（无物理嵌套）：按「拆分型」处理——生成 {skill}/ROUTER.md（Phase 2 能力路由）+ 多个子叶 {skill}/{capability}/SKILL.md。拆分依据为 A1 识别的 leaf capabilities 和 routing criteria。此情况下 Step C2 对该 skill 使用「拆分型叶节点」规则。
• 嵌套/多能力 skill 方式 A（路由分离型）：生成 {skill}/ROUTER.md（Phase 2 能力路由，路由表覆盖该 skill 所有 skill-specific / Shared-similar 叶节点）+ 入口 {skill}/SKILL.md。仅当源 SKILL.md 是纯路由表无入口/使用说明时选方式 A。
• 嵌套 skill 方式 B（路由内嵌型，源 SKILL.md 是「路由表+入口」一体文件时首选）：不生成 ROUTER.md，把路由表 + 全局约束直接承载在 {skill}/SKILL.md（标 [Ln ROUTING NODE] [NESTED SKILL SUBTREE]），上游父路由指向 {skill}/SKILL.md。