From dev-toolkit
Analyze a Claude Code session transcript to find friction points with skills that were used, then propose targeted edits to those skills' SKILL.md files. Use this skill whenever the user wants to improve, tune, refine, sharpen, retrospect on, or learn from a Claude Code session — especially when they mention reviewing skill performance, skills that "didn't work right", skills the user had to correct, or anything about making skills better based on real usage. Trigger on phrases like "improve the skills I used", "what could my skills do better", "review this session for skill issues", "sharpen my skills", "skill retro", "tune my skills", or `/skill-sharpener`. Also trigger when the user expresses frustration with how a skill behaved and wants to fix it for next time. Output is a markdown proposal per skill (problems found + suggested edits) for user approval before any SKILL.md changes are written.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dev-toolkit:skill-sharpenerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Mine session history for evidence of skill friction. Propose fixes. Let user approve before editing.
Mine session history for evidence of skill friction. Propose fixes. Let user approve before editing.
Skills are durable instructions. They get used many times across many sessions. A single bad instruction or missing guardrail compounds. Real session transcripts contain the best signal about what skills actually need — better than guessing or asking the user to articulate it.
But session JSONL is noisy. The user changes their mind, asks tangential questions, or corrects Claude for reasons unrelated to the skill. Auto-editing skills from raw signal produces churn. So this skill takes a careful approach: gather evidence, present a proposal, let the human decide.
No auto-edits. Every change goes through user review.
Sessions live at ~/.claude/projects/<encoded-project-path>/<session-uuid>.jsonl.
Default: analyze the current session. Find the active JSONL by matching the project's
encoded path (replace / with -) under ~/.claude/projects/, then pick the most recently
modified .jsonl.
Ask the user to confirm:
Analyze current session? (default: yes)
Or provide path to a specific session JSONL:
If the user passes a session UUID or partial filename, search and resolve it.
Read the JSONL and scan for Skill tool invocations. The relevant events look like:
{"type":"tool_use","name":"Skill","input":{"skill":"<name>","args":"..."}}
Build a list of unique skills invoked in the session. For each, record:
If no skills were invoked, report that and stop. Nothing to sharpen.
Present the skill list to the user before proceeding. Show a numbered list:
Skills used this session:
1. <skill-name> (N invocations)
2. <skill-name> (N invocations)
...
Which skills should I analyze? (e.g., "1, 3" or "all")
Wait for the user's selection. Only proceed with Step 3 for the chosen skills. This avoids generating proposals for skills the user doesn't want to review.
For each skill invocation, look at the surrounding turns and flag these signals:
Strong signals (skill likely needs change):
Weak signals (might be skill, might be user):
Not signals (ignore):
For each strong signal, capture:
Skills with zero strong signals get no proposal. Skip them.
For each skill with strong signals, locate its SKILL.md. Skills live in:
~/.claude/skills/<name>/SKILL.md (user-global)~/.claude/plugins/cache/**/skills/<name>/SKILL.md (plugin-installed)<project>/.claude/skills/<name>/SKILL.md (project-local)Read the SKILL.md so the proposal can reference exact sections.
Output one markdown proposal per skill. Use this template:
# Sharpener Proposal: <skill-name>
**Skill path:** <absolute path to SKILL.md>
**Invocations this session:** <count>
## Friction Observed
### 1. <Short title of issue>
**Evidence (from session):**
> <quoted user correction or friction moment>
**Root cause:** <why the skill failed here — missing instruction, ambiguous wording, wrong default, etc.>
**Suggested edit:**
- Section: <heading from SKILL.md, or "new section">
- Change:
```
becomes
```
```
- Rationale:
...
Things that looked like signals but probably aren't worth changing:
Show all proposals to the user at once. Then ask:
Which edits should I apply? (e.g., "1, 3" or "all" or "none")
## Step 6: Apply Approved Edits
For each approved edit, use the Edit tool against the relevant SKILL.md. Make minimal changes —
don't rewrite sections that weren't flagged. Don't add hypothetical guardrails for problems the
session didn't surface.
After applying edits, show the user:
- Files changed
- Diff summary (one line per edit)
- Reminder: skill changes don't apply retroactively to past sessions
## Principles
**Bias toward fewer, better edits.** One precise change beats five speculative ones. If you're
not sure an edit is justified, skip it and tell the user why.
**Quote evidence.** Every proposed edit should cite a specific moment from the transcript. If
you can't quote evidence, you don't have a signal — drop the proposal.
**Explain the why.** Don't just say "add MUST X". Explain why the skill failed, what change
addresses the root cause, and why it won't overfit to this one session.
**Don't oversteer.** Skills get worse when they accumulate rigid `ALWAYS`/`NEVER` rules from
one-off corrections. Prefer reframing or clarifying intent over adding constraints.
**Respect skill scope.** If the friction was outside what the skill is supposed to do, that's
not a skill bug. Note it and move on.
## Edge Cases
- **Session has no Skill invocations** → report and stop. Suggest user invoke skills they want
to evaluate, then rerun.
- **SKILL.md is read-only or in a plugin cache** → flag clearly. Plugin skills typically
shouldn't be edited in place; suggest forking to user-global skills instead.
- **Multiple invocations of same skill, conflicting signals** → present both, let user weigh.
- **User wants to analyze a different session than current** → accept path or UUID, validate
before reading.
## Configuration
- `SHARPENER_SESSIONS_DIR` — override session JSONL location (default: `~/.claude/projects/`)
- `SHARPENER_SKILLS_DIRS` — comma-separated list of skill search paths
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub alton09/q-skills --plugin dev-toolkit