FarzamMohammadi Improve Skill
Reflect on how a skill performed, identify gaps, and iterate on improvements.
Step 1: Locate the Skill
Find the skill file based on the provided name:
ls ai/claude-code/skills/[skill-name]/skill.md
Read the skill's current implementation.
Step 2: Review Recent Usage
Examine the conversation for how the skill was just used. Ask yourself:
Clarity & Instructions
- Were any instructions ambiguous?
- Did I have to guess or interpret what was meant?
- Were there missing steps I filled in myself?
Edge Cases
- Did I encounter situations the skill didn't handle?
- What did I improvise that should be documented?
Output Quality
- Did the output format work well?
- Was anything awkward to produce?
Missing Features
- What would have made this easier?
- What did the user have to clarify that should be in the skill?
Friction Points
- Where did I slow down or struggle?
- What felt repetitive or unnecessary?
Step 3: Generate Reflection
Output findings in this format:
## Skill Reflection: [skill-name]
### What Worked Well
- [strength]
### Gaps Identified
| Gap | Suggested Fix |
|-----|---------------|
| [issue] | [concrete change] |
### Suggested Improvements
1. [specific edit to skill.md with line reference]
2. [specific edit]
Use AskUserQuestion to validate findings or get more context if unsure.
Step 4: Apply Improvements
Ask user: "Apply these improvements? [Y/n/select]"
- Y: Apply all suggested changes
- n: Skip, just provide the reflection
- select: Let user pick which improvements to apply
When applying, make precise edits to the skill file. Verify each change doesn't break existing functionality.
Guidelines
- Be specific—vague feedback like "make it clearer" isn't actionable
- Reference exact lines or sections when suggesting changes
- Small, incremental improvements beat large rewrites
- If nothing needs improvement, say so honestly