Skill Lifecycle

Overview

A skill that stays in one session is forgotten by the next. This skill closes the loop: match → (criteria) → acquire → create → improve, so every decision either reuses a proven capability or leaves a trace for the future.

The deterministic part is run by a small router, node tools/skill-match.mjs (relative to this skill's own directory) — it does matching, usage logging, --feedback, --stats, --gaps. The judgment steps below are this protocol.

Stage 0 — MATCH (always, free)

node tools/skill-match.mjs "<task in your own words>" --json

Runs in well under a second. Don't ask yourself "do I need to search" — running it is mandatory for any non-trivial task. strong confidence → read the SKILL.md of the top result and use it.

Trigger criteria (expensive stages — only past this gate)

weak/none does NOT mean "this task has no skill for it". Ask yourself three questions honestly, out loud in your reasoning:

1. Will it repeat? Is this task part of a regular class (documents, releases, reports, generating artifacts, checks) — or a genuine one-off?
2. Would I get it wrong without instructions? Are there standards/regulations/ordering traps/house style where improvising would produce a defect or inconsistency?
3. Does someone else need this too? Should other engines/future sessions be able to do the same thing?

≥2 "yes" → go through the stages below. 0–1 "yes" → do the task by hand — but still leave feedback (see Stage 3).

Data beats intuition: --gaps shows whether this class of task has come up before and stayed without a skill — 2+ repeats in the gaps log is an automatic "yes" to question 1.

Stage 1 — ACQUIRE (find it in the world)

1. gh search repos "<2-3 key words> skill claude" --sort stars --limit 10
2. Catalogs: agentskills.io · plugin marketplaces (the ponytail/superpowers ecosystem) · awesome-claude-code
3. Found something worth it → install it (/plugin marketplace add <owner>/<repo> + /plugin install, or clone into your skills directory and enable it per your host's convention) → re-run match (should now be strong).
4. Read third-party skills before installing — skills execute as code inside your trusted context.

Stage 2 — CREATE (write it yourself)

Nothing suitable exists in the world → create it. REQUIRED SUB-SKILL: superpowers:writing-skills (Iron Law: baseline failure BEFORE writing the skill). Quality checklist: the official Anthropic Agent Skills best-practices doc (platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices). Place it in your skills directory, e.g. ~/.claude/skills/<name>/SKILL.md, then enable/sync per your host and repeat Stage 1.3.

Stage 3 — FEEDBACK (always, even without a skill)

• Used a skill → node tools/skill-match.mjs --feedback <skill> ok|fail --note "<what was wrong>" — a fail note should be specific, it becomes the spec for the improve stage.
• The match was noise → --feedback <top-match> fail --note "irrelevant to the request <...>".
• Did it by hand with no skill → write nothing: match already logged the gap, --gaps will surface it.

Stage 4 — IMPROVE (data-driven)

--stats surfaces a candidate (fail≥2 and fail>ok) → re-read its SKILL.md against the fail notes, improve it against the checklist, re-run the verification scenario. Improving a skill = editing a skill ⇒ the writing-skills Iron Law applies.

Stage 5 — HARVEST (reap lessons from shared memory)

Mistakes that live only in the log get repeated. Regularly (weekly review / after a major task) pull failures and lessons from your shared ledger — e.g. npx samemind ledger status (open failures) and recent fail-events — or run tools/skill-match.mjs --harvest if your team logs to a journal it can read.

Owner-grade thresholds:

• A substantive mistake needs to happen only ONCE. A behavior/method error (lost lines in a merge resolve, skipped post-release smoke, false "done", a skill's blind spot) → convert immediately: IMPROVE the existing skill (if it's that skill's blind spot) or CREATE a new one. The three questions are not needed — the mistake itself already answered "yes" on the cost of repetition.
• Reproducibility gate — when the mistake involves a tool or the environment. A tool refusal, permissions, config, version, sandbox: before CREATE/IMPROVE from a single occurrence, first reproduce the failure or find a second independent witness in the ledger. A one-off, unreproduced environment failure codified into a skill becomes learned helplessness — agents will route around a healthy tool forever (precedent: hermes-agent#6051, where a transient failure was captured as "this tool doesn't work" and the avoidance outlived the fix). No repro and no second witness → record it as a candidate (a note / --gaps) and convert on its second appearance. A purely behavioral mistake (no environment involved) needs no gate — the once-threshold stands.
• External failures don't count. server errors, network timeouts, a crashed service — that's not a skill lesson; it gets a fix/retry, not a skill.
• Neutral lessons (a discovery without a mistake) — go through the three questions as usual.

A lesson converted into a skill never repeats on any engine; a lesson left as a log entry repeats on the next one. One repetition is the maximum you allow yourself.

Rationalizations — don't say these to yourself

Red Flags — STOP and return to the protocol

• Solved a task by hand without running match first
• Said "not skill-shaped" without asking the three questions
• weak/none → straight to manual work, skipping the questions
• Used a skill — didn't leave feedback
• Editing a skill without a baseline test

Quick Reference