| name | skill-retro |
| description | Monthly evidence-driven retrospective of this kit's skills: gather friction logs, invocation traces, PR outcomes and docs drift, then propose SKILL.md fixes as a draft PR — only where evidence exists. No evidence → no change. |
| argument-hint | (none — runs one monthly retro pass) |
| disable-model-invocation | true |
/skill-retro
One evidence-driven retro pass over this kit's skills. The core rule:
no evidence, no change — skills are never rewritten on calendar cadence or
taste; every proposed edit must cite a concrete friction, outcome, or docs
drift. This skill is itself in scope (dogfooding).
Respond in the user's conversation language. Skip narration between tool
calls — this may run unattended as a scheduled routine.
1. Enumerate scope
Skills = directories with a SKILL.md in the claude-kit checkout's skills/.
Locate the checkout: if ~/.claude/skills is a symlink (the kit's symlink
install), follow it to the repo root; otherwise ask the user where the
claude-kit checkout lives. If no writable checkout exists (plugin-only
install), still run the evaluation and report the verdicts — skip only the
PR delivery step. Also note the always-loaded rules skills
rely on (the kit's rules/*.md, and the user's global CLAUDE.md sections such
as Plan & Delegate / Skill Feedback Capture) — the thing that needs fixing may
be a rule, not a skill.
2. Gather evidence (cheap first, expensive only if warranted)
- Friction logs — read
~/.claude/skill-feedback/*.md. This is the
primary signal (self-reported deviations, user corrections, uncovered
judgment calls).
- Invocation traces — mine
~/.claude/projects/*/ session logs for the
last month: count invocations per skill (search for skill names /
<command-name> markers). For skills with hits, sample at most 10
excerpts total across all skills, preferring sessions where the user's
next message after skill output looks corrective. Do not read whole
transcripts.
- Outcome data (only if /dispatch was used this month) — for open or
recently merged PRs on
dispatch/* branches (gh pr list --search), note
CI failures and review-comment counts: a high rate means dispatch's
verification or review stage is leaking defects.
- Docs drift — ONLY for skills that had activity or friction this month:
collect their load-bearing assumptions about Claude Code behavior (e.g.
skill invocation rules, worktree isolation semantics, hook events,
permission rule syntax, subagent output caps) and verify them in ONE
batched check against current official docs — via a
claude-code-guide
subagent if that agent type is available, else one WebFetch pass over the
relevant docs pages.
Early exit: if friction logs are empty AND invocation traces show no
corrective signals AND outcomes are clean, print one line
(e.g. 🔁 no evidence this month — no skill changes (N skills, M invocations))
and stop. Skip the docs-drift check entirely in that case.
3. Synthesize per-skill verdicts
For each skill: no change (state why in ≤1 line) or proposed fix —
each proposed edit paired with its evidence (feedback line, transcript
excerpt, outcome stat, or docs citation). Distinguish:
- fix the skill (instructions unclear / wrong assumption)
- fix a kit rule or the user's global rule instead (friction shared across
skills) — kit rules go in the same PR; global-CLAUDE.md fixes are reported
as recommendations (they live in the user's dotfiles, outside this repo)
- retire/merge (skill unused for 2+ retros and duplicated elsewhere — propose,
never delete unilaterally)
4. Deliver as a draft PR to claude-kit
If there are proposed edits:
- In the kit checkout: branch
skill-retro/YYYY-MM from the default branch
(never commit to main directly).
- Apply the SKILL.md / rules edits, keeping README.md's Contents list in
sync.
- Run
./scripts/scrub-check.sh — it must PASS before pushing (per-user
evidence must not leak into the shared repo: cite dates and session
projects, not absolute personal paths or transcript contents).
- Commit (repo conventions), push,
gh pr create --draft --assignee @me.
PR body: one section per skill — evidence → change pairs, so the human
can judge each edit independently.
- Archive consumed feedback lines: move them from
~/.claude/skill-feedback/<skill>.md into
~/.claude/skill-feedback/archive/YYYY-MM.md so next month's retro starts
clean. Leave unaddressed lines in place.
Final report: verdict table (skill / evidence / verdict) + PR URL if created.
Constraints
- Never edit skills in place on main — all changes go through the draft PR.
- Token guard: one pass, at most one docs-drift check (one subagent call or
one WebFetch batch), at most 10 transcript excerpts. Do not loop or
re-verify.
- Evidence citations in the PR must be specific (dated feedback line, session
date, PR number, doc URL) — no "feels outdated".
