Validate Claude Code skills against the agentskills specification. Catches structural, semantic, and naming issues before users do.
Validate SKILL.md files against the agentskills specification and Anthropic best practices. Catches structural errors, semantic contradictions, naming anti-patterns, and quality gaps in a single read-only pass.
Read the target SKILL.md file and extract YAML frontmatter.
Apply all Free tier checks in order:
| Category | Checks | What it catches |
|---|---|---|
| Structure (1.x) | Name format, description WHAT+WHEN, allowed-tools, categories, XML injection | Malformed frontmatter, missing fields |
| Body (2.x) | Line count, hardcoded paths, stale dates, empty sections, deprecated syntax, MCP tool qualification | Content quality issues |
| Naming (3.x) | Vague terms, single-word names, gerund suggestions | Poor discoverability |
| Semantic (4.x) | Contradictions, ambiguous terms, missing output format, wisdom/platitudes, misplaced triggers | Logical inconsistencies |
| Quality (8.x) | Examples, error handling, triggers, output format, prerequisites, negative triggers | Strengths (positive patterns) |
Calculate overall score (0-100). Penalties: critical = -20, warning = -5, suggestion = -1.
Return structured results: score, grade (Excellent/Good/Needs Work/Poor), issue list with check IDs, line numbers, messages, and fix suggestions.
User: check my skill at ~/.claude/skills/weekly-report/SKILL.md
SkillCheck output:
## weekly-report Check Results [FREE]
Score: 85/100 (Good)
### Warnings (2)
- 1.2-desc-when (line 3): Description missing WHEN clause
- 4.5-desc-no-triggers (line 3): Description lacks triggering conditions
### Suggestions (1)
- 3.4-gerund-naming (line 2): Skill name could use gerund form
### Passed Checks: 28
User: skillcheck ~/.claude/skills/processing-pdfs/SKILL.md
Score: 100/100 (Excellent)
All 31 checks passed. No issues found.
1.2-desc-when) to find the exact rule in the skill bodyProblem: Score seems low due to many suggestions Solution: Suggestions cap at -15 points total. Focus on warnings and criticals first.
Problem: False positive on ambiguous terms inside code blocks Solution: SkillCheck skips code blocks and inline code. If you still see false positives, wrap the term in backticks.
Problem: Wisdom/platitude check flags legitimate instructions Solution: Rephrase generic advice ("Remember that testing is important") as concrete directives ("Run tests before committing").