Skill Checker

A comprehensive skill validation and review tool based on Anthropic's official "Complete Guide to Building Skills for Claude." This skill runs a multi-dimensional audit on any skill folder or SKILL.md and produces an actionable scorecard with specific fix recommendations.

When to use

Run this skill whenever a user:

Uploads or references a skill they want reviewed
Asks "is this skill good?" or "check my skill"
Wants to validate before publishing/distributing
Is debugging triggering, execution, or quality issues
Wants to improve an existing skill

How it works

The review runs in three phases:

Structural validation — file naming, folder layout, YAML correctness
Content quality audit — description effectiveness, instruction clarity, progressive disclosure, patterns used
Scorecard & recommendations — graded rubric across all dimensions with prioritized fixes

Phase 1: Structural Validation

Read the skill folder and check every item below. Report pass/fail for each.

1.1 File & Folder Naming

[ ] Folder name uses kebab-case (e.g., my-cool-skill)
[ ] No spaces in folder name
[ ] No underscores in folder name
[ ] No capital letters in folder name
[ ] Folder name does NOT contain "claude" or "anthropic" (reserved)
[ ] Main file is exactly SKILL.md (case-sensitive — not skill.md, SKILL.MD, etc.)
[ ] No README.md inside the skill folder (all docs belong in SKILL.md or references/)

1.2 YAML Frontmatter

[ ] Frontmatter is delimited by --- on both the opening and closing lines
[ ] name field is present
[ ] name field uses kebab-case, no spaces, no capitals
[ ] name field matches the folder name
[ ] description field is present
[ ] description is under 1024 characters
[ ] No XML angle brackets (< or >) anywhere in frontmatter (security restriction)
[ ] No unclosed quotes in YAML values
[ ] Optional fields (if present) are valid:
- license: recognized license identifier (e.g., MIT, Apache-2.0)
- compatibility: 1–500 characters, describes environment requirements
- metadata: valid key-value pairs (suggested: author, version, mcp-server)

1.3 Folder Structure

[ ] Contains SKILL.md at root (required)
[ ] Optional directories follow convention: scripts/, references/, assets/
[ ] No unexpected top-level files that should be in subdirectories
[ ] If scripts/ exists, files are executable code (Python, Bash, etc.)
[ ] If references/ exists, files are documentation (.md, .txt, etc.)
[ ] If assets/ exists, files are templates, fonts, icons, etc.

Phase 2: Content Quality Audit

2.1 Description Field (Critical — this is the primary triggering mechanism)

The description must answer two questions: WHAT the skill does and WHEN to use it.

Check for:

[ ] Describes what the skill does (capability)
[ ] Describes when to use it (trigger conditions / user phrases)
[ ] Includes specific trigger phrases users would actually say
[ ] Mentions relevant file types if applicable
[ ] Is specific enough to avoid over-triggering on unrelated queries
[ ] Is broad enough to trigger on paraphrased requests (not just one exact phrase)
[ ] Includes negative triggers if there's risk of confusion with other skills (e.g., "Do NOT use for simple data exploration")

Grade the description:

Excellent: Specific, actionable, includes 3+ trigger phrases, mentions file types, clear scope
Good: Answers WHAT and WHEN, has trigger phrases, reasonable scope
Needs work: Vague ("Helps with projects"), missing triggers, too generic, or too technical without user-facing language
Failing: Missing entirely, one-word, or no trigger conditions

Red flags:

"Helps with X" without specifying what the user would say
Pure technical description with no user-facing trigger phrases
Overloaded description trying to cover too many unrelated things

2.2 Progressive Disclosure

Skills should use a three-level loading system to minimize token usage:

Level 1 — YAML frontmatter (~100 words): Always in context. Just enough for Claude to decide when to use it.
Level 2 — SKILL.md body (<500 lines ideal): Loaded when the skill triggers. Contains full instructions.
Level 3 — Linked files (references/, scripts/, assets/): Loaded only as needed.

Check for:

[ ] SKILL.md body is under 500 lines (ideal) or has clear hierarchy with pointers if longer
[ ] Detailed documentation is in references/, not inline in SKILL.md
[ ] SKILL.md references external files clearly with guidance on WHEN to read them
[ ] Large reference files (>300 lines) include a table of contents
[ ] Domain-specific variants are organized into separate reference files (e.g., references/aws.md, references/gcp.md) rather than all inlined

Grade:

Excellent: Clean separation across all three levels, SKILL.md is lean, references are well-organized
Good: Reasonable separation, maybe a bit long but manageable
Needs work: Everything crammed into SKILL.md, no use of references/
Failing: SKILL.md is 1000+ lines with no external files, or instructions are buried and hard to find

2.3 Instruction Quality

Check for clarity and actionability:

[ ] Instructions use imperative form ("Run X", "Check Y" — not "You might want to consider running X")
[ ] Critical instructions appear at the top, not buried deep
[ ] Steps are numbered and sequenced when order matters
[ ] Specific commands/scripts are given, not vague ("validate the data" → "Run python scripts/validate.py --input {filename}")
[ ] Error handling is included (what to do when things go wrong)
[ ] Examples are provided for common scenarios
[ ] Explains the why behind instructions, not just the what (this helps the model generalize)
[ ] Avoids excessive ALWAYS/NEVER/MUST in all-caps (reframe as reasoning when possible)
[ ] Output format is defined (template, structure, or example of expected result)

Check for composability:

[ ] Skill works well alongside other skills (doesn't assume it's the only capability)
[ ] No conflicts with common built-in Claude capabilities

Check for portability:

[ ] Works across Claude.ai, Claude Code, and API without modification
[ ] Any environment-specific dependencies are noted in compatibility field

