---
name: self-improving-skills
description: >
  Observe, inspect, amend, and evaluate agent skills and agent-level learnings
  using a structured self-improvement loop. Use when: (1) a skill or agent task
  fails and needs to be logged, (2) error patterns accumulate and need inspection,
  (3) a skill patch or agent rule is proposed based on evidence, (4) evaluating
  whether a previous amendment improved outcomes, (5) promoting a validated
  learning to AGENTS.md, (6) rolling back an amendment that degraded performance,
  (7) reviewing the health of the self-improvement system across agents or skills.
  Triggers on: "log this error", "what keeps failing", "why did that break",
  "propose a skill fix", "evaluate the patch", "promote this learning",
  "roll back", "self-improvement status", "learnings report", "skill health".
---

# Self-Improving Skills

A disciplined loop for agent and skill self-improvement:
**Observe → Inspect → Amend → Evaluate**

No amendment without evidence. No promotion without validation. No lost originals.

## Architecture

Two layers share the same loop but operate at different scopes:

| Layer | Scope | Storage | Amend approval |
|-------|-------|---------|----------------|
| **Agent** | Per-agent mistakes and rules | `workspace-{agent}/.learnings/` | Auto-log, human-approve promote |
| **Skill** | Shared skill instructions | `{skill-dir}/.learnings/` | Human-approve ALL patches |

## Directory Structure

### Agent layer (per workspace)
```
workspace-{agent}/
├── AGENTS.md              ← promoted rules (battle-tested)
├── MEMORY.md              ← context, decisions, roster
├── .learnings/
│   ├── ERRORS.md          ← raw error log
│   └── LEARNINGS.md       ← validated corrections
```

### Skill layer (per installed skill)
```
skills/{skill-name}/
├── SKILL.md               ← current instructions
├── .learnings/
│   ├── RUNS.md            ← invocation log (observe)
│   ├── ERRORS.md          ← failure log (observe)
│   ├── PATCHES.md         ← proposed/applied amendments
│   └── versions/
│       └── SKILL.md.v{N}  ← snapshot before each patch
```

---

## The Loop

### 1. Observe — Log Every Run

**When:** After every skill invocation or notable agent task outcome.

**Agent errors** → append to `workspace-{agent}/.learnings/ERRORS.md`:
```markdown
## {ISO-timestamp} — {short description}
- **Task:** What you were doing
- **Error:** What went wrong
- **Root cause:** Why (if known), or "unknown — needs inspection"
- **Resolution:** How it was fixed (or "unresolved")
- **Class:** {error-category-tag}
```

**Skill runs** → append to `{skill-dir}/.learnings/RUNS.md`:
```markdown
## {ISO-timestamp} — {agent-id} — {outcome: success|partial|failure}
- **Task:** What was attempted
- **Skill version:** v{N} (current)
- **Steps completed:** {N}/{total}
- **Failure point:** {step or "none"}
- **Error:** {message or "none"}
- **Workaround:** {what the agent did differently, or "none"}
- **User feedback:** {if any, or "none"}
```

**Skill errors** → append to `{skill-dir}/.learnings/ERRORS.md` (same format as agent errors but with skill context).

**Automation:** Always log. No approval needed. This is observation, not modification.

### 2. Inspect — Detect Patterns

**When:** Same error class appears 2+ times, OR a skill's failure rate exceeds 30% over its last 10 runs.

**How to inspect:**

For agent errors:
```bash
# Count error classes
grep "^- \*\*Class:\*\*" .learnings/ERRORS.md | sort | uniq -c | sort -rn
```

For skill health:
```bash
# Success rate from RUNS.md
grep "outcome:" {skill-dir}/.learnings/RUNS.md | tail -10
```

**Output of inspection** — a pattern summary:
```markdown
### Pattern: {name}
- **Error class:** {tag}
- **Occurrences:** {N} times in {date range}
- **Affected:** {agents or skill name}
- **Common factor:** {what they share}
- **Proposed action:** {agent rule | skill patch | investigation needed}
```

Read `references/inspection-checklist.md` for the full diagnostic protocol.

### 3. Amend — Propose a Fix

**Critical rule: Never auto-apply skill patches. Always propose, never commit without approval.**

#### Agent-level amendment

When a pattern is confirmed, write to `workspace-{agent}/.learnings/LEARNINGS.md`:
```markdown
## {date} — {rule name}
- **Pattern:** What keeps going wrong
- **Evidence:** {dates of ERRORS.md entries}
- **Rule:** The specific behavior change
- **Validations:** 0 (pending)
- **Status:** active
```

