<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: self-evolution
description: >-
  Self-evolution system for automatic skill generation from engagement experience.
  Detects skill gaps during operations (missing skills, shallow coverage, new threats,
  tool gaps), tracks gaps persistently, validates generated skills against AgentSkills
  standard, and registers new skills into the NERF ecosystem. Inspired by MetaClaw's
  skill evolution pattern.
domain: cybersecurity
subdomain: evolution-system
tags:
  - self-evolution
  - skill-generation
  - gap-detection
  - quality-validation
  - continuous-improvement
  - metaclaw
version: "1.0"
author: defconxt
license: AGPL-3.0
compatibility: Designed for Claude Code, GitHub Copilot, OpenAI Codex, Cursor, Gemini CLI, and any agentskills.io-compatible agent.
metadata:
  frameworks: ["MetaClaw skill evolution", "AgentSkills standard"]
---

# Self-Evolution System

## When to Use

Activate when NERF encounters a domain it lacks depth in, when an operator
query can't be fully answered by existing skills, when new threats emerge that
aren't covered, or when reviewing skill coverage gaps.

## Architecture

```
Engagement Session
    │
    ├─── Gap Detection
    │    ├── Missing skill (no skill covers this domain)
    │    ├── Shallow coverage (skill exists but lacks depth)
    │    ├── Outdated (stale tool versions, deprecated techniques)
    │    ├── Failed task (operator couldn't complete objective)
    │    ├── New threat (emerging attack not covered)
    │    └── Tool gap (new tool not documented)
    │
    ├─── Gap Tracker (persistent JSON store)
    │    ├── Report gaps with confidence scores
    │    ├── Deduplicate similar gaps
    │    └── Prioritize by confidence × frequency
    │
    ├─── Skill Synthesizer
    │    ├── Generate SKILL.md from template + context
    │    ├── Include: frontmatter, workflows, commands, verification
    │    └── Target: 100-250 lines, practitioner-grade depth
    │
    ├─── Skill Validator
    │    ├── YAML frontmatter validation (8 required fields)
    │    ├── Section validation (When to Use, Quick Reference, Workflow, Verification)
    │    ├── Name format validation (kebab-case, 2-64 chars)
    │    ├── Content quality (code examples, verification checklist)
    │    └── Line count check (30-300 recommended)
    │
    └─── Skill Registry
         ├── Create directory structure (SKILL.md + references/ + scripts/ + assets/)
         ├── Update index.json
         └── Resolve tracked gap
```

## Usage

```python
from evolution.core.engine import EvolutionEngine, GapType

engine = EvolutionEngine(
    skills_dir=Path("skills"),
    index_path=Path("index.json"),
)

# Report a gap detected during engagement
engine.report_gap(
    gap_type=GapType.MISSING_SKILL,
    description="No skill for firmware binary analysis and backdoor detection",
    operator_query="How do I extract and analyze router firmware for backdoors?",
    subdomain="firmware-security",
    confidence=0.85,
    suggested_tags=["firmware", "binwalk", "ghidra", "iot", "embedded"],
)

# Review pending gaps
gaps = engine.get_pending_gaps(min_confidence=0.5)
for gap in gaps:
    print(f"[{gap.confidence:.1f}] {gap.description}")

# Validate a generated skill before registration
result = engine.validate_skill(skill_content, "firmware-security")
if result.valid:
    print(f"Quality score: {result.score:.2f}")
else:
    print(f"Errors: {result.errors}")

# Register the skill (validates + creates dirs + updates index)
path, result = engine.register_skill(
    name="firmware-security",
    description="Firmware analysis and IoT security",
    subdomain="firmware-security",
    tags=["firmware", "binwalk", "iot"],
    content=skill_content,
    gap_id=gap.gap_id,  # Resolves the tracked gap
)
```

## Gap Types

| Type | Trigger | Example |
|------|---------|---------|
| `missing_skill` | No skill covers requested domain | "firmware analysis" with no firmware skill |
| `shallow_coverage` | Skill exists but lacks depth | "SAML attacks" covered briefly in IAM but needs deep skill |
| `outdated` | Tool versions or techniques stale | "Cobalt Strike 4.9 features" not in post-exploitation |
| `failed_task` | Operator couldn't complete objective | "Analyze Solidity smart contract" — no Web3 skill |
| `new_threat` | Emerging threat not covered | "AI worm propagation via agent tool abuse" |
| `tool_gap` | New tool not documented | "Caido proxy" not in web skill |

## Validation Rules

| Check | Requirement | Impact |
|-------|-------------|--------|
| YAML frontmatter | Must start with `---` | ❌ Fail |
| Required fields | name, description, domain, subdomain, tags, version, author, license | ❌ Fail |
| Name format | kebab-case, 2-64 characters | ❌ Fail |
| Minimum length | ≥30 lines | ❌ Fail |
| Code examples | At least one code block | ⚠ Warning |
| Verification checklist | `- [ ]` items present | ⚠ Warning |
| Recommended sections | When to Use, Quick Reference, Workflow, Verification | ⚠ Warning |
| Maximum length | ≤300 lines (split to references/) | ⚠ Warning |

## Verification

- [ ] Gap detection identifies missing skills from operator queries
- [ ] Gaps persist across sessions (JSON storage)
- [ ] Skill validation catches malformed frontmatter
- [ ] Skill validation catches missing required fields
- [ ] Valid skills register successfully (dirs + index.json)
- [ ] Invalid skills are rejected without filesystem changes
- [ ] Resolved gaps tracked with resolution type
