# Skill Refiner > Validate and fix an Agent Skill against the spec. Checks frontmatter, naming, description quality, step structure, success criteria, tool patterns, and token budget. Use when a skill needs cleanup, after editing a SKILL.md, when a skill isn't triggering correctly, or to keep a self-modifying skill in check. - Skill: `coffeegrind123/skill-refiner` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add coffeegrind123/skill-refiner` - Raw SKILL.md: https://api.skillmd.com/api/skills/coffeegrind123/skill-refiner/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: coffeegrind123 (https://skillmd.com/u/coffeegrind123) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/coffeegrind123/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: ### 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.