Agent learnings are **active immediately** for the authoring agent (low risk — only affects one agent's behavior, easy to roll back).

#### Skill-level amendment

When inspection shows a skill needs patching:

1. **Snapshot current version:**
   ```bash
   cp {skill-dir}/SKILL.md {skill-dir}/.learnings/versions/SKILL.md.v{N}
   ```

2. **Write patch proposal** to `{skill-dir}/.learnings/PATCHES.md`:
   ```markdown
   ## Patch v{N+1} — {date} — PROPOSED
   - **Problem:** {what's failing}
   - **Evidence:** {RUNS.md and ERRORS.md references}
   - **Change:** {specific diff description}
   - **Risk:** {what could break}
   - **Rollback:** Restore from versions/SKILL.md.v{N}
   - **Success criteria:** {measurable — e.g., "error class X drops to 0 in next 5 runs"}
   - **Status:** proposed | approved | applied | evaluated | rolled-back
   ```

3. **Present to user for approval.** Include:
   - The evidence (error counts, failure patterns)
   - The specific change (as a diff or clear description)
   - The risk assessment
   - The success criteria
   - The rollback path

4. **On approval**, apply the patch, update status to `applied`, record the apply date.

Read `references/amendment-rules.md` for patch safety guidelines.

### 4. Evaluate — Measure and Decide

**When:** After a patch has been applied and enough runs have accumulated (minimum 5 runs or 7 days, whichever comes first).

**Evaluation process:**

1. Pull post-patch runs from `RUNS.md`
2. Compare against success criteria defined in the patch
3. Calculate:
   - **Success rate:** % of runs with outcome=success
   - **Error rate for target class:** did the specific failure decrease?
   - **Regression check:** did any NEW error classes appear?

4. **Decision matrix:**

| Success criteria met? | New regressions? | Action |
|----------------------|-------------------|--------|
| ✅ Yes | ❌ No | **Promote** — patch becomes permanent |
| ✅ Yes | ⚠️ Minor | **Keep + fix** — address regression separately |
| ❌ No | ❌ No | **Extend** — more data needed, keep observing |
| ❌ No | ✅ Yes | **Roll back** — restore from versions/SKILL.md.v{N} |

5. **Update PATCHES.md** with evaluation results and final status.

#### Promotion (agent layer)

When an agent learning has **2+ real-world validations** (the rule actively prevented an error it was designed to catch):

1. Update `LEARNINGS.md` entry: `Status: promoted`
2. Append rule to `AGENTS.md` with source reference
3. The learning is now permanent unless explicitly revised

#### Rollback

Rollback is always available because originals are preserved:
- **Agent rule:** Set status to `rolled-back` in LEARNINGS.md, remove from AGENTS.md
- **Skill patch:** Restore `versions/SKILL.md.v{N}`, update PATCHES.md status to `rolled-back`

---

## Commands Reference

Quick actions for the loop:

| Action | Command |
|--------|---------|
| Log agent error | Append to `.learnings/ERRORS.md` |
| Log skill run | Append to `{skill}/.learnings/RUNS.md` |
| Check skill health | `grep "outcome:" RUNS.md \| tail -10` |
| Find error patterns | `grep "Class:" ERRORS.md \| sort \| uniq -c \| sort -rn` |
| Snapshot before patch | `cp SKILL.md .learnings/versions/SKILL.md.v{N}` |
| Roll back skill | `cp .learnings/versions/SKILL.md.v{N} SKILL.md` |
| Promote agent rule | Move from LEARNINGS.md → AGENTS.md, set `Status: promoted` |

---

## Guardrails

1. **No silent amendments.** Every change is logged with rationale.
2. **No skill auto-patching.** Skill patches require human approval.
3. **No promotion without proof.** Agent rules need 2+ validated saves. Skill patches need success criteria met.
4. **No lost originals.** Versions directory preserves every pre-patch state.
5. **No compounding drift.** If a skill has had 3+ patches without a full review, flag it for human audit before any further amendments.
6. **Observation is free.** Logging runs and errors never requires approval. The data pipeline is always on.
7. **Rollback is instant.** Versions are plain files. Restoring is a file copy, not a rebuild.

## Health Check

Run periodically (or on request) to assess the system:

1. **Per agent:** Count errors in last 30 days, count active learnings, count promoted rules
2. **Per skill:** Success rate over last 10 runs, open patches, patch count (drift check)
3. **Cross-agent:** Same error class appearing across multiple agents → candidate for shared learning or skill patch

Read `references/health-check-protocol.md` for the full checklist.