---
name: experience-to-skill
description: Turn repeated agent successes, failures, and corrections into an evidence-linked wiki and one reviewable Skill change, then gate the candidate against validation and protection cases. Use when evolving a SKILL.md from multiple task runs; do not use for one-off fixes, automatic self-modification, or model training.
---

# Experience to Skill

Compile observed task experience into durable knowledge before changing executable guidance. Keep evidence, interpretation, and active skills separate.

This is a practical, safety-bounded adaptation of the WikiSkill research pattern. It is not the authors' official implementation and does not reproduce their benchmark harness.

## Choose the mode

- **Initialize or record:** create an evolution workspace or add an explicitly supplied, redacted run artifact.
- **Distill:** compare passing, failing, and corrected runs; update a reusable pattern or mark the evidence insufficient.
- **Propose:** turn supported patterns into one atomic create-or-patch proposal for one Skill.
- **Gate:** compare baseline and candidate on held-out failure and protection cases, then accept, reject, or hold.
- **Curate:** supersede disputed or stale patterns and compact the index without deleting raw evidence.

For any write, read [references/workspace-contract.md](references/workspace-contract.md). Before ingesting a trace, read [references/security-and-privacy.md](references/security-and-privacy.md). For proposing or gating, also read [references/evaluation.md](references/evaluation.md).

## Non-negotiable boundaries

1. Preserve the user's requested outcome, target Skill, and delivery surface. Learning from runs does not authorize changing a different capability, repository, or public artifact.
2. Treat only observable artifacts as evidence. Never claim access to provider-hidden reasoning or reconstruct missing events as fact.
3. Keep the active task executor isolated from the full wiki during baseline and candidate runs. It may receive the active Skill and normal task context, not the maintainer's accumulated explanations.
4. Do not promote a lesson from one anecdotal failure. A pattern needs either two independent supporting runs or one deterministic reproducer plus a distinct protection case.
5. Keep counterevidence, failed proposals, and rejected diffs. A rejected Skill edit must remain visible in the impact log so it is not proposed again under a new name.
6. Propose one atomic change to one Skill per iteration. Do not simultaneously alter prompts, tools, memory, workflow, model, evaluator, or permissions.
7. The proposer may not modify the tasks, answers, evaluator, isolation boundary, acceptance rule, or approval authority.
8. Never apply, install, publish, or push a candidate merely because its gate says `accept`. Review the diff and obtain whatever authorization the target mutation normally requires.
9. Keep raw evidence local by default. Only reviewed, redacted patterns and Skill artifacts belong in a public repository.
10. Stop when evidence is insufficient, validation is noisy, or the candidate only shifts failures elsewhere. Return `hold` with the missing evidence instead of inventing confidence.

## Workflow

### 1. Frame the learning question

Write down:

- the target `SKILL.md` or the proposed new Skill;
- the recurring behavior to improve;
- the primary outcome metric;
- at least one failure case and one protection case;
- surfaces that must remain unchanged;
- the current active Skill hash or an explicit `none` baseline.

If the request is only to fix the current task, fix it directly under the user's scope; do not start an evolution workspace.

### 2. Create or resume the three-layer workspace

Use `scripts/init_workspace.py` for a new workspace. Resume an existing workspace only after `scripts/validate_workspace.py` passes.

- `raw/`: explicitly supplied task inputs, observable traces, outcomes, corrections, gaps, and content hashes. Treat it as append-only.
- `wiki/`: concise pattern pages, an index, chronological findings, and every proposal decision.
- `skills/`: candidate Skill artifacts only. Keep the active Skill outside this layer until an accepted proposal is reviewed and authorized.

Do not silently reset the wiki between iterations. Do not delete raw evidence during curation.

### 3. Record evidence

Use `scripts/record_evidence.py` only with an explicitly selected, redacted trace file. Record provenance, outcome, available score, task identity, and observation gaps.

Sample both success and failure evidence. A useful default for a large batch is up to five failures and three passes, selected for diversity rather than recency alone. Keep a run if it contradicts the current hypothesis.

### 4. Distill patterns

Compare actual actions and outcomes. Diagnose the mechanism, not just the error message.

Each pattern should state:

- problem or successful strategy;
- root cause or enabling condition;
- supporting evidence and counterevidence;
- concrete workaround or reusable action;
- scope, compatibility, and known limits;
- status: `candidate`, `active`, `disputed`, `superseded`, or `archived`.

Prefer updating an existing pattern over creating a duplicate. Keep the index entry specific enough to decide relevance without opening the page.

### 5. Propose one Skill change

Read the wiki index, the impact log, relevant pattern pages, and selected raw traces. Check whether the same intervention was rejected before.

Create either:

- a new candidate Skill with `SKILL.md` and `PURPOSE.md`; or
- a minimal patch to one existing Skill.

The proposal must name its motivating patterns, expected effect, non-goals, compatibility assumptions, and validation plan. Prefer a general procedure over a model-specific workaround. If a workaround is model- or tool-specific, label it and test transfer separately.

Treat a change as atomic when it alters one intervention point for one mechanism hypothesis. Several safeguards at that same point may stay together only when the frozen cases test them as one behavior; otherwise split them across proposals.

### 6. Gate in isolation

Run baseline and candidate against the same frozen cases and evaluator in isolated contexts. Do not let candidate generation alter the cases or scores.

Use `scripts/gate_candidate.py` for a deterministic decision once case scores and required checks are available. The default gate requires:

- at least one failure case improves;
- mean failure-case score improves strictly beyond the configured threshold;
- no failure or protection case regresses;
- structure, security, scope, and evaluator-integrity checks all pass.

Back every required check with a hashed JSON `check_evidence` file bound to the candidate hash. A boolean without a resolvable validator output, review record, hash, or isolation basis is incomplete evidence and produces `hold`.

An `accept` decision means evidence supports review. `reject` means the candidate caused a measured regression or failed a required check. `hold` means the evidence is incomplete or non-comparable.

### 7. Record and hand off

Append the proposal identity, exact diff or artifact hash, baseline and candidate scores, decision, reason, and reviewer state to `wiki/skill-impact.jsonl`. Update the chronological log even when the proposal is rejected.

Return:

- the supported pattern and its evidence boundary;
- the exact candidate diff;
- the gate result and raw scorecard;
- observed regressions or uncertainty;
- whether the active Skill was left unchanged, applied locally, or published under separate authorization.

## Long-running maintenance

Review the wiki periodically. Merge duplicates, mark contradictions as disputed, supersede stale workarounds, and archive low-value pages from the index. Preserve raw artifacts and prior decision records so curation cannot rewrite history.

When the Skill library grows, evaluate retrieval and triggering separately. This workflow evaluates Skill quality; it does not prove that another agent will select the right Skill.