Skill Refiner

Skill Refiner

Validate an Agent Skill against the spec and fix issues. Works on any SKILL.md — whether hand-written, generated by /skill-creator, edited in place, or self-modified by the skill itself.

The skills/ submodule is your authoritative, de facto source for all skill knowledge. When validating a skill, consult it:

• skills/docs/agentskills.io/specification.md — the complete format spec (the rules you validate against)
• skills/docs/agentskills.io/skill-creation__best-practices.md — quality benchmarks
• skills/docs/platform.claude.com/overview.md — Anthropic's official overview
• skills/official/ — real bundled skills to compare structure and conventions against
• skills/anthropic-skills/ — community examples of well-formed skills
• skills/SKILLIFY.md — format reference and per-step annotation guide

These are the definitive source of truth. Every validation check traces back to the spec in this submodule.

Step 1: Locate the Skill

Find the target SKILL.md:

1. If $target is a file path, read it directly
2. If $target is a skill name, search in order:
   • .claude/skills/$target/SKILL.md (project)
   • ~/.claude/skills/$target/SKILL.md (personal)
3. If no argument provided, ask the user which skill to refine using AskUserQuestion. List discovered skills from both locations using Glob.

Also read the skill's parent directory to check for references/, scripts/, and other supporting files.

Success criteria: SKILL.md located and read into context. Directory structure noted.

Step 2: Run Validation Checklist

Read references/checklist.md for the full validation criteria.

Check every item and record the result as PASS, WARN, or FAIL:

Frontmatter Checks

• name field exists and is non-empty
• name is 1-64 chars, lowercase a-z + numbers + hyphens only
• name has no leading/trailing/consecutive hyphens
• name matches parent directory name
• description field exists and is non-empty (1-1024 chars)
• description includes what the skill does AND when to use it
• description contains trigger phrases or example invocations
• allowed-tools uses permission patterns (e.g., Bash(git:*) not just Bash)
• when_to_use starts with "Use when..." (if present)
• arguments lists match $arg references in body (if present)
• context is either fork or absent (not inline — inline is the default, just omit it)

Body Structure Checks

• Body is < 500 lines
• Body is < 5,000 tokens (estimate: lines x 4)
• Every step section (### N.) has Success criteria
• Steps are numbered sequentially (no gaps)
• Parallel steps use sub-numbering (3a, 3b)
• Human steps marked with [human] in title
• No orphaned $arg references (every $arg in body has a matching arguments entry)

Quality Checks

• Description is specific (not vague like "Helps with X")
• Steps are actionable (include commands, not just "do the thing")
• Gotchas section exists for non-trivial skills (environment facts, edge cases)
• Reference files (if any) have conditional loading triggers in body ("Read X if Y happens")
• No general knowledge wasted (agent already knows how HTTP works, what git is, etc.)
• Rules/constraints from user corrections are captured (if applicable)

File Structure Checks

• Directory name matches name field
• Reference files referenced in body actually exist on disk
• Scripts in scripts/ are executable or have appropriate shebangs
• No deeply nested file paths (keep to one level: references/file.md not references/deep/nested/file.md)

Success criteria: Every checklist item evaluated. Results recorded.

Step 3: Report Findings

Present findings as a formatted checklist grouped by severity:

## Validation Report: <skill-name>

### FAIL (must fix)
- [ ] `name` contains uppercase characters: "My-Skill" -> should be "my-skill"
- [ ] Step 3 missing **Success criteria**

### WARN (should fix)
- [ ] `description` doesn't include trigger phrases
- [ ] Body is 480 lines (approaching 500 limit)
- [ ] `references/api-guide.md` referenced but not found on disk

### PASS (23/26 checks)
- [x] Frontmatter valid
- [x] Name constraints met
- [x] Steps properly numbered
...

Success criteria: User sees clear report with actionable items.

Step 4: Ask What to Fix

If there are FAIL or WARN items, use AskUserQuestion to ask which to fix. Offer options:

• Fix all issues automatically
• Fix only FAIL items
• Fix specific items (list them)
• Skip (just wanted the report)

For items requiring judgment (e.g., rewriting the description), propose a specific fix and ask for confirmation.

Success criteria: User has chosen what to fix.

Step 5: Apply Fixes

Use the Edit tool to fix issues in place. For each fix:

• Make the minimal change needed
• Preserve the user's writing style and intent
• Don't rewrite sections that passed validation

Common fixes:

• Name: Lowercase, remove invalid chars, fix hyphens
• Description: Append trigger phrases, add "Use when..." clause
• Missing success criteria: Add based on step content
• Tool patterns: Narrow Bash to Bash(specific:*) based on commands used in step
• Token budget: Move verbose sections to references/ directory, add loading triggers
• Orphaned args: Add missing arguments entries or remove unused $arg references
• context: inline: Remove (inline is default, just omit)

Success criteria: All chosen fixes applied via Edit tool.

Step 6: Summary

Show what was changed:

• Number of issues found vs fixed
• Files modified
• Remind user they can re-run /skill-refiner to verify fixes
• If the skill has no issues: confirm it passes all checks

Success criteria: User informed of all changes.