| name | optimize-skills |
| description | Mine past Claude Code session transcripts for recurring friction — problems the user had to find manually, corrections, repeated tool errors, hand-rolled loops — and turn the patterns into skill gotchas, memory entries, or CLAUDE.md rules. Use when asked to optimize the skills, run a retro, review past sessions, or find recurring problems. |
Session retro: mine friction, improve the loops
Past sessions are data. This skill extracts friction signals from the
transcript JSONL files and converts recurring patterns into fixes in
the right place: a gotcha in an existing skill, a memory entry, a
CLAUDE.md rule, or a new skill/command proposal. Transcripts live
under ~/.claude/projects/<slug>/, where the slug is the absolute
repo path with / replaced by - — derive it from the working
directory instead of hardcoding a machine-specific path. The files
are megabytes — never read them raw, always extract with jq.
1 · Extract (per transcript)
ls -S ~/.claude/projects/$(pwd | tr '/' '-')/*.jsonl
Four extractors, each verified against real transcripts. FILE is
one transcript path:
User texts — the user's own words: bug reports the assistant
missed, corrections, re-instructions:
jq -r 'select(.type=="user") | .message.content | if type=="string" then . elif type=="array" then (map(select(.type=="text") | .text) | join(" ")) else empty end' FILE | grep -v '^$' | grep -v '^<' | head -80
Tool errors, deduplicated by class:
jq -r 'select(.type=="user") | .message.content[]? | select(type=="object" and .type=="tool_result" and .is_error==true) | .content | if type=="string" then . elif type=="array" then (map(.text? // empty) | join(" ")) else empty end' FILE | cut -c1-200 | sort | uniq -c | sort -rn | head -20
Interruptions (user broke in mid-action — scoped to user entries,
see Gotchas):
jq -r 'select(.type=="user") | .message.content | if type=="string" then . else empty end' FILE | grep -c 'Request interrupted by user'
Command repetition (hand-rolled loops a skill should own):
jq -r 'select(.type=="assistant") | .message.content[]? | select(type=="object" and .type=="tool_use" and .name=="Bash") | .input.command' FILE | awk '{print $1, $2}' | sort | uniq -c | sort -rn | head -10
2 · Judge into categories
- undetected-problem — the user reports something broken that the
assistant did not catch itself (found via manual testing, the live
site, a screenshot). The most valuable signal: each one means a
verification loop has a hole.
- user-correction — the user redirects („nein", „nicht so",
switching tool/approach).
- recurring-tool-error — same error class ≥ 3× (permission
denials, missing flags,
/api-prefix 404s, wrong package manager).
- manual-repetition — the same command sequence run many times
(dozens of
gh run list / gh pr checks cycles = the loop belongs
in a skill or command).
- workflow-friction — anything else that cost a round trip
(blocked sleeps, stalled background waits, harness denials).
Ignore: routine output, system reminders, skill/command texts pasted
into user messages, one-off typos, and the expected chatter of
pipeline babysitting (bulk-generate monitoring output is high-volume
by design — only its failures and hand-rolled polling loops count
as friction).
3 · Scale: fan out for many sessions
For 1–2 transcripts, run the extractors inline. For more, use a
Workflow: one mining agent per transcript (each runs the §1
extractors and returns structured findings), then a single synthesis
agent that clusters across sessions, ranks by sessions × frequency,
and — after reading the current skill files — proposes only fixes
that aren't already documented.
4 · Convert patterns into fixes
Route each accepted pattern to where it prevents the recurrence:
- behaviour during verification/shipping → a gotcha/step in the
matching
.claude/skills/ skill (verify-*, open-pr)
- repeatable multi-step procedures → an
agentic/commands/*.md
command (edit there, never in .claude/commands/ — it's a
symlink)
- environment/infra knowledge → a memory entry under
~/.claude/projects/<slug>/memory/ (update existing files before
creating new ones; keep the MEMORY.md index in sync)
- session-spanning working rules → CLAUDE.md (duplicate into
.github/copilot-instructions.md only if it's a repo/domain rule
the reviewer bot needs, not a Claude-harness rule — and honor the
declared sync duties between the two)
Apply small, low-risk fixes (gotchas, memory) directly and list them;
anything touching settings, hooks, workflows, or new repo code is a
recommendation for the user, not a unilateral change. Repo-file
changes ship as a normal PR through /open-pr (changelog entry
included).
Gotchas
- Workflow
args can arrive undefined — inline the transcript
file list in the script body instead of passing it via args.
.message.content is string OR array depending on entry type —
both extractor branches are needed, otherwise jq silently drops
half the messages.- User-text extraction picks up pasted skill instructions and
command output; the
grep -v '^<' filter drops system-reminder
blocks, the rest needs judgment in §2.
- Transcripts may contain secrets (env output, tokens). Findings
quote error classes, never raw transcript lines with values, and
nothing from a transcript gets committed verbatim.
- The current session is in the list — including it is fine (its
friction is the freshest), but its file keeps growing while you
mine; frequencies for it are a snapshot.
- A raw
grep -c for interruptions false-positives when the
transcript embeds skill/command text containing the phrase (this
SKILL.md being read or written mid-session once produced 4 phantom
interruptions) — hence the jq-scoped extractor above; verify
nonzero counts against entry context.
- Transcript retention is limited (old sessions are cleaned up) —
run this regularly (e.g. a weekly/monthly cadence) or the friction
history evaporates before it's mined.
Troubleshooting
- jq prints nothing for a file that clearly has content → you are
filtering on the wrong
.type; inspect first:
jq -r '.type' FILE | sort | uniq -c.
