skill-validator

name	skill-validator
description	Validate SKILL.md files against the Agent Skills spec and Claude Code extensions. Run on new or modified skills before committing.
metadata	{"internal":true,"version":"1.0.3","tags":"validation, skills, spec-compliance, quality"}

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 (must match allowed_fields in scripts/validate-skill-sync.sh):

Field	Purpose
when_to_use	Extra trigger phrases appended to description
disable-model-invocation	Prevent auto-triggering (for destructive skills)
user-invocable	false hides from the / menu
allowed-tools	Auto-approve allowlist (not a sandbox — unlisted tools stay callable)
disallowed-tools	Removes tools from the pool while active (the actual block mechanism)
argument-hint	Autocomplete hint for expected arguments
compatibility	Environment prerequisites (packages, network, target agent)
context	fork for subagent isolation
agent	Subagent type when context: fork
hooks	Lifecycle hooks scoped to the skill
paths	⚠️ Broken upstream (#49835) — flag if present
shell	bash (default) or powershell

Forbidden Fields (updated)

• auto_activate / auto_trigger — removed in 2026-04 migration
• risk — not in any spec
• metadata.triggers — duplicate activation metadata; put trigger phrases in description or when_to_use
• model / effort — recognized by Claude Code but owned by app/session configuration, not public reusable skills
• Any top-level field not in the tables above → "Unsupported top-level frontmatter field"

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 \```
• No concrete model names in body, references/, or scripts/ — reject tier+version IDs (claude-3-7-sonnet-20250219, claude-opus-4.5, gpt-5.5), dated snapshots, and bare family names used as routing keys. Exception: orchestrator skills may name capability tiers in prose. See skill-standards.md → Model references.
• No harness-owned execution parameters in skills, commands, or routine templates. Apply execution-boundary.md.
• Routine templates follow routine-standards.md. Run python3 scripts/audit-routines.py to detect duplicate bodies and app-parameter leakage without printing prompt or configuration values.
• Provenance (derived skills only): when metadata.source is set, metadata.last_synced and a README ## Upstream section are required (enforced by check_provenance()). In-house skills need no provenance fields.

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, model, effort, any field not in the extension tables)
8. Check for escaped backtick fences in content
9. Validate frontmatter value types: allowed-tools is a scalar, metadata.version and metadata.tags are quoted scalars, and metadata is a map
10. Reject duplicate metadata.triggers; keep activation guidance in description or when_to_use
11. Check for hardcoded paths (/workspace/, project-specific paths)
12. Grep body + references/ + scripts/ for concrete model names (claude-*, gpt-*, sonnet/opus/haiku used as IDs); allow only capability-tier prose in orchestrator skills
13. Warn when skills, commands, or templates set harness-owned execution parameters
14. Warn when a side-effecting skill lacks both disable-model-invocation: true and an explicit Confirmation Required gate
15. Check prose routing references across the body, excluding frontmatter and code fences, and flag missing local skills
16. Check provenance for derived skills: if metadata.source is set, require metadata.last_synced and a README ## Upstream section
17. Run bunx markdownlint-cli on the file
18. 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