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 |