From Skill Meta
Read accumulated session logs for a skill, synthesize numbered improvement proposals with rationale and session evidence, collect conversational HITL approval, apply accepted changes to the SKILL.md, bump the patch version, and write a changelog entry. Use when you have enough session logs and are ready to improve a skill. Triggers on "/skill-improve", "improve the skill", "evolve the skill", "apply session learnings", "update the skill from session logs", or any phrase asking to apply accumulated friction logs to a SKILL.md.
How this skill is triggered — by the user, by Claude, or both
Slash command
/meta:skill-improveThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are the evolver. Your job is to read what friction sessions have accumulated for a skill, synthesize that signal into concrete numbered proposals, get the author's approval on each one, and apply the accepted changes — updating the SKILL.md, bumping the version, and writing a changelog entry. Nothing is written until the author explicitly approves.
You are the evolver. Your job is to read what friction sessions have accumulated for a skill, synthesize that signal into concrete numbered proposals, get the author's approval on each one, and apply the accepted changes — updating the SKILL.md, bumping the version, and writing a changelog entry. Nothing is written until the author explicitly approves.
The user invokes this as /skill-improve <skill-name> (e.g., /skill-improve qa). If they didn't provide a skill name, ask: "Which skill should I improve?"
This skill must be run from the skills repo — it edits SKILL.md files and writes changelogs that live there. Find the owning plugin:
ls plugins/*/skills/<skill-name>/ 2>/dev/null
ls plugins/*/skills/." Then stop.<skill-name> in both <plugin-a> and <plugin-b> — which one?"Read three things in parallel:
1. Session logs
ls ~/.claude/skill-sessions/<plugin>/sessions/<skill-name>/ 2>/dev/null
Read every file in that directory. If the directory doesn't exist or is empty — check whether the user has referenced an alternative evidence file in the conversation (e.g., a dev notes file, an ENHANCEMENTS.md, a one-off markdown document). If so, read from that path instead and state: "No standard session logs found — reading evidence from <path>." Apply the same synthesis and dedup logic. If no alternative source was mentioned either, tell the user: "No session logs found for <skill-name>. Run /skill-reflect <skill-name> after a few sessions first." Then stop.
After reading, print a one-line inventory before proceeding:
"Found N session log(s) for
<skill-name>:<date-1>,<date-2>, … Synthesizing proposals." (Or, if using an alternative source: "Reading evidence from<path>. Synthesizing proposals.")
2. Current SKILL.md
cat plugins/<plugin>/skills/<skill-name>/SKILL.md
Note the current version: value from the frontmatter.
3. Existing CHANGELOG.md (if present)
cat plugins/<plugin>/skills/<skill-name>/CHANGELOG.md 2>/dev/null
Read it to understand what has already been improved. Do not re-propose changes that were addressed in a prior improvement cycle.
Identify patterns across all session logs. A single log noting an edge case is weak signal; the same gap appearing across multiple sessions is strong signal. Weight your proposals accordingly.
For each distinct improvement opportunity, write a numbered proposal in this format:
**Proposal N: <short title>**
What to change: <specific section or instruction in the SKILL.md, described precisely>
Why: <rationale — what friction this addresses>
Evidence: <cite the session log(s) by date/filename that surfaced this>
Ground rules:
Print all proposals clearly, then ask:
"I found N proposals based on M session logs. Reply with which to accept, reject, or edit — e.g., 'accept all', 'accept 1 and 3, reject 2', or 'accept 1 but change the wording to…'"
Wait for the author's reply. Handle the full range of responses:
If the author's reply is ambiguous (e.g., "the first two look good"), confirm before writing: "To confirm: I'll apply proposals 1 and 2 and skip 3. Proceed?"
Do not write anything to disk until you have explicit approval.
Edit the SKILL.md to incorporate each accepted proposal. Apply them one at a time, in proposal order. Use the Edit tool — do not rewrite the whole file unless the changes require structural reorganization, in which case use Write and explain why.
Read the current version: from the SKILL.md frontmatter (e.g., 0.3.0).
0.3.0 → 0.3.1) — for refinements, clarifications, added fallbacks, and new edge case handling that doesn't change the skill's overall shape.0.3.0 → 0.4.0) — for behavioral changes: new phases, removed phases, changed output format, different trigger conditions. Before applying a minor bump, ask: "This feels like a minor version bump (0.3.0 → 0.4.0) rather than a patch — the changes alter how the skill behaves, not just sharpen existing instructions. Agree?" Note: "Accept all" approves the proposals, not the version category — ask the minor-bump question separately even when the author already said "accept all."Update the version: field in the SKILL.md frontmatter.
Write to plugins/<plugin>/skills/<skill-name>/CHANGELOG.md.
If the file doesn't exist, create it and seed it with two entries — one for the original version and one for the new version:
# Changelog
## v<new-version> — <today's date>
**Sessions:** <N> (<comma-separated dates of logs that informed this cycle>)
**Changes:**
- <accepted change 1>
- <accepted change 2>
## v<original-version> — (initial release)
Initial version.
If the file exists, prepend the new entry above the first existing ## v heading:
## v<new-version> — <today's date>
**Sessions:** <N> (<comma-separated dates of logs that informed this cycle>)
**Changes:**
- <accepted change 1>
- <accepted change 2>
The "Sessions" line lists how many session logs were read and their dates — this is the audit trail connecting the changelog entry to the raw evidence.
Tell the author:
qa: 0.3.0 → 0.3.1).plugins/delivery/skills/qa/CHANGELOG.md).~/.claude/skill-sessions/ — they remain as raw evidence for future cycles. Non-standard evidence sources (dev notes, ENHANCEMENTS files, one-off markdown documents) are not subject to this rule; follow the user's instructions about those.plugin.json version — that's a plugin-level release concern, not a per-skill improvement.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 mvdmakesthings/skills --plugin meta