/skill-retro

name: skill-retro
description: Use when reviewing how skills performed during a session, when the user wants to analyze skill invocations and identify improvements, or when the user says "skill retro", "review skills", "how did skills do", "improve this skill", or "skill retrospective".
user-invocable: true
disable-model-invocation: true

Skill Retro

Analyze how skills performed in the current session and apply improvements via skill-creator.

Process

Step 1: Preprocess Session

Run the preprocessing script to extract a clean transcript from the current session's JSONL log:

node ${CLAUDE_SKILL_DIR}/scripts/preprocess.mjs --cwd <current-working-directory>

Capture the JSON output. Key fields:

• `transcript_file` — path to the temp file containing the full transcript (at `~/.claude/tmp/skill-retro-<session-id>.json`)
• `stats.skill_invocations` — count of skills used

The script writes the full transcript to a temp file to avoid flooding the main thread's context window. Only the summary (stats + file path) appears in stdout.

**If the script fails** (e.g., no session files found), report the error and stop.

**If `skill_invocations` is 0**, tell the user: "No skills were invoked in this session — nothing to analyze." and stop.

Step 2: Analyze (Sub-Agent)

Spawn an analysis sub-agent (using the Agent tool, model: sonnet):

• Load the prompt from `${CLAUDE_SKILL_DIR}/references/analysis-prompt.md`
• Tell the agent to read the transcript file at the path from `transcript_file` in Step 1's output
• The agent should read the SKILL.md file for each invoked skill to compare intended vs. actual behavior. Skill paths are discoverable from the transcript's system-reminder blocks (which list installed skill base directories) or from `[SKILL INVOCATION]` markers combined with installed plugin cache paths.
• The agent returns a JSON object with `findings`, `well_executed`, and `severity_summary`

Parse the agent's response into structured findings.

Once the analysis agent has finished, **delete the temp file** created in Step 1:

rm <transcript_file>

**If the agent returns 0 findings**, tell the user: "All skills performed well this session. No improvements identified." Show the `well_executed` list and stop.

Step 3: Interpret and Recommend

Don't just present raw findings — interpret them. For each finding, add your own reasoning:

1. **What the fix looks like** — Is it a one-line description tweak? A new section in SKILL.md? A script rewrite? Be specific about what changes would actually be made. 2. **Effort estimate** — Quick fix (description/wording change), moderate (new section or error handling), or high-lift (architectural change, script rewrite, new scripts). 3. **Recommendation** — Whether to action it now, defer it, or skip it entirely. Explain why.

Group findings by skill and present with your interpretation:

## Skill Performance Report

### scheduler:manage (3 findings)

**1. [high] gap_coverage — pause command doesn't verify unload succeeded**
The `_launchctl_unload` helper silently swallows errors, so the registry can say "paused" while the job is still running.
- **Fix:** Add return-code checking to `_launchctl_unload` in the manage script, and add a post-unload verification step in SKILL.md's Pause operation.
- **Effort:** Moderate — script change + SKILL.md update
- **Recommend: Action** — This caused real user confusion in this session.

**2. [medium] gap_coverage — No error recovery entry for "task still runs after pausing"**
The assistant had to improvise the entire investigation.
- **Fix:** Add a new row to the Error Recovery table in SKILL.md.
- **Effort:** Quick — one table row addition
- **Recommend: Action** — Low effort, high value.

**3. [low] execution_quality — list command shows registry status without cross-checking launchd**
Would require the list command to shell out to `launchctl list` and reconcile.
- **Fix:** Add launchd state reconciliation to the list operation in the manage script.
- **Effort:** High-lift — requires new script logic and testing across platforms.
- **Recommend: Defer** — Nice-to-have but significant work. Not worth addressing now.

### Well Executed
- list presented clean, accurate registry data
- Assistant correctly went outside the skill to diagnose the real issue

---
I recommend actioning findings 1 and 2. Finding 3 is high-lift and better deferred.

Proceed with these? (y/adjust/none)

**Key principles:**

• Lead with your recommendation — don't make the user figure out what's worth doing
• Be honest about high-lift items — don't propose changes that would require major rewrites unless they're clearly worth it
• Group related findings that would be addressed together
• The user can adjust your recommendation (add/remove items) or accept it

Wait for user confirmation. If "none", show summary and stop.

Step 4: Resolve Source Locations

For each skill with selected findings, determine where to edit:

**Resolution order:**

1. **Project-level skill** — path contains `.claude/skills/` relative to a project → Candidate: edit in place (user owns it)

2. **User-level skill** — path is under `~/.claude/skills/` → Candidate: edit in place (user owns it)

3. **Installed plugin** — path is under `~/.claude/plugins/cache/` → Try to trace to source: a. Extract plugin name from the path b. Check if cwd is a marketplace project containing that plugin's source (look for `<plugin-name>/skills/<skill-name>/SKILL.md`) c. If not found, ask user: "Where is the source code for the `<plugin-name>` plugin? Provide a path, or type 'installed' to edit the installed copy." → If "installed": warn that changes will be overwritten on plugin update, proceed only if user confirms → If user provides a path: verify it exists and contains the skill

4. **Current project contains source** — cwd has `./<plugin-name>/skills/<skill-name>/SKILL.md` → Candidate: edit in place

**For each