Improving Skills
Improve existing agent skills through gathering user feedback and technical analysis.
Workflow
Step 1: Identify Target Skill
Ask user for the skill path if not provided (e.g., .claude/skills/skill-name/).
Read SKILL.md and understand current structure.
Step 2: Gather Feedback (Required)
Ask the essential question:
"What problems or improvements do you want for this skill?"
Based on the response, ask follow-up questions as needed:
| If user mentions... | Follow-up question |
|---|---|
| Vague dissatisfaction | "Can you give a specific example of when it didn't work well?" |
| Trigger issues | "When does it fail to trigger, or trigger unexpectedly?" |
| Missing features | "What should the output look like when this feature works?" |
| Too much/little output | "What level of detail do you prefer?" |
| Unclear scope | "What tasks should this skill handle vs. not handle?" |
Keep follow-ups minimal. One or two is usually enough.
Step 3: Technical Analysis
Check against best practices (reference reviewing-skills criteria):
- Naming: Gerund form, descriptive
- Description: Third person, includes what + when
- Size: SKILL.md < 500 lines
- Progressive disclosure: Details in references
- Single responsibility: One clear purpose
- Tests: tests/scenarios.md exists (required for
/evaluating-skills-with-models)
Step 4: Present Improvement Plan
Organize improvements into:
User-requested improvements:
- Based on feedback
- Prioritize what user explicitly mentioned
Technical improvements:
- Issues found in analysis
- Only include if impactful
Format:
## Improvement Plan
### User-requested
1. [Issue from feedback] → [Proposed fix]
### Technical
1. [Issue from analysis] → [Proposed fix]
Proceed with these changes?Step 5: Implement
Execute the improvements:
- Edit SKILL.md
- Update/create reference files if needed
- Adjust scripts/assets if applicable
Show diff or summary of changes made.
Step 6: Verify
Quick check:
- Changes address user's stated problems
- No new issues introduced
- Skill still follows best practices
Key Difference from reviewing-skills
| reviewing-skills | improving-skills |
|---|---|
| Technical analysis only | User feedback + technical analysis |
| Provides feedback | Implements changes |
| Read-only | Read-write |