Skill Evolution Manager

Enables skills to automatically improve based on usage patterns, user edits, and success rates. Provides version control with safe rollback capability.

Overview

• Reviewing how skills are performing across sessions
• Identifying patterns in user edits to skill outputs
• Applying learned improvements to skill templates
• Rolling back problematic skill changes
• Tracking skill version history and success rates

Quick Reference

Command	Description
/ork:skill-evolution	Show evolution report for all skills
/ork:skill-evolution analyze <skill-id>	Analyze specific skill patterns
/ork:skill-evolution evolve <skill-id>	Review and apply suggestions
/ork:skill-evolution history <skill-id>	Show version history
/ork:skill-evolution rollback <skill-id> <version>	Restore previous version

---

How It Works

The skill evolution system operates in three phases:

COLLECT                    ANALYZE                    ACT
───────                    ───────                    ───
┌─────────────┐           ┌─────────────┐           ┌─────────────┐
│ PostTool    │──────────▶│ Evolution   │──────────▶│ /ork:skill- │
│ Edit        │  patterns │ Analyzer    │ suggest   │ evolution   │
│ Tracker     │           │ Engine      │           │ command     │
└─────────────┘           └─────────────┘           └─────────────┘
     │                          │                          │
     ▼                          ▼                          ▼
┌─────────────┐           ┌─────────────┐           ┌─────────────┐
│ edit-       │           │ evolution-  │           │ versions/   │
│ patterns.   │           │ registry.   │           │ snapshots   │
│ jsonl       │           │ json        │           │             │
└─────────────┘           └─────────────┘           └─────────────┘

Load details: Read("${CLAUDE_SKILL_DIR}/rules/pattern-detection-heuristics.md") for tracked edit patterns and detection regexes. Load details: Read("${CLAUDE_SKILL_DIR}/rules/confidence-scoring.md") for suggestion thresholds.

---

Subcommands

Each subcommand is documented with implementation details, shell commands, and sample output. Load details: Read("${CLAUDE_SKILL_DIR}/references/evolution-commands.md")

Report (Default)

/ork:skill-evolution — Shows evolution report for all tracked skills with usage counts, success rates, and pending suggestions.

Analyze

/ork:skill-evolution analyze <skill-id> — Deep-dives into edit patterns for a specific skill, showing frequency, sample counts, and confidence scores.

Evolve

/ork:skill-evolution evolve <skill-id> — Interactive review of improvement suggestions. Uses AskUserQuestion for each suggestion (Apply / Skip / Reject). Creates version snapshot before applying.

History

/ork:skill-evolution history <skill-id> — Shows version history with performance metrics per version.

Rollback

/ork:skill-evolution rollback <skill-id> <version> — Restores a previous version after confirmation. Current version is backed up automatically.

---

Data Files

File	Purpose	Format
.claude/feedback/edit-patterns.jsonl	Raw edit pattern events	JSONL (append-only)
.claude/feedback/evolution-registry.json	Aggregated suggestions	JSON
.claude/feedback/metrics.json	Skill usage metrics	JSON
skills/<cat>/<name>/versions/	Version snapshots	Directory
skills/<cat>/<name>/versions/manifest.json	Version metadata	JSON

---

Auto-Evolution Safety

Load details: Read("${CLAUDE_SKILL_DIR}/rules/auto-evolution-triggers.md") for full safety mechanisms, health monitoring, and trigger criteria.

Key safeguards: version snapshots before changes, auto-alert on >20% success rate drop, human review required, rejected suggestions never re-suggested.

---

References

Load on demand with Read("${CLAUDE_SKILL_DIR}/references/<file>"):

File	Content
evolution-commands.md	Subcommand implementation, shell commands, and sample output
evolution-analysis.md	Evolution analysis methodology
version-management.md	Version management guide

Rules

Load on demand with Read("${CLAUDE_SKILL_DIR}/rules/<file>"):

File	Content
pattern-detection-heuristics.md	Edit pattern categories and regex detection
confidence-scoring.md	Suggestion thresholds and confidence criteria
auto-evolution-triggers.md	Safety mechanisms and trigger criteria

---

Related Skills

• ork:configure - Configure OrchestKit settings
• ork:doctor - Diagnose OrchestKit issues
• feedback-dashboard - View comprehensive feedback metrics