Skill Validator

Skill Validator

Validate SKILL.md files against the Agent Skills specification and Claude Code extensions.

When to Run

• After creating a new skill
• After modifying a skill's SKILL.md frontmatter
• Before committing skill changes
• During periodic repo audits

Validation Rules

Required Fields (Agent Skills Spec)

Every SKILL.md must have YAML frontmatter with:

• name — kebab-case, matches directory name
• description — 1-3 sentences, under 1024 chars, starts with verb or domain noun

Metadata Block

version and tags must be inside metadata:, never top-level:

# CORRECT
metadata:
  version: "1.0.0"
  tags: "react, performance, optimization"

# WRONG — top-level version
version: 1.0.0

# WRONG — tags as YAML list
metadata:
  tags:
    - react
    - performance

Forbidden Fields

These are not part of any spec:

• auto_activate / auto_trigger — removed in 2026-04 migration
• risk — not in Agent Skills or Claude Code specs

Claude Code Extensions (Optional)

Valid extension fields:

Content Rules

• No hardcoded /workspace/ paths
• No tool names in instructions (say "search for" not "use Grep")
• Imperative/infinitive style ("Configure X" not "You should configure X")
• Code blocks use real backtick fences, not escaped \\\`

Validation Process

1. Read the SKILL.md frontmatter 2. Check name matches parent directory name 3. Check description exists and is under 1024 chars 4. Check description plus when_to_use is under 1536 chars 5. Check plugin.json description is present and under 100 chars 6. Check version/tags are NOT top-level (must be inside metadata:) 7. Check for forbidden fields (auto_activate, auto_trigger, risk) 8. Check for escaped backtick fences in content 9. Check for hardcoded paths (/workspace/, project-specific paths) 10. Run bunx markdownlint-cli on the file 11. Run ./scripts/validate-skill-sync.sh for cross-validation

Quick Validation Command

# Single skill
bunx markdownlint-cli skills/<name>/SKILL.md skills/<name>/references/*.md

# All skills
bunx markdownlint-cli --ignore bundles --ignore dist "**/*.md"

# Sync validation
./scripts/validate-skill-sync.sh