skill-evolution
- Repo stars 175
- License MIT
- Author repo orchestkit
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 settingsork:doctor- Diagnose OrchestKit issuesfeedback-dashboard- View comprehensive feedback metrics
- Fluxly category
- Engineering · skill-management · evolution · versioning
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 100 / 100 · heuristic scan, not runtime safety proof
- Author / version / license
- @yonatangross · v1.0.0 · MIT
- Fluxly token estimate
- Lean
- Fluxly setup estimate
- Guided setup
- External API key
- No requirement detected
- Detected OS requirements
- Unspecified
- Runtime requirements
- Unspecified
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Detected network behavior
- Local-only
- Install commands
- None (reference only)
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
The current SKILL.md does not define a fixed output example. Reviewing how skills are performing across sessions Identifying patterns in user edits to skill outputs Applying learned improvements to skill templates
Command · Description /ork:skill-evolution · Show evolution report for all skills /ork:skill-evolution analyze <skill-id> · Analyze specific skill patterns
The skill evolution system operates in three phases: Load details: Read("${CLAUDESKILLDIR}/rules/pattern-detection-heuristics.md") for tracked edit patterns and detection regexes. Load details: Read("${CLAUDESKILLDIR}/rules/confidence-scoring.md") for…
Each subcommand is documented with implementation details, shell commands, and sample output. Load details: Read("${CLAUDESKILLDIR}/references/evolution-commands.md")
/ork:skill-evolution — Shows evolution report for all tracked skills with usage counts, success rates, and pending suggestions.
/ork:skill-evolution analyze <skill-id> — Deep-dives into edit patterns for a specific skill, showing frequency, sample counts, and confidence scores.
# 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 │
… Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.
sections -> Overview → Quick Reference → How It Works → Subcommands → Report (Default) → Analyze
terms -> Enables skills to automatically improve based on usage patterns, user edits, and success rates. · Load details: Read("${CLAUDESKILLDIR}/rules/pattern-detection-heuristics.md") for tracked edit patterns and detection regexes. · Each subcommand is documented with implementation details, shell commands, and sample output. · /ork:skill-evolution — Shows evolution report for all tracked skills with usage counts, success rates, and pending suggestions. · /ork:skill-evolution evolve <skill-id> — Interactive review of improvement suggestions. · /ork:skill-evolution history <skill-id> — Shows version history with performance metrics per version. · /ork:skill-evolution rollback <skill-id> <version> — Restores a previous version after confirmation. · Load details: Read("${CLAUDESKILLDIR}/rules/auto-evolution-triggers.md") for full safety mechanisms, health monitoring, and trigger criteria.
files/cmd -> /ork:skill-evolution · /ork:skill-evolution analyze <skill-id> · /ork:skill-evolution evolve <skill-id> · /ork:skill-evolution history <skill-id> · /ork:skill-evolution rollback <skill-id> <version> · Read("${CLAUDESKILLDIR}/rules/pattern-detection-heuristics.md") · Read("${CLAUDESKILLDIR}/rules/confidence-scoring.md") · Read("${CLAUDESKILLDIR}/references/evolution-commands.md")
body sha256 -> 4b1a13c173bb
Decide Fit First
Design Intent
How To Use It
Boundaries And Review