self-evolve

name	self-evolve
description	Detect capability gaps and autonomously create skills, add free MCP servers, or organize agent teams. Trigger when: a task requires tools you don't have, a workflow pattern repeats 3+ times, a tool call fails because the capability is missing, or the user says 'there should be a skill for this' or 'can you learn to do X'. Always ask before adding external MCP servers.
auto-generated	false

Self-Evolve — Autonomous Capability Growth

The system's meta-skill. When Claude detects it lacks a capability needed for the current task, this skill provides the decision framework to fill the gap — by creating skills, adding MCP servers, or recommending community tools.

Gap Detection Signals

Activate self-evolve when ANY of these occur:

1. Missing tool: A task requires an integration or tool that isn't available (e.g., "connect to Jira" but no Jira MCP)
2. Repeated pattern: The same multi-step workflow has been executed 3+ times across sessions — check ~/.claude/logs/failures.jsonl and <your-vault-path>/wiki/engineering/_index.md for patterns
3. Explicit request: User says "can you learn to do X", "there should be a skill for this", "add a tool for X"
4. Tool failure: A tool call fails because the capability doesn't exist, not because of a bug
5. Inefficiency signal: Claude catches itself doing >5 manual steps that could be automated

Decision Tree

Step 0 — check the parked-capabilities registry FIRST: INSTALLED.md § "Parked capabilities" holds pre-vetted, license-checked, install-ready capabilities with explicit adoption triggers (local image gen via ComfyUI, local TTS via OmniVoice, crawl4ai-as-MCP, MCP-description compression, no-code scrapers, local video gen). If the detected gap matches a row, propose THAT (install + register only — the research is done, don't redo it). Same file records outright-rejected tools — don't re-research those either.

┌─ Is the gap about a TOOL or INTEGRATION?
│  YES → Check INSTALLED.md § Parked capabilities (step 0) → then search MCP registry
│  │  ├─ mcp-find "{keyword}" → found free server?
│  │  │  YES → Show user: name, capabilities, source → on approval: mcp-add → document in INSTALLED.md
│  │  │  NO  → Can a skill wrap existing CLI tools?
│  │  │       YES → Create skill (see Skill Creation Protocol)
│  │  │       NO  → Inform user, suggest alternatives or manual install
│  │
│  NO ↓
│
├─ Is the gap about a REPEATED WORKFLOW?
│  YES → Create skill using Skill Creation Protocol
│  │     1. Capture the workflow steps from conversation history
│  │     2. Abstract into reusable instructions
│  │     3. Write SKILL.md with proper frontmatter
│  │     4. Register in ACTIVE-DIRECTORY.md (protocol step 3)
│  │
│  NO ↓
│
├─ Is the gap about DOMAIN KNOWLEDGE?
│  YES → Search Context7 first (no skill needed)
│  │     If recurring → create lightweight reference skill
│  │
│  NO ↓
│
└─ Is the gap about AGENT COORDINATION?
   YES → Suggest /flow:smart-swarm (SK-039) for complex multi-agent tasks

MCP Server Addition Protocol

1. Search: Use mcp-find with relevant keywords

   mcp-find "jira" / "slack" / "database" / "email" / etc.
   

2. Evaluate: Check each result for:

   • Free tier available (no API key required, or user has the key)
   • Relevant to the task at hand
   • Not redundant with existing MCP servers (check INSTALLED.md + the connected-server list)

3. Propose: Show the user:

   Found MCP server: {name}
   Capabilities: {list of tools it provides}
   Source: {catalog entry}
   Requires: {any API keys or auth needed}
   
   Want me to add it?
   

4. Install (on user approval):

   mcp-add "{server-name}"
   

5. Verify: Make a test call to confirm tools are working

6. Register: Document the server in ~/.claude/INSTALLED.md (dated entry: name, purpose, access method). skills/REGISTRY.md was retired — the live skill index is ACTIVE-DIRECTORY.md.

7. Log: Update ~/.claude/SYSTEM_CHANGELOG.md

Skill Creation Protocol

1. Template: Read ~/.claude/skills/self-evolve/templates/skill-template.md

2. Write: Create ~/.claude/skills/{name}/SKILL.md with:

   • Proper frontmatter (name, description with trigger conditions)
   • auto-generated: true tag in frontmatter
   • keywords: [keyword1, keyword2, "multi word phrase"] in frontmatter — these feed the keyword detection system so the skill is auto-suggested on matching prompts
   • Clear "When to Use" section
   • Step-by-step "Process" section
   • Expected "Output Format"

3. Register (v8.14: REGISTRY.md never existed — real surfaces below, same set skill-vet SK-140 uses):

   • skills/ACTIVE-DIRECTORY.md — add the | SK-NNN | {name} | {purpose} | skills/{name}/SKILL.md | row + bump the header total (next free SK number = last entry + 1)
   • SYSTEM_VERSION.md — Skills (in ACTIVE-DIRECTORY) row count
   • ARCHITECTURE.md + REFERENCE.md + README badges — count mentions (the skill-counts validator cross-checks all surfaces; run node scripts/system-doctor.js after)

4. Changelog: Update ~/.claude/SYSTEM_CHANGELOG.md

5. Verify: Read back the skill to confirm it's well-formed

Safety Rules — Non-Negotiable

• NEVER install paid services or servers requiring paid API keys without explicit user confirmation
• NEVER add MCP servers that require authentication tokens the user hasn't provided
• ALWAYS verify free tier availability before suggesting
• ALWAYS show the user what will be added and get confirmation for MCP servers
• ALWAYS check ACTIVE-DIRECTORY.md + ARCHIVE-DIRECTORY.md for duplicates before creating (grep for similar names/purposes)
• MAX 1 auto-created skill per session unless user explicitly requests more
• Skills are local files only — no external downloads or binary installations
• If uncertain whether something is free, ASK the user

Examples

Example 1: Missing MCP Server

User: "Can you check my Asana tasks?"
Gap: No Asana MCP server connected
Action: mcp-find "asana" → found → propose → user approves → mcp-add → register

Example 2: Repeated Pattern

Pattern: Claude has formatted markdown tables 4 times this session using the same 6-step process
Action: Create skill "markdown-table-formatter" with the 6 steps abstracted

Example 3: Domain Knowledge

User: "How do I use the Stripe API?"
Action: Context7 search first → if sufficient, use inline → if recurring need, create reference skill