---
name: skill-evolve
description: The improvement loop for SKOA's skill library: how an agent records what happened in a run, and how a revised SKILL.md with a new version is produced from those run notes. Use after running any skoa-* skill when something surprised you, or when asked to improve, version or review a skill.
---

# Improve a skill from its runs

Every skill in `skills/` is versioned in `skills/library.json`. Skills get better from evidence, not from opinion: a run leaves a note, the notes are turned into a revision, the revision gets a version and a changelog line, and the web library at `/skills/` is rebuilt from the same files.

## 1. Leave a run note

After using a skill, if anything was wrong, missing, slower than needed or surprising, write `skills/<name>/runs/YYYY-MM-DD-<short-slug>.md`:

```
# <one-line title>
Context: what was asked, where it ran (local, Hermes cron, CI), date.
What happened: facts, with the exact error text or output if short.
What the skill got wrong or missed: the gap between the instructions and reality.
Suggested change: one or two sentences, optional.
```

A run that went exactly as written needs no note. Never put secrets, personal data or credentials in a note.

## 2. Evolve

`npm run skills:evolve -- --skill <name>` (or `--all`). The script:

1. Collects the run notes not yet reviewed for that skill (`reviewedRuns` in `library.json`).
2. Sends the current SKILL.md plus the notes to Claude Code in headless mode (`claude -p`) and asks for a revised SKILL.md and a one-line changelog, or for "no change" if the notes do not justify one.
3. Validates the proposal (same `name`, a description, the same frontmatter keys), writes the new SKILL.md, bumps the patch version, appends `{date, version, note, runs}` to the skill's history and marks the notes as reviewed.

Use `--dry-run` to print the proposal without writing. Review the diff like any other change: the loop proposes, a person merges.

## 3. Publish

`npm run skills:build` regenerates `/skills/` (EN and ES) and `/skills/index.json` from `skills/`. Commit the skill, the library and the generated pages together, with the changelog line as the commit subject.

## Rules

- Keep instructions short and operational; delete anything the notes prove unnecessary.
- A bigger change (new section, new tool, changed scope) bumps the minor version by hand in `library.json`.
- Frontmatter stays standard (`name`, `description`); versions and history live only in `library.json`.