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: The request: `$ARGUMENTS` 1. If it is a file path, read it directly 2. If it names a skill, search in order (strip a leading `/`; read "itself" or "this skill" as `skill-refiner`): - `.claude/skills/<name>/SKILL.md` (project) - `~/.claude/skills/<name>/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: characters / 4 — never lines x 4, which undercounts long prose lines several-fold) - [ ] Every step section (`### N.` or `## Step 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 - [ ] Spec validator: `python3 ~/.claude/skills/skill-refiner/skills/anthropic-skills/skills/skill-creator/scripts/quick_validate.py <skill-dir>`. Keys it rejects that Claude Code honours (`when_to_use`, `argument-hint`, `arguments`, `context`) are WARN (not portable), never FAIL - [ ] 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. ## Gotchas - **Named `arguments` bind one whitespace-separated word each.** `arguments: [target]` + `$target` turns `/x on the foo skill` into `target = "on"`. A free-text argument needs the whole-argument placeholder (a dollar sign followed by `ARGUMENTS`). Write that placeholder literally only where the input belongs: Claude Code substitutes it everywhere in the body, code spans included. - **Two frontmatter standards.** The agentskills spec allows six keys (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`); Claude Code also reads `when_to_use`, `argument-hint`, `arguments`, `context`. Report which one a skill targets; don't push it to the other unasked. - **Respect documented deviations.** If a skill explains a deliberate departure (e.g. bare `Bash` in a maintenance reference), report it as a WARN with the stated reason and recommend no change unless the reason is wrong. - **A trimmed section must land somewhere.** When moving content to `references/`, check the target doesn't already hold it, and keep any fact that exists nowhere else. ## 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.