Skill Distiller
Turn successful workflows into reusable skills — automatically.
Inspired by Hermes Agent's learning loop, but with quality gates to prevent skill bloat.
When to Distill
Not every task deserves a skill. Evaluate these three criteria:
All three must be YES to proceed:
- Novel? — Did this task require a workflow you haven't done before? (If you already have a skill for this, update it instead of creating a new one)
- Successful? — Did the task complete with verified results? (Failed tasks produce lessons, not skills — write to memory/lessons-learned.md instead)
- Reusable? — Will this exact workflow likely be needed again? (One-off tasks don't need skills)
Quick scoring:
Novel + Successful + Reusable = CREATE SKILL
Novel + Successful + One-off = WRITE TO MEMORY (lesson learned, not a skill)
Novel + Failed = WRITE TO LESSONS-LEARNED
Not Novel = UPDATE EXISTING SKILL (or skip)
Distillation Process
Step 1: Extract the Workflow
Look back at what you just did and identify:
- Trigger: What kind of request started this? (pattern, not specific instance)
- Steps: What were the key steps, in order?
- Tools: Which tools were used and how?
- Decisions: What non-obvious choices were made and why?
- Gotchas: What almost went wrong or required retry?
Step 2: Generalize
Transform the specific instance into a reusable pattern:
- Replace specific file names with
<input_file>, <output_path> etc.
- Replace specific content with descriptions of what goes there
- Extract magic numbers into named parameters
- Identify which steps are always needed vs. conditional
Bad (too specific):
1. Read ch10-multi-agent-comm-patterns.md
2. Convert markdown to docx using python-docx
3. Upload to feishu folder nodcnxdXVfsiCVDuiigFVpnCPoc
Good (generalized):
1. Read source markdown file(s)
2. Convert to docx using python-docx (see references/docx-patterns.md)
3. Upload to target feishu folder
Step 3: Write SKILL.md
Generate the skill following the standard format:
---
name: <slug>
description: "<when to use this skill — be specific about triggers>"
---
# <Skill Name>
## When to Use
<1-2 sentences on the trigger pattern>
## Workflow
<Numbered steps — the core of the skill>
## Key Decisions
<Non-obvious choices and their rationale>
## Gotchas
<Things that can go wrong and how to handle them>
## References
<Links to detailed docs if needed>
Size target: SKILL.md body should be under 200 lines. If longer, split into SKILL.md (workflow) + references/ (details).
Step 4: Quality Check
Before saving, verify:
Step 5: Save and Register
Save to ~/.openclaw/skills/<slug>/SKILL.md.
If the skill has reference materials, save them to ~/.openclaw/skills/<slug>/references/.
After saving, verify the skill loads:
ls ~/.openclaw/skills/<slug>/SKILL.md
Automatic Distillation Mode
When integrated with trinity-harness's Layer 3 (Compound), distillation happens automatically:
- Task completes → Layer 3 Compound phase triggers
- Evaluate Novel + Successful + Reusable
- If all YES → run distillation process
- If NO → write lesson to memory instead
- Announce to user: "Distilled skill: <name>. Review with
read ~/.openclaw/skills/<slug>/SKILL.md"
Never auto-distill silently. Always announce what was created so the user can review, edit, or delete.
Skill Maintenance
Update vs. Create
Before creating a new skill, check if a related one exists:
ls ~/.openclaw/skills/ | grep -i <keyword>
If a similar skill exists, update it (add the new pattern as a variant) rather than creating a near-duplicate.
Pruning
Periodically (during Dream Task), review skills:
- Skills unused for 30+ days → candidate for archival
- Skills with overlapping triggers → merge
- Skills that have been superseded → mark deprecated
Anti-Patterns
| Don't | Why | Do Instead |
|---|
| Distill every task | Skill bloat, noise drowns signal | Apply the 3-question gate |
| Include conversation history | Wastes tokens, not reusable | Extract only the workflow pattern |
| Write vague gotchas | "Be careful" helps no one | Specific: "API X returns 429 after 3 concurrent requests" |
| Hardcode paths/names | Not portable | Use <parameter> placeholders |
| Skip quality check | Garbage skills waste future context | Always verify before saving |
Integration with Memory System
Distillation complements, not replaces, the memory system:
| Output | Goes to | When |
|---|
| Reusable workflow | ~/.openclaw/skills/<slug>/SKILL.md | Novel + Successful + Reusable |
| Lesson learned | memory/lessons-learned.md | Successful but one-off, or failed |
| Quick note | memory/YYYY-MM-DD.md | Routine observations |
| Core insight | MEMORY.md | Fundamental principle change |