2.4 Workflow Pattern Assessment

Identify which pattern(s) the skill uses and whether it applies them well:

Pattern 1: Sequential Workflow Orchestration

Explicit step ordering with dependencies between steps
Validation at each stage
Rollback instructions for failures

Pattern 2: Multi-MCP Coordination

Clear phase separation between different MCP services
Data passing between MCPs is documented
Validation before moving to next phase
Centralized error handling

Pattern 3: Iterative Refinement

Explicit quality criteria defined
Validation scripts or checks between iterations
Clear stopping criteria (when to stop iterating)

Pattern 4: Context-Aware Tool Selection

Clear decision criteria for choosing between tools
Fallback options documented
Transparency about choices (tells user why a path was chosen)

Pattern 5: Domain-Specific Intelligence

Domain expertise embedded in logic (not just tool access)
Compliance/governance checks before action
Comprehensive audit trail / documentation

Grade the pattern usage:

Excellent: Pattern is clearly identified and well-executed, with validation gates and error handling
Good: Pattern is present and functional, minor gaps
Needs work: Pattern is implicit or incomplete
N/A: Skill is simple enough that no formal pattern is needed

2.5 Use Case Definition

[ ] 2–3 concrete use cases are identifiable from the skill
[ ] Each use case has a clear trigger, steps, and expected result
[ ] Edge cases are addressed
[ ] Success criteria are defined (even if qualitative)

2.6 Category Classification

Classify the skill into one of the three standard categories:

Document & Asset Creation — consistent output (docs, presentations, code, designs)
Workflow Automation — multi-step processes with methodology
MCP Enhancement — workflow guidance on top of MCP tool access

Note: Skills can span categories. Identify the primary and any secondary categories.

Phase 3: Scorecard & Recommendations

Scoring Rubric

Score each dimension 1–5:

| Dimension | 1 (Failing) | 3 (Adequate) | 5 (Excellent) | |---|---|---|---| | Structure | Missing SKILL.md or broken YAML | Valid structure, minor issues | Perfect folder layout, all conventions followed | | Description | Missing or vague | Answers WHAT and WHEN | Specific triggers, file types, negative triggers, pushiness | | Progressive Disclosure | Everything in one giant file | Some separation | Clean 3-level hierarchy, lean SKILL.md | | Instruction Clarity | Vague, no examples | Clear steps, some examples | Imperative, examples, error handling, explains WHY | | Error Handling | None | Basic error messages | Comprehensive troubleshooting, rollback, common issues | | Composability | Conflicts with other skills | Works in isolation | Explicitly designed for multi-skill environments | | Testing Readiness | No testable outputs | Some verifiable outputs | Clear success criteria, assertions possible |

Output Format

Present the results as:

# Skill Review: [skill-name]

## Overall Score: X/35 ([rating])

### Structural Validation
✅ / ❌ [each check with pass/fail]

### Content Quality
| Dimension | Score | Notes |
|---|---|---|
| Description | X/5 | [specific feedback] |
| Progressive Disclosure | X/5 | [specific feedback] |
| Instruction Clarity | X/5 | [specific feedback] |
| Error Handling | X/5 | [specific feedback] |
| Composability | X/5 | [specific feedback] |
| Testing Readiness | X/5 | [specific feedback] |

### Pattern Analysis
Primary pattern: [pattern name]
Pattern execution: [grade]

### Category
Primary: [category]
Secondary: [category, if applicable]

### Top 3 Fixes (Prioritized)
1. **[Priority: High/Medium/Low]** — [specific, actionable fix]
2. **[Priority: High/Medium/Low]** — [specific, actionable fix]
3. **[Priority: High/Medium/Low]** — [specific, actionable fix]

### Description Rewrite (if score < 4)
Suggested improved description:
[rewritten description]

Rating Scale

30–35: Production-ready. Minor polish only.
22–29: Good foundation. Address the top fixes and it's ready.
15–21: Needs significant work. Focus on structural and description issues first.
Below 15: Fundamental rework needed. Start with the Fundamentals chapter of the guide.

Quick-Check Mode

If the user just wants a fast pass (e.g., "quick check my skill"), skip the full audit and run only:

YAML frontmatter validation (all required fields, no forbidden content)
Description quality check (WHAT + WHEN + trigger phrases)
Top 3 issues with fixes

This should take under 2 minutes and give the user enough to act on immediately.

Validation Script

If the skill folder is available on the filesystem, run the automated structural checks:

python scripts/validate_skill.py <path-to-skill-folder>

This script checks file naming, YAML parsing, folder structure, description length, and forbidden content. It outputs a JSON report that feeds into the scorecard.

Troubleshooting Common Issues (Reference for Reviewer)

Skill won't upload

File not named exactly SKILL.md
YAML missing --- delimiters
Unclosed quotes in YAML
Name has spaces or capitals

Skill doesn't trigger

Description too generic ("Helps with projects")
Missing trigger phrases
Missing relevant file type mentions
Test: Ask Claude "When would you use the [skill name] skill?" — if Claude can't answer clearly, the description needs work

Skill triggers too often

Add negative triggers ("Do NOT use for...")
Be more specific about scope
Clarify what adjacent skills handle instead

Instructions not followed

Instructions too verbose (keep SKILL.md lean)
Critical instructions buried deep (move them up)
Ambiguous language ("process appropriately" → give explicit steps)
Missing explanation of WHY (model can't generalize without reasoning)
Consider bundling validation scripts for critical checks (code is deterministic; language isn't)

Performance/context issues

SKILL.md over 500 lines without progressive disclosure
Too many skills enabled simultaneously (>20–50)
All content loaded inline instead of referenced