SkillCheck
Selective Reading Rule
Start with:
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
Then load only the inherited docs, scripts, assets, or examples that match the user's actual task.
Overview
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.
When to Use This Skill
- Use when user says "check skill", "skillcheck", or "validate SKILL.md"
- Use when reviewing a skill before publishing to a marketplace
- Use when debugging why a skill doesn't trigger correctly
- Use when onboarding a team to skill authoring standards
- Do NOT use for anti-slop detection, security scanning, or token analysis; use SkillCheck Pro for those
How It Works
Step 1: Parse
Read the target SKILL.md file and extract YAML frontmatter.
Step 2: Validate
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) |
Step 3: Score
Calculate overall score (0-100). Penalties: critical = -20, warning = -5, suggestion = -1.
Step 4: Report
Return structured results: score, grade (Excellent/Good/Needs Work/Poor), issue list with check IDs, line numbers, messages, and fix suggestions.
Examples
Example 1: Validating a skill
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
Example 2: Clean skill passes all checks
User: skillcheck ~/.claude/skills/processing-pdfs/SKILL.md
Score: 100/100 (Excellent)
All 31 checks passed. No issues found.
Limitations
- Read-only: does not modify any files
- Free tier covers structural, semantic, and naming checks only
- Anti-slop, security, WCAG, token, enterprise, and workflow checks require SkillCheck Pro
- Semantic checks (contradiction detection, wisdom/platitude) are heuristic with ~5% false positive rate
- Does not validate referenced files or scripts; only checks SKILL.md content
- Single-file validation; does not cross-check against other skills in the same directory
Best Practices
- Run SkillCheck before submitting skills to any marketplace
- Fix all critical and warning issues; suggestions are optional
- Use the check ID (e.g.,
1.2-desc-when) to find the exact rule in the skill body
- Re-run after fixes to confirm the score improved
Common Pitfalls
Problem: 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").
1---2name: skill-check3description: ALWAYS use this when the request matches Skill Check: Validate Claude Code skills against the agentskills specification.4---56# SkillCheck78## Selective Reading Rule910Start with:1112- `references/senior-master-standard.md`13- `references/usage-routing.md`14- `references/quality-checklist.md`1516Then load only the inherited docs, scripts, assets, or examples that match the user's actual task.1718## Overview1920Validate SKILL.md files against the [agentskills specification](https://agentskills.io) and Anthropic best practices. Catches structural errors, semantic contradictions, naming anti-patterns, and quality gaps in a single read-only pass.2122## When to Use This Skill2324- Use when user says "check skill", "skillcheck", or "validate SKILL.md"25- Use when reviewing a skill before publishing to a marketplace26- Use when debugging why a skill doesn't trigger correctly27- Use when onboarding a team to skill authoring standards28- Do NOT use for anti-slop detection, security scanning, or token analysis; use [SkillCheck Pro](https://getskillcheck.com) for those2930## How It Works3132### Step 1: Parse3334Read the target SKILL.md file and extract YAML frontmatter.3536### Step 2: Validate3738Apply all Free tier checks in order:3940| Category | Checks | What it catches |41|----------|--------|----------------|42| Structure (1.x) | Name format, description WHAT+WHEN, allowed-tools, categories, XML injection | Malformed frontmatter, missing fields |43| Body (2.x) | Line count, hardcoded paths, stale dates, empty sections, deprecated syntax, MCP tool qualification | Content quality issues |44| Naming (3.x) | Vague terms, single-word names, gerund suggestions | Poor discoverability |45| Semantic (4.x) | Contradictions, ambiguous terms, missing output format, wisdom/platitudes, misplaced triggers | Logical inconsistencies |46| Quality (8.x) | Examples, error handling, triggers, output format, prerequisites, negative triggers | Strengths (positive patterns) |4748### Step 3: Score4950Calculate overall score (0-100). Penalties: critical = -20, warning = -5, suggestion = -1.5152### Step 4: Report5354Return structured results: score, grade (Excellent/Good/Needs Work/Poor), issue list with check IDs, line numbers, messages, and fix suggestions.5556## Examples5758### Example 1: Validating a skill5960```61User: check my skill at ~/.claude/skills/weekly-report/SKILL.md6263SkillCheck output:64## weekly-report Check Results [FREE]6566Score: 85/100 (Good)6768### Warnings (2)69 - 1.2-desc-when (line 3): Description missing WHEN clause70 - 4.5-desc-no-triggers (line 3): Description lacks triggering conditions7172### Suggestions (1)73 - 3.4-gerund-naming (line 2): Skill name could use gerund form7475### Passed Checks: 2876```7778### Example 2: Clean skill passes all checks7980```81User: skillcheck ~/.claude/skills/processing-pdfs/SKILL.md8283Score: 100/100 (Excellent)84All 31 checks passed. No issues found.85```8687## Limitations8889- Read-only: does not modify any files90- Free tier covers structural, semantic, and naming checks only91- Anti-slop, security, WCAG, token, enterprise, and workflow checks require [SkillCheck Pro](https://getskillcheck.com)92- Semantic checks (contradiction detection, wisdom/platitude) are heuristic with ~5% false positive rate93- Does not validate referenced files or scripts; only checks SKILL.md content94- Single-file validation; does not cross-check against other skills in the same directory9596## Best Practices9798- Run SkillCheck before submitting skills to any marketplace99- Fix all critical and warning issues; suggestions are optional100- Use the check ID (e.g., `1.2-desc-when`) to find the exact rule in the skill body101- Re-run after fixes to confirm the score improved102103## Common Pitfalls104105- **Problem:** Score seems low due to many suggestions106 **Solution:** Suggestions cap at -15 points total. Focus on warnings and criticals first.107108- **Problem:** False positive on ambiguous terms inside code blocks109 **Solution:** SkillCheck skips code blocks and inline code. If you still see false positives, wrap the term in backticks.110111- **Problem:** Wisdom/platitude check flags legitimate instructions112 **Solution:** Rephrase generic advice ("Remember that testing is important") as concrete directives ("Run tests before committing").
anhvu1107