🧬 Self-Evolving Agent

The agent that watches how you use it, finds what's missing, and builds itself new capabilities.

Most AI agents are static — they do what they're told and nothing more. This skill turns your agent into a self-improving system that identifies gaps in its own abilities and proposes new skills to fill them. Over time, your agent becomes progressively more useful without you doing anything.

How It Works

1. Observe — The agent monitors your conversations, noting recurring request patterns
2. Detect — It identifies tasks you keep asking for that aren't served by existing skills
3. Propose — It drafts a new skill proposal with name, description, commands, and rationale
4. Confirm — You review the proposal and decide whether to create it
5. Create — The agent writes a complete SKILL.md file and installs it
6. Iterate — After deployment, it monitors usage and improves the skill over time

Commands

evolve:scan

Scan recent conversations for recurring request patterns that aren't covered by existing skills.

What it does:

• Uses session_search to review your last N days of conversations
• Extracts repeated task patterns (at least 3 occurrences by default)
• Cross-references against installed skills via skills_list
• Identifies gaps: things you keep asking for that no skill handles

Parameters:

• --days N — How many days of history to scan (default: 30)
• --min-occurrences N — Minimum times a pattern must appear to be considered (default: 3)

Process:

1. Run session_search with broad queries to capture recent conversations
2. For each session, identify the core user request/intent
3. Group similar intents into pattern clusters
4. Run skills_list to get all installed skill names
5. For each pattern cluster, check if any existing skill covers it
6. Report uncovered patterns with: pattern name, occurrence count, example requests, suggested skill category

Example output:

🔍 Evolution Scan Results (last 30 days)

Uncovered Patterns:
1. "Car maintenance tracking" — 5 occurrences
   Examples: "When's my MOT due?", "Book a service", "Check tyre pressure"
   No existing skill covers this.
   Suggested category: productivity

2. "Recipe scaling" — 3 occurrences
   Examples: "Halve this recipe", "Scale for 8 people"
   Meal-planner skill exists but doesn't cover scaling.
   Suggested category: productivity (extend meal-planner)

evolve:propose

Generate a skill proposal based on detected gaps.

What it does:

• Takes an uncovered pattern and designs a complete skill around it
• Writes a proposal document in Obsidian with: name, description, commands, references, pitfalls
• Presents the proposal for your review before any files are created

Parameters:

• --pattern PATTERN_ID — Propose a skill for a specific pattern (from scan results)

Process:

1. Analyse the pattern's example requests to understand the full scope
2. Choose an appropriate category and skill name
3. Define 3-6 commands that cover the pattern's use cases
4. Draft YAML frontmatter with name, description, version, author, metadata
5. Write full documentation sections: overview, commands (with examples), pitfalls, verification
6. Save proposal to ~/obsidian-vault/Inbox/Evolution Proposals/[name]-proposal.md
7. Present the proposal to the user for review

Proposal format:

# 🧬 Evolution Proposal: [skill-name]

**Detected Pattern:** [what you keep asking for]
**Occurrence Count:** [how many times in last N days]
**Category:** [suggested category]

## Proposed Skill

**Name:** [skill-name]
**Description:** [one-line description]

### Commands
1. `[command]` — [description]
2. `[command]` — [description]
...

### Why This Skill
[Evidence from conversation history showing the need]

### Pitfalls to Address
[Known challenges this skill should handle]

---
Reply "create" to install this skill, "edit" to modify, or "skip" to dismiss.

evolve:create

Create a new skill from a confirmed proposal.

What it does:

• Reads the approved proposal from Obsidian
• Generates a complete, well-structured SKILL.md file
• Saves it to ~/.hermes/skills/[category]/[skill-name]/SKILL.md
• Creates any referenced templates/scripts
• Registers the skill by running skills_list to verify it appears

Parameters:

• --proposal PROPOSAL_ID — The proposal to create from

Process:

1. Read proposal from ~/obsidian-vault/Inbox/Evolution Proposals/
2. Generate complete SKILL.md with:
   • YAML frontmatter (name, description, version: 0.1.0, author: "Self-Evolving Agent")
   • Full command documentation with usage, examples, process steps
   • Pitfalls section
   • Verification steps
3. Write to ~/.hermes/skills/[category]/[skill-name]/SKILL.md
4. Create references/ templates/ directories if referenced
5. Run skills_list to confirm the new skill appears
6. Log creation to evolution log (see below)
7. Move proposal to ~/obsidian-vault/Archive/Evolution Proposals/

Safety guardrails:

• NEVER create a skill without user confirmation (the proposal must be explicitly approved)
• ALWAYS set initial version to 0.1.0 (indicating auto-generated, needs refinement)
• ALWAYS include the author: "Self-Evolving Agent" tag for traceability
• NEVER overwrite an existing skill — check with skills_list first
• If a similar skill exists, propose extending it instead of creating a new one

evolve:review

Review auto-generated skills: their quality, usage statistics, and iteration history.

What it does:

• Lists all skills created by the self-evolving agent (identified by author: "Self-Evolving Agent")
• Shows usage frequency since creation
• Rates skill quality (completeness of docs, command coverage, pitfalls section)
• Highlights skills that may need iteration

Parameters:

• --skill SKILL_NAME — Review a specific skill (omit for all auto-generated skills)

Process:

