MilesChou Polish
Step 1: Identify the Target Skill
Scan the conversation history for traces of skill execution. Look for:
<command-name>/skill-name</command-name>tags — these mark skill invocationsSkilltool calls — these show which skills were loaded
If multiple skills were executed, rank them by "how many corrections occurred during execution." Present the results to the user via AskUserQuestion:
- List each detected skill with a one-line summary of observed issues
- Ask the user to confirm which skill to retro, or specify another
If the user already passed an argument (e.g. /polish resolve-issue), use it directly, but still summarize observed issues and ask for confirmation.
Once the target skill is confirmed, locate its SKILL.md by running:
${CLAUDE_SKILL_DIR}/scripts/find-skill.sh <skill-name>
The script searches ~/.claude/skills and the current working directory recursively.
Use the results to confirm the target path via AskUserQuestion:
- One result — present the path and ask for confirmation
- Multiple results — list each as a numbered option and ask the user to pick one
- No results — ask the user to provide the absolute path to the SKILL.md directly
Once the path is confirmed, immediately read the file with the Read tool so its current content is available for Steps 3 and 4.
Step 2: Catalog Correction Events
A skill is written with assumptions about how execution will unfold. Correction events are the gaps between those assumptions and reality — signals that the skill's instructions can be improved. The goal is to feed these signals back into SKILL.md so its instructions guide toward the ideal execution path.
Event type definitions and identification methods are in references/event-types.md.
Extract Correction Events
Walk through the conversation chronologically and extract every correction event (types defined in references/event-types.md). For each event, record:
| Field | Description |
|---|---|
| Type | user-interrupt, self-correct, unnecessary-pause, script-candidate, or preload-candidate |
| Location | The step/phase the skill was executing at the time |
| What happened | The action the agent took, or was about to take |
| What should have happened | The correct action (from user feedback or the successful recovery) |
| Root cause in skill | Which part of SKILL.md led to the wrong behavior |
For script-candidate and preload-candidate events, additionally record:
- Which Bash commands to consolidate or preload
- What the script/preload does (input → output)
- Where in the skill it would be called or inlined
Present the Event List
Present the list to the user as a numbered list. Each item should show:
- Correction type (emoji: 🛑 user-interrupt, 🔄 self-correct, ⏸️ unnecessary-pause, 📦 script-candidate, ⚡ preload-candidate)
- A short description of what happened
- The inferred root cause in the skill (or consolidation rationale for script/preload candidates)
Use AskUserQuestion to confirm the list is correct before proceeding.
Step 3: Design Fixes
For each event in the confirmed list, propose a concrete change to SKILL.md. Fix patterns for each event type are in references/event-types.md.
Structural Improvements
Beyond individual fixes, look for overall patterns:
- Multiple corrections in the same phase → the phase's instructions may need restructuring
- Corrections imply a missing step → add that step
- Corrections stem from outdated information → update the stale content
- Skill instructions conflict with CLAUDE.md or project conventions → align to project standards
Present each proposed fix to the user, including:
- The corresponding correction event (referencing its list number)
- The specific SKILL.md section to change
- A before/after preview of the change
If any fix implies splitting the skill or creating a new skill, discuss with the user before proceeding.
Step 4: Apply Fixes
After the user approves the fixes (or a subset of them):
- Apply each approved fix one by one using the Edit tool
- If metadata changes are needed (description, allowed-tools), update those too
- Show a summary of all changes made
Do not create new files or rewrite the entire SKILL.md — use targeted edits to preserve the existing structure, changing only what needs to change.
Step 5: Verify
After applying fixes, do a quick sanity check:
- Re-read the modified SKILL.md
- Confirm the changes are consistent with the rest of the skill's instructions
- Check that no instructions contradict each other
- Verify the YAML frontmatter is still valid
Present a final summary to the user:
- How many corrections were addressed
- Which sections were modified
- Any issues that couldn't be resolved through skill changes alone (e.g. tool limitations, external API behavior)