| name | improving-skills |
| description | Improve existing agent skills based on user feedback and best practices. Use when the user wants to fix, enhance, or refactor an existing skill. Gathers user feedback first, then applies technical analysis and implements improvements. |
| license | Apache-2.0 |
| metadata | [object Object] |
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 |