1. Scan ~/.hermes/skills/ for skills with author: "Self-Evolving Agent" in frontmatter
2. For each skill, check:
   • How many times it's been loaded via skill_view in recent sessions (use session_search)
   • Whether its commands are being used
   • Quality score: does it have complete docs, pitfalls, verification steps?
   • Version (0.1.x = needs iteration, 1.0+ = mature)
3. Present a review dashboard in Obsidian

Example output:

📊 Self-Evolution Review

Auto-generated skills: 3

1. vehicle-management (v0.1.0) — ⭐⭐⭐☆☆
   Created: 2026-04-28 | Loaded: 12 times | Commands used: 8/12
   Notes: Missing pitfall about UK MOT grace period. Commands well-structured.
   Recommendation: Iterate — add MOT pitfalls and extend command set.

2. recipe-scaler (v0.1.0) — ⭐⭐☆☆☆
   Created: 2026-04-30 | Loaded: 3 times | Commands used: 1/4
   Notes: Could be merged into meal-planner. Low usage suggests overlap.
   Recommendation: Consider merging into existing meal-planner skill.

3. commute-optimizer (v1.0.0) — ⭐⭐⭐⭐⭐
   Created: 2026-03-15 | Loaded: 45 times | Commands used: 10/10
   Notes: Mature, well-adopted. All commands active.
   Recommendation: Promote to stable. No further iteration needed.

evolve:iterate

Improve an existing auto-generated skill based on usage feedback and identified gaps.

What it does:

• Reads the skill's current SKILL.md
• Analyses how it's been used (which commands, which pitfalls hit)
• Identifies gaps: commands that are never used, missing commands users are asking for
• Updates the SKILL.md with improvements

Parameters:

• --skill SKILL_NAME — The skill to iterate on

Process:

1. Load current skill via skill_view
2. Search recent sessions for usage of this skill's commands
3. Identify:
   • Commands that are never used → candidates for removal or redesign
   • User requests that should be covered but aren't → new commands
   • Pitfalls that users have hit → add to pitfalls section
   • Missing verification steps → add
4. Generate an updated SKILL.md
5. Use skill_manage(action='patch') to apply targeted improvements
6. Bump version: 0.1.0 → 0.1.1 (minor iteration) or 0.1.x → 1.0.0 (mature)
7. Log iteration to evolution log

Iteration criteria:

• If a skill has been loaded 10+ times and all commands are used → promote to v1.0.0
• If a skill has commands never used → redesign or remove them
• If users are asking for features outside the skill's scope → extend or propose a companion skill
• If a skill overlaps significantly with another → propose merging

Evolution Log

All self-evolution activity is tracked in an Obsidian note for persistence and review.

Log location: ~/obsidian-vault/Areas/Self-Evolution Log.md

Log entry format:

## [YYYY-MM-DD] [skill-name] — [Action]

**Pattern detected:** [what was observed]
**Occurrences:** [count] in [N] days
**Proposal:** [link to proposal]
**Action taken:** [created/iterated/promoted/merged]
**Version:** [old → new]
**Commands:** [list of commands in the skill]
**Notes:** [any observations]

How It Monitors

The self-evolving agent can be triggered in two ways:

1. Manual — User explicitly runs evolve:scan or evolve:propose
2. Automatic — Set up a cron job to periodically scan for patterns

Cron setup example:

# Scan for evolution opportunities every week
hermes cron:create --schedule "0 9 * * 1" --prompt "Run evolve:scan and present any new patterns found"

Pitfalls

1. Never auto-create without confirmation — Always propose first. The user must explicitly approve every new skill creation with "create".

2. Check for overlap before creating — Use skills_list to verify no existing skill covers the same territory. If one does, propose extending it instead.

3. Pattern detection threshold — Require at least 3 occurrences over 30 days before proposing a skill. One-off requests don't justify a dedicated skill.

4. Version numbering — Auto-generated skills start at 0.1.0. Only promote to 1.0.0 after the iteration review confirms maturity (10+ loads, all commands used).

5. Evolution log persistence — The Obsidian log is the single source of truth. If it's missing, recreate it from session history before proceeding.

6. Skill quality standards — Every auto-generated skill must have: complete YAML frontmatter, 3+ commands with examples, pitfalls section, verification steps. Don't create stub skills.

7. Don't create skills for things that should be one-liners — If a user asks "what's the weather" 10 times, that's a use case, not a skill. Patterns should represent complex, multi-step workflows.

8. Respect existing skill boundaries — If the meal-planner skill exists and the pattern is about recipes, propose extending meal-planner rather than creating recipe-scaler.

Verification

• Run evolve:scan and confirm it identifies patterns from your recent conversations
• Run evolve:propose and check the proposal appears in ~/obsidian-vault/Inbox/Evolution Proposals/
• Run evolve:create --proposal [id] and verify the new SKILL.md file exists at the correct path
• Check the new skill appears in skills_list output
• Verify the evolution log has a new entry for the creation
• Run evolve:review and confirm the newly created skill appears with quality metrics
• Run evolve:iterate --skill [name] and verify the skill is updated with a bumped version

Philosophy

The Self-Evolving Agent is built on the principle that the best tool is one that grows with you. Instead of waiting for someone else to build the skill you need, your agent watches how you work, identifies what's missing, and builds it. Over time, your agent becomes uniquely tailored to your life — because it shaped itself around your actual patterns.

This is not about replacing human creativity or decision-making. It's about removing the friction between "I wish my agent could do this" and "my agent now does this."

The agent that levels itself up.