Skill Linter

Validates skills against the best practices guide.

Quick Start

Run the linter on a skill directory:

python /path/to/skill-linter/scripts/lint_skill.py <skill-path>

The script outputs JSON with three sections:

• errors: Must fix before publishing
• warnings: Should fix (script confident these are issues)
• review: Candidates needing your judgment (see Phase 2)

Interpreting Results

Errors (must fix)

These are validation failures that will cause problems:

Code	Issue
SKILL001	Missing frontmatter
SKILL002	Missing name field
SKILL003	Missing description field
SKILL004	Name exceeds 64 characters
SKILL005	Name has invalid characters (must be [a-z0-9-]+)
SKILL006	Name contains reserved words (anthropic, claude)
SKILL007	Name contains XML tags
SKILL008	Description is empty
SKILL009	Description exceeds 1024 characters
SKILL010	Description contains XML tags
SKILL012	Body exceeds 750 lines
SKILL018	Windows-style paths (backslashes)
SKILL021	Broken internal file references

Warnings (should fix)

These indicate likely issues:

Code	Issue
SKILL011	Body exceeds 500 lines
SKILL013	Description uses first person ("I can", "I will")
SKILL014	Description uses second person ("You can", "You should")
SKILL015	Description missing context trigger (when/use)
SKILL016	Description under 50 characters
SKILL017	Vague description patterns
SKILL019	Nested file references (md linking to md)
SKILL022	Inconsistent terminology
SKILL023	Time-sensitive date references
SKILL026	Magic numbers without comments
SKILL029	Vague name (helper, utils, tools)
SKILL030	"When to use" section in body
SKILL031	Unqualified MCP tool reference

Info (consider fixing)

Code	Issue
SKILL020	Reference files >100 lines without TOC
SKILL024	Many options without clear default
SKILL025	Potentially verbose sections
SKILL028	Name not in gerund form
SKILL032	Package install without availability context

Review Flagged Items

For items in review, read the skill and apply judgment:

Terminology consistency (review.terminology)

The script found multiple terms for similar concepts. Determine: Are these genuinely inconsistent, or contextually appropriate?

Example output:

{"extract": 5, "retrieve": 2, "pull": 1}

If the skill uses these interchangeably for the same action, pick one term.

Verbosity candidates (review.verbosity_candidates)

The script flagged sections that may explain things Claude already knows.

Example:

{"line": 45, "text": "PDF (Portable Document Format) files are..."}

Evaluate: Does Claude need this explanation? Would a code example work better?

Uncommented constants (review.uncommented_constants)

Constants without explanatory comments:

{"line": 102, "code": "TIMEOUT = 47"}

Determine: Is this value justified? Should it be documented?

Options without defaults (review.options_without_defaults)

Multiple alternatives presented without guidance:

{"line": 88, "text": "You can use pypdf, or pdfplumber, or PyMuPDF..."}

Provide a default recommendation with an escape hatch for edge cases.

Manual Review Checklist

These require reading the skill holistically:

• [ ] Is the skill concise enough for its purpose?
• [ ] Does it assume Claude knows common concepts?
• [ ] Are degrees of freedom appropriate for task fragility?
• [ ] Would examples improve clarity?
• [ ] Are workflows clear and sequential?
• [ ] Do scripts handle errors explicitly (not punt to Claude)?

Common Fixes

SKILL013/014: Point of view

Change first/second person to third person:

• "I can process PDFs" → "Processes PDFs"
• "You can use this to" → "Use when"

SKILL015: Missing context trigger

Add when to use the skill:

• "Processes PDF files" → "Processes PDF files. Use when working with PDFs or extracting document text."

SKILL011: Body too long

Split content into separate files using progressive disclosure:

## Advanced features
See ADVANCED.md for detailed configuration.

SKILL022: Inconsistent terminology

Pick one term and use it consistently:

• Bad: "extract", "pull", "retrieve", "get"
• Good: "extract" (used throughout)

SKILL030: "When to use" in body

Move the "when to use" context into the description field. The body should focus on how to use the skill, not when.

Running on Multiple Skills

Lint all skills in a directory:

for dir in skills/*/; do
  python scripts/lint_skill.py "$dir"
done

Exit Codes

• 0: No errors (warnings/info may exist)
• 1: Errors found
• 2: Invalid arguments or skill not found