SkillCheck
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").
Source: sickn33/agentic-awesome-skills → skills/skill-check/SKILL.md
Also appears in: sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills-claude/skills/skill-check/SKILL.md
1---2name: skill-check3description: Validate Claude Code skills against the agentskills specification. Catches structural, semantic, and naming issues before users do.4---5
6
7# SkillCheck
8
9## Overview
10
11Validate 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.
12
13## When to Use This Skill
14
15- Use when user says "check skill", "skillcheck", or "validate SKILL.md"
16- Use when reviewing a skill before publishing to a marketplace
17- Use when debugging why a skill doesn't trigger correctly
18- Use when onboarding a team to skill authoring standards
19- Do NOT use for anti-slop detection, security scanning, or token analysis; use [SkillCheck Pro](https://getskillcheck.com) for those
20
21## How It Works
22
23### Step 1: Parse
24
25Read the target SKILL.md file and extract YAML frontmatter.
26
27### Step 2: Validate
28
29Apply all Free tier checks in order:
30
31| Category | Checks | What it catches |
32|----------|--------|----------------|
33| Structure (1.x) | Name format, description WHAT+WHEN, allowed-tools, categories, XML injection | Malformed frontmatter, missing fields |
34| Body (2.x) | Line count, hardcoded paths, stale dates, empty sections, deprecated syntax, MCP tool qualification | Content quality issues |
35| Naming (3.x) | Vague terms, single-word names, gerund suggestions | Poor discoverability |
36| Semantic (4.x) | Contradictions, ambiguous terms, missing output format, wisdom/platitudes, misplaced triggers | Logical inconsistencies |
37| Quality (8.x) | Examples, error handling, triggers, output format, prerequisites, negative triggers | Strengths (positive patterns) |
38
39### Step 3: Score
40
41Calculate overall score (0-100). Penalties: critical = -20, warning = -5, suggestion = -1.
42
43### Step 4: Report
44
45Return structured results: score, grade (Excellent/Good/Needs Work/Poor), issue list with check IDs, line numbers, messages, and fix suggestions.
46
47## Examples
48
49### Example 1: Validating a skill
50
51```
52User: check my skill at ~/.claude/skills/weekly-report/SKILL.md
53
54SkillCheck output:
55## weekly-report Check Results [FREE]
56
57Score: 85/100 (Good)
58
59### Warnings (2)
60 - 1.2-desc-when (line 3): Description missing WHEN clause
61 - 4.5-desc-no-triggers (line 3): Description lacks triggering conditions
62
63### Suggestions (1)
64 - 3.4-gerund-naming (line 2): Skill name could use gerund form
65
66### Passed Checks: 28
67```
68
69### Example 2: Clean skill passes all checks
70
71```
72User: skillcheck ~/.claude/skills/processing-pdfs/SKILL.md
73
74Score: 100/100 (Excellent)
75All 31 checks passed. No issues found.
76```
77
78## Limitations
79
80- Read-only: does not modify any files
81- Free tier covers structural, semantic, and naming checks only
82- Anti-slop, security, WCAG, token, enterprise, and workflow checks require [SkillCheck Pro](https://getskillcheck.com)
83- Semantic checks (contradiction detection, wisdom/platitude) are heuristic with ~5% false positive rate
84- Does not validate referenced files or scripts; only checks SKILL.md content
85- Single-file validation; does not cross-check against other skills in the same directory
86
87## Best Practices
88
89- Run SkillCheck before submitting skills to any marketplace
90- Fix all critical and warning issues; suggestions are optional
91- Use the check ID (e.g., `1.2-desc-when`) to find the exact rule in the skill body
92- Re-run after fixes to confirm the score improved
93
94## Common Pitfalls
95
96- **Problem:** Score seems low due to many suggestions
97 **Solution:** Suggestions cap at -15 points total. Focus on warnings and criticals first.
98
99- **Problem:** False positive on ambiguous terms inside code blocks
100 **Solution:** SkillCheck skips code blocks and inline code. If you still see false positives, wrap the term in backticks.
101
102- **Problem:** Wisdom/platitude check flags legitimate instructions
103 **Solution:** Rephrase generic advice ("Remember that testing is important") as concrete directives ("Run tests before committing").
104
105---
106
107**Source:** [`sickn33/agentic-awesome-skills`](https://github.com/sickn33/agentic-awesome-skills) → `skills/skill-check/SKILL.md`
108
109**Also appears in:** `sickn33/agentic-awesome-skills/plugins/agentic-awesome-skills-claude/skills/skill-check/SKILL.md`
thedixitjain