Skill Validator — Anvil & Code

Audits SKILL.md files for structural correctness, triggering strength, and marketplace readiness. Produces a scored report with every issue categorized by severity and a specific fix for each.

How to Use

Paste a SKILL.md file (or its contents) and say "validate this" or "audit this skill." The validator will scan it, score it, and return a full report.

Validation Checklist

Run every check below. Report every finding — do not silently skip checks that pass.

YAML Frontmatter (Critical — failures here make the skill invisible)

Check	Pass	Fail
`name` field present	✅	❌ CRITICAL: Skill won't load
`name` in kebab-case	✅	⚠️ WARNING: May cause ID conflicts
`description` field present	✅	❌ CRITICAL: Skill will never trigger
`description` is 60–120 words	✅	⚠️ WARNING: Under 60 = under-triggers; Over 200 = diluted signal
`description` starts with an action verb	✅	⚠️ WARNING: Passive descriptions under-trigger by ~40%
`description` contains 3+ trigger phrases	✅	⚠️ WARNING: Skill won't fire on real user inputs
`description` names input AND output format	✅	⚠️ WARNING: Claude can't match skill to context
No placeholder text in YAML	✅	❌ CRITICAL: Placeholder text breaks triggering

Body Structure (Important — missing sections produce unreliable output)

Check	Pass	Fail
Has a clear purpose statement in first 3 lines	✅	⚠️ WARNING
Has an output format section	✅	⚠️ WARNING: Claude will invent a format
Has an anti-patterns section	✅	⚠️ INFO: Skill will occasionally produce bad output
Has at least 2 test cases	✅	⚠️ INFO: No way to verify skill works without tests
No placeholder text ([TODO], [INSERT], etc.)	✅	❌ CRITICAL: Incomplete skill
Under 500 lines total	✅	⚠️ WARNING: Large skills load slowly and may be partially ignored
No instructions that contradict each other	✅	❌ CRITICAL: Claude will behave unpredictably

Triggering Quality (Determines whether the skill actually fires)

Score the description on each dimension (1–3):

Specificity — Does it name specific inputs, outputs, and user phrases?

3: Names exact input format, output format, and 3+ trigger phrases
2: Names some inputs/outputs but trigger phrases are vague
1: Generic ("helps with X") — will not trigger reliably

Action orientation — Does it start with what Claude will DO?

3: Starts with verb: "Generates...", "Audits...", "Converts..."
2: Subject-first but active: "This skill generates..."
1: Passive or noun-first: "A skill for..." or "Can be used to..."

Coverage — Does it cover the real ways users will ask for this?

3: Includes formal request, casual request, and adjacent use case
2: Covers formal request only
1: Only matches one exact phrasing

Total triggering score: X/9

8–9: Strong — will trigger reliably
5–7: Moderate — will miss some valid use cases
Below 5: Weak — needs a rewrite before publishing

Anti-Pattern Detection

Flag any of the following if present:

❌ Unicode bullets (•, -, –) in YAML values — breaks YAML parsing
❌ HTML tags in the skill body — not rendered, creates noise
❌ Hardcoded file paths that don't exist in the skill's directory
❌ References to tools or MCPs not listed in a compatibility section
❌ Instructions that say "always" and also say "never" about the same thing
❌ Empty sections with only a heading
❌ Test cases with no expected output described

Output Format

Return the report in this exact structure:

## Skill Validation Report: [skill name]

**Overall Score: [X/10]**
[One sentence verdict: Ready to publish / Needs minor fixes / Needs major revision]

---

### Critical Issues (fix before using)
[List each CRITICAL finding with: what's wrong, where it is, exact fix]

### Warnings (fix before publishing)
[List each WARNING finding with: what's wrong, where it is, recommended fix]

### Info (optional improvements)
[List each INFO finding with: what it is and why it's worth fixing]

### Triggering Score: [X/9]
[Specificity: X/3 — one-line reason]
[Action orientation: X/3 — one-line reason]
[Coverage: X/3 — one-line reason]

### What's Working Well
[2–3 things the skill does right — be specific]

### Recommended Next Step
[Single most important thing to fix first]

Scoring Rubric (Overall 0–10)

Start at 10. Deduct:

3 points per CRITICAL issue
1 point per WARNING
0.5 points per INFO
Floor at 0

A score of 7+ is publishable. Below 7, the skill needs revision before listing.

Anti-Patterns

Never give a passing score to a skill with any CRITICAL issues
Never skip the triggering score — it's the most important single metric
Never suggest fixes without explaining why the current version is wrong
Never give vague feedback like "improve the description" — always give the specific rewrite

Test Cases

Test 1 — Strong skill Input: A well-formed SKILL.md with complete frontmatter, clear output format, 3+ test cases Expected: Score 8–10, few or no warnings, positive "What's Working" section

Test 2 — Weak description Input: A SKILL.md where the description is 15 words and starts with "A skill for..." Expected: Triggering score 2–3/9, CRITICAL issue flagged for description length and action verb

Test 3 — Placeholder text Input: A SKILL.md with [TODO: add examples here] in the body Expected: CRITICAL issue flagged, score deducted, exact location of placeholder cited

skill-validator