Self-Evolving Skill

A skill that enables continuous self-improvement through reflection, learning, and self-modification.

Core Principle

Every task is a learning opportunity. After completing work, reflect on what happened, extract insights, and permanently improve the skill's own capabilities.

Evolution Lifecycle

Complete Task -> Reflect -> Research -> Record Learning -> Evaluate -> User Confirm -> Apply Changes -> Version

When to Evolve

Auto-trigger (record only):
- After completing any task that involved debugging or fixing errors
- After a task failed or required multiple attempts
- After completing a complex multi-step task (capture what worked)
- When discovering a new pattern, tool usage, or technique

Full evolution (record + modify):
- When the user explicitly asks: evolve, improve yourself, learn from this, self-reflect
- When accumulated learnings reveal a systematic improvement opportunity

Step-by-Step Workflow

Step 1: Reflect

After completing a task, analyze the execution:

1. What went well? -- Patterns, approaches, or techniques that were effective
2. What went wrong? -- Errors, inefficiencies, or surprises encountered
3. What was learned? -- New knowledge about tools, APIs, the codebase, or domain
4. What would I do differently? -- Concrete behavioral changes for next time

Step 2: Research External Best Practices

Before recording and applying changes, search for relevant external knowledge to
ground the evolution in proven practices rather than purely internal reflection.
This prevents reinventing the wheel and ensures modifications align with
established patterns from the research community.

When to research:
- Always before a full evolution (record + modify)
- When the learning involves a new technique, pattern, or approach
- When unsure whether a proposed change is sound

When to skip:
- Pure bugfixes to scripts (typos, syntax errors)
- One-time project-specific details with no generalizable pattern
- When the user explicitly says to skip research

How to research:

python scripts/research_evolution.py --topic "TOPIC" [--max-results 5]

Replace TOPIC with a concise description of the proposed change, e.g.:
- "LLM agent self-reflection skill evolution"
- "agent evaluator optimizer workflow pattern"
- "skill library versioning best practices"

The script searches arxiv and the web for relevant papers and articles.
Review the results and extract actionable insights:

1. Relevant papers -- Note key findings that support or contradict the proposed change
2. Established patterns -- Identify named patterns or frameworks that apply
3. Best practices -- Extract concrete recommendations from authoritative sources
4. Warnings -- Note any risks or pitfalls mentioned in the literature

Incorporate these insights into the learning record and use them to refine
the proposed modification before presenting it to the user.

Step 3: Record the Learning

Append the reflection to the evolution log:

python scripts/log_learning.py --category CATEGORY --summary "One-line summary" --detail "Detailed description" --action "What to change"

The log is stored at references/evolution-log.jsonl (one JSON object per line).

Step 4: Evaluate if Changes Are Needed

Ask: Does this learning warrant a permanent change to the skill's files?

Apply changes when:
- A new reusable pattern was discovered (add to SKILL.md body)
- An existing instruction was wrong or misleading (fix it)
- A new tool/API behavior was learned (add reference)
- A common mistake was identified (add warning/guardrail)
- A script bug was found and fixed
- External research confirms the proposed direction

Do NOT change files for:
- One-time project-specific details
- Information already in the system prompt
- Trivial observations
- Changes contradicted by established research without strong justification

Step 5: User Confirmation (Balance Mode)

Before applying any changes:

1. Show the user exactly what will be changed (diff format)
2. Explain the reasoning behind each change
3. Wait for explicit user confirmation
4. If declined, log the rejected learning for future reference

Step 6: Apply Self-Modification

If confirmed, apply changes:

python scripts/apply_evolution.py --type TYPE --content "New content"

Safety rules:
- Never delete the YAML frontmatter name or description
- Never remove existing instructions unless provably wrong and user-confirmed
- Prefer appending new sections over modifying existing ones
- Never modify more than 30% of a file in a single evolution
- After modifying, validate with: python scripts/validate_skill.py

Step 7: Version the Evolution

python scripts/version_bump.py --type major|minor|patch --reason "Why this change"

Version history is stored in references/version-log.jsonl.

Evolution Log Format

Each entry in references/evolution-log.jsonl:

{
  "timestamp": "2026-06-01T16:00:00+08:00",
  "version": "1.0.0",
  "category": "discovery",
  "summary": "Brief one-line summary",
  "detail": "Full description",
  "action_taken": "What was changed",
  "files_modified": ["SKILL.md"],
  "user_confirmed": true
}

Categories