Turn real-world experience into durable skill knowledge.
When to Use
User invokes this skill after completing work that revealed a gap, pitfall, or new pattern not yet captured in an existing SKILL.md. Typical trigger: $skill-evolve @path/to/SKILL.md
Procedure
Step 1 — Gather Context
Read the referenced SKILL.md in full.
Review the current conversation to identify:
What went wrong or was discovered (the incident/finding)
Root cause (why it happened)
The fix or pattern (what the correct approach is)
Why the existing skill didn't prevent it (the gap)
Step 2 — Classify the Learning
Determine which type of update is needed:
Type
Description
Example
New Rule
A pattern/anti-pattern not covered at all
.entered() in async is forbidden
Rule Refinement
Existing rule needs caveats or edge cases
skip_all needed when params include trait objects
New Example
Correct/incorrect code pattern to illustrate existing rule
async {}.instrument(span).await for match arms
Checklist Addition
New review checkpoint
".entered() held across .await? FORBIDDEN"
Section Expansion
Existing section needs a new subsection
Adding async lifecycle patterns to spawn section
Step 3 — Draft the Update
Write the proposed additions following these principles:
Match the existing style — same heading levels, table formats, code block conventions
Place it where it belongs — near related content, not appended randomly at the end
Lead with the rule, then the why, then the example
Include both CORRECT and FORBIDDEN patterns when adding anti-patterns
Keep it concise — skills are reference material, not tutorials
Step 4 — Apply and Summarize
Edit the SKILL.md with the new content.
Present a summary to the user:
## Skill Evolution Summary
**Skill**: <skill name>
**Trigger**: <what happened that revealed the gap>
**Update type**: <New Rule | Rule Refinement | New Example | Checklist Addition | Section Expansion>
**What was added**:
- <bullet summary of each change>
**Section(s) modified**: <list of modified section numbers/names>
Quality Gates
Before applying the update, verify:
The new content does NOT duplicate existing rules (check the full SKILL first)
The new content is grounded in a real incident from this conversation (not hypothetical)
The learning is generalizable — useful beyond this one specific case
If adding a FORBIDDEN pattern, a CORRECT alternative is shown alongside it
Anti-Patterns for This Skill
Don't bloat: If the learning is too narrow or one-off, suggest the user add it to memory instead of a skill
Don't rewrite: Evolve the skill incrementally. Don't restructure or rewrite existing sections unless they are wrong
Don't speculate: Only add patterns that were validated in practice during this conversation
Don't duplicate: If the fix was specific to this codebase and not transferable, it belongs in the nearest AGENTS.md, not a skill
1---2name: skill-evolve3description: Skill Evolve4---56# Skill Evolve78Turn real-world experience into durable skill knowledge.910## When to Use1112User invokes this skill after completing work that revealed a gap, pitfall, or new pattern not yet captured in an existing SKILL.md. Typical trigger: `$skill-evolve @path/to/SKILL.md`1314## Procedure1516### Step 1 — Gather Context17181. Read the referenced SKILL.md in full.192. Review the current conversation to identify:20 - **What went wrong or was discovered** (the incident/finding)21 - **Root cause** (why it happened)22 - **The fix or pattern** (what the correct approach is)23 - **Why the existing skill didn't prevent it** (the gap)2425### Step 2 — Classify the Learning2627Determine which type of update is needed:2829| Type | Description | Example |30| ---------------------- | ---------------------------------------------------------- | --------------------------------------------------- |31| **New Rule** | A pattern/anti-pattern not covered at all | `.entered()` in async is forbidden |32| **Rule Refinement** | Existing rule needs caveats or edge cases | `skip_all` needed when params include trait objects |33| **New Example** | Correct/incorrect code pattern to illustrate existing rule | `async {}.instrument(span).await` for match arms |34| **Checklist Addition** | New review checkpoint | "`.entered()` held across `.await`? FORBIDDEN" |35| **Section Expansion** | Existing section needs a new subsection | Adding async lifecycle patterns to spawn section |3637### Step 3 — Draft the Update3839Write the proposed additions following these principles:4041- **Match the existing style** — same heading levels, table formats, code block conventions42- **Place it where it belongs** — near related content, not appended randomly at the end43- **Lead with the rule, then the why, then the example**44- **Include both CORRECT and FORBIDDEN patterns** when adding anti-patterns45- **Keep it concise** — skills are reference material, not tutorials4647### Step 4 — Apply and Summarize48491. Edit the SKILL.md with the new content.502. Present a summary to the user:5152```text53## Skill Evolution Summary5455**Skill**: <skill name>56**Trigger**: <what happened that revealed the gap>57**Update type**: <New Rule | Rule Refinement | New Example | Checklist Addition | Section Expansion>58**What was added**:59- <bullet summary of each change>60**Section(s) modified**: <list of modified section numbers/names>61```6263## Quality Gates6465Before applying the update, verify:6667- [ ] The new content does NOT duplicate existing rules (check the full SKILL first)68- [ ] The new content is grounded in a real incident from this conversation (not hypothetical)69- [ ] Code examples compile conceptually (correct syntax, realistic types)70- [ ] The learning is **generalizable** — useful beyond this one specific case71- [ ] If adding a FORBIDDEN pattern, a CORRECT alternative is shown alongside it7273## Anti-Patterns for This Skill7475- **Don't bloat**: If the learning is too narrow or one-off, suggest the user add it to memory instead of a skill76- **Don't rewrite**: Evolve the skill incrementally. Don't restructure or rewrite existing sections unless they are wrong77- **Don't speculate**: Only add patterns that were validated in practice during this conversation78- **Don't duplicate**: If the fix was specific to this codebase and not transferable, it belongs in the nearest `AGENTS.md`, not a skill
Run npx skillmds@latest add uniclipboard/skill-evolve in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Skill Evolve It is listed under Coding & Dev Tools on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
uniclipboard (@uniclipboard) published this skill. Their other Agent Skills are listed on their SkillMD profile.
uniclipboard