# Skill Evolution

> Self-evolving skills — analyzes session corrections, error patterns, and successful approaches to automatically propose improvements to SKILL.md files. Use when the user says 'evolve skills', 'improve skills from history', 'what have we learned'.

- Skill: `kevinzai/skill-evolution` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kevinzai/skill-evolution`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kevinzai/skill-evolution/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: KevinZai (https://skillmd.com/u/kevinzai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kevinzai/skill-evolution

---


# Skill Evolution — Self-Improving Skills

Analyzes CC Commander's knowledge base and session history to propose concrete improvements to SKILL.md files.

## How It Works

1. **Scan knowledge base** — Read ~/.claude/commander/knowledge/*.json for patterns
2. **Identify corrections** — Find sessions where approach A failed but approach B succeeded
3. **Match to skills** — Map error/success patterns to relevant SKILL.md files
4. **Propose changes** — Generate specific edits (add gotchas, update examples, flag anti-patterns)
5. **User approval** — Present changes via AskUserQuestion before applying

## Trigger Conditions

Run skill evolution when:
- Knowledge base has 10+ lessons
- A skill was involved in 3+ failed sessions
- A new pattern was discovered that contradicts skill guidance

## Process

### Step 1: Analyze Knowledge Base

```bash
# Read all lessons
ls ~/.claude/commander/knowledge/*.json | wc -l
```

For each lesson with outcome "error":
- Extract the error pattern
- Identify which skill category it falls into
- Check if the relevant SKILL.md already warns about this

### Step 2: Generate Proposals

For each skill with improvement opportunities:

Use AskUserQuestion:
```
Skill: {skill-name}
Based on {N} sessions, I found:
- {pattern}: happened {count} times
- Current SKILL.md does NOT warn about this

Proposed addition to SKILL.md:
## Known Gotchas
- {description of the gotcha}
- Workaround: {what worked}

Apply this improvement?
❯ Yes, update the skill
  Show me the full diff first
  Skip this one
```

### Step 3: Apply and Log

After user approval:
1. Edit the SKILL.md file
2. Log the evolution to ~/.claude/commander/knowledge/ with category "skill-evolution"
3. Report what was changed

## Safety

- NEVER modify skills without user approval
- Only ADD content (gotchas, examples, warnings) — never remove
- Keep a log of all evolutions in ~/.claude/commander/skill-evolution-log.json
- Maximum 5 proposals per run (don't overwhelm)

## Example Output

```
Skill Evolution Report:
━━━━━━━━━━━━━━━━━━━━━

Analyzed: 47 lessons across 12 categories
Proposals: 3 improvements

1. skills/ccc-saas/auth-patterns/SKILL.md
   + Added: "next-auth conflicts with custom Prisma adapters" to Gotchas
   Evidence: 2 failed sessions, 1 workaround found

2. skills/frontend-patterns/SKILL.md
   + Added: "middleware.ts matcher needs exact paths, not wildcards" to Tips
   Evidence: 3 sessions hit this issue

3. skills/ccc-testing/SKILL.md
   + Added: "Mock database tests can mask real migration failures" to Anti-Patterns
   Evidence: 1 production incident traced to mocked tests

Applied: 3/3 (user approved all)
```