Self-Referential Self-Improvement

This skill implements the core insight from Meta's HyperAgents paper: agents can improve themselves by treating their own code/prompts as mutable targets, evaluating changes with fitness functions, and selecting the best mutations across generations.

When This Skill Activates

• User asks to "improve", "optimize", or "evolve" a skill, agent, or code file
• A task fails repeatedly (automatic recovery via self-improvement)
• User explicitly invokes /hyperagents:evolve
• User asks about self-referential improvement patterns

The Self-Improvement Cycle

┌─────────────────────────────────────────────┐
│              GENERATE LOOP                   │
│                                              │
│  1. SELECT PARENT (from archive)             │
│         │                                    │
│  2. MUTATE (meta-agent modifies code)        │
│         │                                    │
│  3. EVALUATE (fitness scoring)               │
│         │                                    │
│  4. ARCHIVE (store generation + score)       │
│         │                                    │
│  5. SELECT NEXT PARENT (fitness-weighted)    │
│         │                                    │
│         └──────── repeat ────────────┘       │
└─────────────────────────────────────────────┘

Key Principles

1. Everything is Mutable

Unlike traditional agent frameworks where the orchestrator is fixed, HyperAgents allows the meta-agent to modify:

• Task agent prompts and logic
• Tool definitions and tool selection strategies
• Evaluation criteria and scoring rubrics
• Parent selection algorithms
• Even its own system prompt

2. Fitness-Driven Selection

Changes are not accepted blindly. Every mutation is evaluated:

• Staged evaluation: Quick check on small sample (fail fast)
• Full evaluation: Comprehensive scoring if staged passes
• Archive comparison: New generation scored against all ancestors

3. Evolutionary Archive

All generations are kept in an append-only archive:

• Enables backtracking to any previous generation
• Supports ensemble methods (combining best aspects of multiple generations)
• Provides data for analysis of what improvement strategies work

4. Sandboxed Mutation

All changes are made in isolation:

• Git worktrees provide sandboxed copies of the codebase
• Failed mutations don't corrupt the main branch
• Diffs are captured and stored for replay

Applying Self-Improvement to Claude Code Artifacts

Improving a Skill

1. Identify the skill's evaluation criteria (what makes it "good"?)
2. Create a fitness function (test it on sample inputs, score the outputs)
3. Run the evolve loop targeting the SKILL.md file
4. Each generation modifies the skill's instructions
5. The best-scoring version becomes the new skill

Improving an Agent

1. Define the agent's success criteria
2. Create test cases that exercise the agent
3. Run the meta-agent to modify the agent's system prompt
4. Evaluate each version against the test cases
5. Select the best-performing version

Improving Hooks

1. Measure hook execution time and false positive rate
2. Run evolve loop on the hook script
3. Each generation modifies the hook logic
4. Score based on accuracy and performance
5. Deploy the best version

Implementation Pattern

When asked to self-improve a target:

1. Create .hyperagents/ directory if not exists
2. Define fitness function for the target
3. Store initial version as gen_initial
4. For N generations:
   a. Select parent from archive
   b. Create git worktree
   c. Dispatch meta-agent to modify target in worktree
   d. Capture diff
   e. Run fitness evaluation
   f. Store results in archive
   g. Clean up worktree
5. Apply best generation's changes

Examples

These scenarios illustrate when this skill activates and what it does.

Scenario 1: User requests skill improvement

Trigger: User says "Improve the code-review skill so it catches more security issues." Action: The skill creates a .hyperagents/ workspace, defines a fitness function based on security-issue detection rate, snapshots the current skill as gen_initial, and launches the evolve loop targeting the skill's SKILL.md. Each generation mutates the skill instructions, evaluates against a set of code samples with known vulnerabilities, and archives the result.

Scenario 2: Automatic recovery after repeated task failure

Trigger: A task agent fails 3 consecutive times on similar inputs (e.g., test generation keeps producing invalid syntax). Action: The skill detects the failure pattern and initiates a self-improvement cycle on the failing agent's prompt. It uses the failing inputs as evaluation samples, scores each mutation by whether the generated output passes validation, and selects the best-performing prompt revision.

Scenario 3: User invokes the evolve command directly

Trigger: User runs /hyperagents:evolve --domain tests --generations 5 --target src/utils/parser.ts. Action: The skill orchestrates 5 generations of mutations to parser.ts, evaluating each against the project's test suite. It selects parents using score-proportional selection, captures diffs, and reports the best generation's improvements along with a suggestion to apply the winning patch.

Anti-Patterns to Avoid

• Goodhart's Law: Don't let the meta-agent optimize the evaluator to give itself higher scores without real improvement
• Catastrophic forgetting: Ensure improvements in one area don't regress others
• Infinite loops: Set a hard generation limit; diminishing returns are expected
• Over-mutation: Prefer small, focused changes over wholesale rewrites