SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsskill-distill

skill-distill

Agents & models

View repository

Updated 10-16 06:22

About this skill

Skill Distill — Multi-Skill Distillation Merge

Merge N skills with overlapping functionality into 1 distilled skill.

Unlike rules extraction (a separate capability from ECC's rules-distill skill, not part of this repo) and nclandrei/distill(sessions → skills), this skill's input and output are both skills: skills → skill.

Why Distill Instead of Copy

Directly copying multiple skills into one large file is the simplest approach, but it brings three practical problems.

Tradeoff: Merging vs Simple Concatenation

Approach Advantage Cost
Simple concatenation Zero thinking cost Token bloat (duplicate content 2-3x), trigger conflicts, user confusion
Distillation merge Deduplication, disambiguation, controllable size Requires analysis and manual confirmation of conflicts

Because each skill consumes context budget when loaded, 3 skills of 200 lines each (~600 lines / ~8k tokens) after concatenation have 60%+ duplicate content, distilling into 1 skill of ~250 lines can save ~50% token overhead.

Distillation also solves the routing conflict problem: when the user says "help me optimize this text", if the triggers of the three skills human-writing, slopbuster, and humanizer all match, the agent doesn't know which one to load. After distillation there is only one entry point, and routing determinism increases from ~33% to 100%.

# Before: 3 skills with overlapping triggers
- skill: human-writing
  triggers: ["优化.*文字", "写作.*风格"]
- skill: slopbuster
  triggers: ["AI.*味", "优化.*文字", "去.*套话"]
- skill: humanizer
  triggers: ["去.*AI味", "优化.*文字"]

# After: 1 distilled skill, zero ambiguity
- skill: deslop
  triggers: ["优化.*文字", "去.*AI味", "写作.*风格", "去.*套话"]

Conflict handling is the core difficulty of distillation: when skill-A says "each paragraph must not exceed 3 sentences" and skill-B says "each paragraph 4-6 sentences", you cannot arbitrarily pick one. The conflict classification in Phase 2 will flag such contradictions, and Phase 3 hands them to the user for adjudication.

When to Use

  • 2+ skills in the same domain have overlapping functionality (e.g., multiple writing-related skills)
  • Users cannot tell which skill to use (routing conflict)
  • Want to reduce the total number of skills to lower metadata token overhead

When NOT to Use

  • Extracting cross-domain principles from skills into rules (rules extraction is a separate capability from ECC's rules-distill skill, not part of this repo）
  • Extracting recurring patterns from session history into a skill (use the distill CLI / skill-create）
  • Optimizing the quality of a single skill (use improvement-orchestrator）
  • Two skills are in different domains but happen to be used in the same project (e.g., cpp-expert + ios-expert)
  • After merging, the SKILL.md body would exceed the 500-line token budget (indicating these skills differ too much and are not suitable for distillation)

Workflow

MUST execute the 4 Phases in order. NEVER skip Phase 2 and write output directly.

Phase 1: Collection (deterministic)

Read the complete content of all source skills:

对每个源 skill:
  1. Read SKILL.md → 提取 frontmatter、body sections、example/anti-example
  2. Read references/*.md → 提取详细规则和示例
  3. 统计行数和 token 估算

Output the Inventory table:

Skill Distillation — Phase 1: Inventory
────────────────────────────────────────
Sources: {N} skills
Total content: ~{X} lines / ~{Y}k tokens

| Source | Lines | Sections | References | Unique contribution |
|--------|-------|----------|------------|-------------------|
| skill-A | 200 | 12 | 2 files | ... |
| skill-B | 280 | 15 | 5 files | ... |

Phase 2: Analysis (LLM judgment)

Perform cross-analysis on all source skill content, classifying each knowledge point into 4 types:

Category Definition Destination
Intersection Present in 2+ source skills, similarly worded Goes into body after deduplication
Unique contribution Present in only 1 source skill, but valuable Keep, goes into body or references
Conflict 2+ source skills make contradictory statements Show to the user for a decision
Redundant Can be derived from general LLM knowledge Discard (token efficiency)

MUST label the source skill for each item. NEVER mix content without labeling.

Phase 2: Cross-Analysis Result
──────────────────────────────
Knowledge Point                | Category    | Source(s)     | Destination
"两次 pass 流程"               | 交集        | A + B + C     | body §Workflow
"AI 模式清单 (Tier 1)"        | 交集        | A + B         | body §Patterns
"中文特有语气词列表"           | 独特贡献    | C only        | references/zh-patterns.md
"每段不超过 3 句" vs "4-6 句"  | 冲突        | A vs B        | → 用户裁决
"主动语态定义"                 | 冗余        | B             | 丢弃（LLM 已知）

Token budget control：

  • SKILL.md body: ≤500 lines (skill-creator specification)
  • A condensed version of the intersecting content goes into the body, the full version goes into references/
  • Evaluate whether each unique contribution is "worth the tokens"—if it is only useful in specific scenarios, put it in references/

Phase 3: User confirmation

Present the distillation plan:

# Distillation Plan

## Target: {new-skill-name}
Sources: {source list}

## Body content (~{N} lines)
- {section 1}: 交集，来自 A+B+C
- {section 2}: 独特贡献，来自 A
- {section 3}: 独特贡献，来自 B

## References
- full-xxx.md: 完整 {topic}（~{N} lines）来自 A+C
- yyy.md: {topic}（~{N} lines）来自 B

## Conflicts (需要你决定)
1. A 说 X，B 说 Y → 你选哪个？

## Dropped (冗余，LLM 已知)
- {list}

## Source skill 处理
- 保留源 skill（蒸馏版作为补充）
- 替换源 skill（删除源，只用蒸馏版）
- 降级源 skill（源 skill 的 description 指向蒸馏版）

MUST wait for user confirmation before generating files. NEVER generate automatically without confirmation.

Phase 4: Generation + Pipeline verification

Generate according to the confirmed plan:

{new-skill}/
├── SKILL.md          # body ≤500 行
└── references/       # 长尾详细内容
    ├── full-xxx.md
    └── yyy.md

After generation, MUST integrate into the improvement pipeline for verification—this is the key to the distillation loop, NEVER skip it:

Step 1: 跑 improvement-learner 评分
  python3 ~/.claude/skills/improvement-learner/scripts/self_improve.py \
    --skill-path {new-skill-path} --max-iterations 1

Step 2: 检查结果
  accuracy ≥ 0.80 → PASS，蒸馏完成
  accuracy < 0.80 → 跑 orchestrator 优化:
    python3 ~/.claude/skills/improvement-orchestrator/scripts/orchestrate.py \
      --target {new-skill-path} --state-root /tmp/skill-distill-state --auto

Step 3: (可选) 如有 task_suite.yaml → 跑 evaluator 执行验证
  python3 ~/.claude/skills/improvement-evaluator/scripts/evaluate.py \
    --standalone --task-suite {new-skill-path}/task_suites/task_suite.yaml \
    --state-root /tmp/skill-distill-eval

Even if the learner score is perfect, if there is a task_suite, the evaluator MUST still be run—a high structural score does not equal good execution results (the lesson from changelog-gen).

Distillation criteria

Signals worth distilling

  • The triggers of 2+ skills have 50%+ overlap
  • The user has been asked multiple times "use A or B"
  • The same task requires loading 2+ skills at the same time

Signals not worth distilling

  • The two skills solve problems at different stages of the process (e.g., generator vs evaluator)
  • The overlap is only at the frontmatter description level, and the body content is completely different
  • After merging, the SKILL.md body would exceed 500 lines

Harness configuration merging

If any source skill contains execution-harness configuration (Ralph state, Handoff template, Hook declaration), distill must:

  1. Merge the harness configuration into the distilled version—take the union of the patterns from all sources
  2. On conflict, take the stricter configuration (e.g., take the minimum value for max_iterations)
  3. Note the dependent harness pattern in the Related Skills section of SKILL.md

Distillation quality check

Check item Standard
No information loss Each unique contribution of the source skill has a counterpart in the distilled version
Condensed body ≤500 lines, detailed content in references/
Traceable sources Each section is labeled with which source skill it comes from
learner score accuracy ≥ 0.80
No routing conflicts triggers do not overlap with other skills
Complete harness All harness patterns of the source skills are retained

Output Artifacts

Request Deliverable Included content
Distillation New skill directory + learner score SKILL.md (≤500 lines) + references/ (long-tail content) + scoring report
Analysis Distillation plan (does not generate files) Phase 1 Inventory + Phase 2 cross-analysis + conflict list
Verification Quality report learner 6-dimension score + evaluator pass rate (if there is a task_suite)

After each distillation is completed, output an example directory structure:

deslop/                          # 蒸馏后的 skill
├── SKILL.md                     # body ≤500 行, frontmatter 含 "蒸馏自" 标注
├── references/
│   ├── full-ai-patterns.md      # 完整 AI 模式清单 (~120 行), 来自 A+B
│   ├── zh-writing-guide.md      # 中文写作特有规则 (~80 行), 来自 C
│   └── voice-calibration.md     # 语气校准参考 (~60 行), 来自 B
└── task_suites/
    └── task_suite.yaml          # 可选, 用于 evaluator 执行验证

Related Skills

Skill Relationship When to use instead
skill-creator The generation of the distilled skill follows the skill-creator specification Create a single skill from scratch
skill-forge After distillation, forge can be used to supplement task_suite Automatically generate skill + task_suite from spec
rules-distill (external, ECC) Complementary: distill merges skills, rules-distill extracts rules Need to extract general principles across skills into rules
improvement-orchestrator After distillation, connect to orchestrator for quality optimization Optimize a single skill rather than merging multiple
improvement-learner Phase 4 uses learner scoring to verify distillation quality Only need scoring, not merging
improvement-evaluator Optional execution verification in Phase 4 Verify skill execution results

References

  • Distillation decision matrix and complete checklist: references/distillation-checklist.md
  • skill-creator specification (body ≤500 lines, frontmatter format): see skill-creator skill
  • improvement-learner 6-dimension scoring description: see improvement-learner skill
  • Actual distillation case: the deslop skill was distilled from three skills: human-writing + slopbuster + humanizer