skill evolution

Engineering Community v1.0.0

Skill notes

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

How It Works

The skill evolution system operates in three phases: 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.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
100 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@yonatangross · v1.0.0 · MIT
Token usage
Lean
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
Network behavior
Local-only
Install commands
None (reference only)
Author source file SKILL.md

# 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

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.