name: skill-tuner description: Analyzes and improves Agent Skills (SKILL.md files) using a 10-dimension evaluation rubric. Generates improved versions with before/after comparison. Use when asked to improve, review, refine, or tune a skill, or when the user mentions skill quality, skill evaluation, or SKILL.md optimization.

Skill Tuner

Evaluate and improve Agent Skills against production-quality standards.

When to use

• User asks to improve, refine, or review a SKILL.md file
• User shares a skill and wants feedback or optimization
• User says "tune my skill", "improve this skill", or "review my SKILL.md"
• User points to a GitHub repo and asks to improve a skill from it
• Building a new skill and want to validate quality before shipping

Workflow (5 steps)

Follow this exact workflow. Do not skip steps.

Skill Tuning Progress:
- [ ] Step 1: ANALYZE — Read and score the skill
- [ ] Step 2: DIAGNOSE — Identify top improvement areas
- [ ] Step 3: IMPROVE — Generate the improved version
- [ ] Step 4: COMPARE — Show before/after with explanations
- [ ] Step 5: DECIDE — User applies or rejects changes

Step 1: ANALYZE

Read the target skill completely. Score it against the evaluation rubric (10 dimensions, 1-5 each).

Output this table:

## Evaluation: [Skill Name]

| # | Dimension | Score | Key Issue |
|---|-----------|-------|-----------|
| 1 | Metadata Quality | /5 | |
| 2 | Conciseness | /5 | |
| 3 | Structure & Organization | /5 | |
| 4 | Progressive Disclosure | /5 | |
| 5 | Degrees of Freedom | /5 | |
| 6 | Workflow Clarity | /5 | |
| 7 | Feedback Loops | /5 | |
| 8 | Examples & Templates | /5 | |
| 9 | Anti-Pattern Avoidance | /5 | |
| 10 | Cross-Platform Compatibility | /5 | |
| **Total** | | **/50** | |

Scoring rules:

• Read the full rubric in references/evaluation-rubric.md before scoring
• Be honest — do not inflate scores. A 3 means "adequate, could be better"
• Every score below 4 must have a specific, actionable issue noted

Step 2: DIAGNOSE

Identify the 3-5 highest-impact improvements. Prioritize by:

1. Impact: How much would fixing this improve the skill's real-world effectiveness?
2. Effort: How much rewriting is needed? (prefer high-impact, low-effort first)
3. Dependencies: Does fixing X automatically fix Y?

Output format:

### Priority Improvements

1. **[Dimension]**: [Specific problem] → [Specific fix]
   - Impact: High/Medium | Effort: Low/Medium/High
2. ...
3. ...

Check against common anti-patterns: Read references/anti-patterns.md and flag any matches.

Reference best practices: Consult references/best-practices-digest.md for improvement patterns.

Step 3: IMPROVE

Generate the complete improved SKILL.md. Rules:

1. Fix all diagnosed issues from Step 2
2. Preserve the skill's intent — do not change what the skill does, only how it instructs
3. Follow the spec: valid YAML frontmatter, name lowercase+hyphens (<=64 chars), description third-person (<=1024 chars)
4. Keep SKILL.md under 500 lines
5. Apply progressive disclosure: if the improved version exceeds 300 lines, suggest splitting content into reference files
6. Match degrees of freedom to the domain: fragile operations get exact commands; creative tasks get general guidance
7. Add missing sections: "When to use", examples, workflows as needed
8. Do not invent new functionality — only improve how existing functionality is documented

Quality gate: The improved version must score 40+ on the rubric. If it doesn't, iterate.

Step 4: COMPARE

Present the before/after comparison so the user can evaluate the changes.

Format:

## Before vs After

### Scores

| Dimension | Before | After | Change |
|-----------|--------|-------|--------|
| Metadata Quality | X | Y | +Z |
| Conciseness | X | Y | +Z |
| ... | | | |
| **Total** | **X/50** | **Y/50** | **+Z** |

### Key Changes

1. **[Change category]**: [What changed and why]
   - Before: `[snippet]`
   - After: `[snippet]`

2. **[Change category]**: [What changed and why]
   - Before: `[snippet]`
   - After: `[snippet]`

3. ...

Show concrete snippets — not abstract descriptions. The user needs to see exactly what changed.

For file-based comparison, you can use: python scripts/diff_skills.py before.md after.md

Step 5: DECIDE

Ask the user:

Here's the improved skill. The score improved from X/50 to Y/50.

Key changes: [1-2 sentence summary]

Options:

1. Apply all changes — replace the current skill with the improved version
2. Apply selectively — tell me which changes to keep and which to revert
3. Reject — keep the original unchanged

What would you like to do?

If the user chooses "Apply selectively":

• List each change as a numbered item
• Ask which numbers to keep
• Generate a version with only the selected changes

If the user chooses "Apply all":

• Write the improved SKILL.md to the skill's directory
• If reference files were suggested, create them too
• Confirm the changes were applied

Tips for best results

• Provide the full skill directory (not just SKILL.md) — knowing about reference files improves the analysis
• Mention the skill's primary platform (Claude Code, API, claude.ai) — affects cross-platform scoring
• Share any known issues — "users report it doesn't activate for X" helps focus the diagnosis
• For new skills: Run this workflow as a quality gate before shipping

See also

• Evaluation Rubric — full scoring criteria for all 10 dimensions
• Best Practices Digest — condensed guidelines from Anthropic and agentskills.io
• Anti-Patterns — common problems and how to fix them
• Before/After Examples — three concrete improvement walkthroughs