Skill loop

/skill-loop — your agent grows its own skills

The ruling this skill encodes: a brain that can't grow itself isn't a brain. Don't ask permission to build a skill. Detect → dedup → if genuinely new, write + install + self-test + announce. The user prunes after the fact. Growth by default, hygiene by check — no permission-slips.

This skill is both a capability you invoke (/skill-loop) and the standing procedure you follow automatically — if you hit a trigger mid-work, run the loop right there. Don't wait to be asked.

State files (created on first use, beside this skill)

• ~/.claude/skills/skill-loop/state/TALLY.md — the Pattern Tally (detection memory)
• ~/.claude/skills/skill-loop/state/LEDGER.md — the Birth Ledger (review queue: born / kept / pruned / near-misses)
• ~/.claude/skills/.pruned/ — the graveyard (pruned skills, archived not deleted)

If any is missing, create it from the templates in this skill's repo (templates/), or scaffold the headings shown below. Teams with a shared knowledge vault can relocate these — update the paths here once.

---

When to run (automatic triggers)

• Recurrence (tally-counted, not vibed) — a line in state/TALLY.md hits count 3. The tally is the loop's memory: a single session can't remember that a task-shape also appeared two sessions ago — the tally can. Your standing duty: whenever you notice a candidate pattern mid-work, increment its tally line (or add it at count 1, with date + 3-6 word context). At count 3, the loop fires.
• The user repeats an instruction — same multi-step "every time X, do Y" more than once → fire immediately, skip the tally (that's already strong evidence).
• Cross-project reuse — a procedure built for one project obviously fits another → fire immediately.

A pattern must be a procedure that produces a specific output, not a vibe. One-offs don't earn a slot.

Modes

• /skill-loop — full pass: read the Tally + recent work → run the loop on anything ripe.
• /skill-loop tally <pattern> — record/increment a pattern sighting without running the full loop.
• /skill-loop review — show the pending-review queue + PROPOSED block from the Ledger.
• /skill-loop prune <name> — retire a bad skill (archive, never hard-delete).
• (automatic) — no invocation; a trigger fires and you run the loop inline.

---

The loop

Step 1 — DETECT

Name the pattern in one sentence: "<procedure> that produces <specific output>." If you can't, it's not a skill yet — tally it if it might become one, otherwise drop it.

Step 2 — DEDUP-CHECK (before you write anything)

Search all of:

1. ~/.claude/skills/ — ls the dir; read the description: frontmatter of anything close.
2. Any project-level skills (.claude/skills/ in the repo you're working in).
3. Available tools/MCP servers — a connector may already do the job.
4. The graveyard: ~/.claude/skills/.pruned/ + the Ledger's 🗄️ PRUNED section. A match here is a hard stop on auto-birth — the user killed it once. Never silently rebirth: escalate to the Ledger's ⚖️ PROPOSED block with "you pruned this on <date> because <why>; the pattern has recurred — rebirth?" Only the user overrules the user.

Outcomes:

• Duplicate / near-duplicate (live) → do NOT birth. If the existing skill is close but incomplete, extend that skill instead. Log one line in the Ledger's 🚫 NEAR-MISSES section. Stop.
• Pruned-match → PROPOSED escalation as above. Stop.
• Genuinely new → Step 3.

Step 3 — JUDGE (earn the slot — all four required)

1. Reusable (not a one-off). 2. Specific output (a deliverable). 3. Distinct (Step 2 cleared).
2. Safe to auto-install (clears the Safety Carve-Out below).

• All four → Step 4. · Fails only #4 → propose (Ledger ⚖️ PROPOSED, tell the user), stop.
• Fails #1–3 → drop, log one line why (near-misses).

Step 4 — WRITE + INSTALL

1. Name it: kebab-case, specific verb-or-domain (release-notes-draft, not helper/utils/misc). Must not shadow any existing skill or command — you just listed them all in Step 2.
2. Create ~/.claude/skills/<name>/SKILL.md:
   • Frontmatter name: + a trigger-aware description: — the description is the ONLY thing that makes the skill auto-fire later. Required: (a) what it does, (b) 3+ concrete trigger phrasings a user would actually say, (c) one "do NOT use for X" clause. A vague description = a zombie skill that installs fine and never triggers.
   • The born: provenance block — no skill exists without one:

     born:
       date: <today>
       by: skill-loop
       trigger: "<the repeated pattern>"
       evidence: "<the tally line's seen: entries, or the repeated instruction refs>"
       status: pending-review   # pending-review | kept | pruned
     

   • Body: ## When to use / ## When NOT to use + a concrete ## Workflow (numbered, executable steps — written like the reader has never seen the pattern).

Installing = the file existing at ~/.claude/skills/<name>/SKILL.md — auto-discovered, no deploy step.

Step 4.5 — SELF-TEST (verify by DOING, not by reading)

Re-reading the file proves it exists, not that it works — and an unverified "done" is a lie the user acts on. Before announcing:

1. Take the actual instance(s) that triggered the birth (from the tally's seen: evidence).
2. Dry-run the skill's Workflow against one of them, following only what the file says — as if you'd never done the task before. Does it reproduce the work that birthed it, without you filling gaps from session memory?
3. Gaps found → fix the SKILL.md and re-test. A skill that can't reproduce its own birth evidence does not ship.
4. Record self-test: PASS (<instance tested>) in the Ledger entry.

Step 5 — ANNOUNCE

1. Append a birth entry to state/LEDGER.md — plain English: what it is, why it was born, self-test result, how to invoke, how to kill, status: pending-review.
2. Flip the pattern's tally line: → BORN /<name> <date>.
3. Tell the user in-session, plainly: "I built /<name> because <plain why>. Self-tested against <instance>. Invoke: /<name>. Say 'kill <name>' if it's dumb."
4. If the skills live in a git repo, commit: skill-loop: born /<name>.

---

Safety Carve-Out — what you must NOT auto-install

Growth-by-default covers capabilities and knowledge, never irreversible or outward actions. If the skill, when run, would send money · contact a real person · delete or overwrite data · touch credentials · take any hard-to-reverse outward action → PROPOSE, don't install (Ledger ⚖️ PROPOSED + tell the user). That one gate stays — the same "stop at the sensitive door" discipline a good operator applies to themselves.

Also: the skill file auto-installs freely, but a dependency it needs (pip/npm) still gets confirmed with the user before installing. Rate limit: ≤3 auto-births per pass; overflow queues as proposals so a noisy detector can't flood.

---

Pruning — /skill-loop prune <name> (hygiene by check)

1. Move ~/.claude/skills/<name>/ → ~/.claude/skills/.pruned/<name>/ (never hard-delete — archived ≠ forgotten; recoverable, and the graveyard is a dedup surface).
2. Flip the Ledger entry to status: pruned + one-line why + date. The why is load-bearing — it's what the rebirth guard quotes back if the pattern ever recurs.
3. Commit if in git.

Hard rules

• Tally, don't trust your memory — cross-session recurrence only counts if it's counted.
• Dedup everything, including the graveyard. Never silently rebirth what the user pruned.
• Earn the slot — reusable · specific output · distinct · safe.
• No zombie skills — trigger-aware description or it doesn't ship.
• Self-test before announce — a skill that can't reproduce its own birth evidence doesn't ship.
• Provenance always — no born skill without a born: block.
• Safety carve-out is not optional — outward/irreversible → propose, never auto-install.
• Never hard-delete — prune = archive + stamp.
• No lies — the Ledger says what the skill actually does, proven by the self-test.