Static analyzer for SKILL.md files. Validates frontmatter, body sizing, file references, and cross-agent compatibility against the agentskills.io specification. No network calls. No LLM API calls. No file mutations.

744 tests cover all rule modules.

Install

pip install skillcheck

Requires Python 3.10 or later. For more accurate token estimates, install the optional extra:

pip install "skillcheck[tiktoken]"

Usage

skillcheck SKILL.md            # validate one file
skillcheck skills/             # scan a directory for files named SKILL.md
skillcheck SKILL.md --format json
skillcheck --help              # full flag reference

Sample output:

✔ PASS  skills/claude-api/SKILL.md
  line 2   ⚠ warning  frontmatter.name.reserved-word  Name contains the term 'claude'.
  line 4   · info     frontmatter.field.ecosystem      Field 'license' is ecosystem-common.

Checked 18 files: 18 passed, 0 failed, 29 warnings

GitHub Action

- uses: moonrunnerkc/skillcheck@v1
  with:
    path: skills/

Diagnostics appear as inline PR annotations. Inputs documented in action.yml.

pre-commit

repos:
  - repo: https://github.com/moonrunnerkc/skillcheck
    rev: v1.3.0
    hooks:
      - id: skillcheck

What it checks

• Frontmatter: required fields, types, name and description length limits, reserved-word collisions.
• Description quality: 0-100 score across action verbs, trigger phrases, keywords, specificity, and length.
• Sizing: line and token thresholds against the agentskills.io disclosure budgets.
• References: broken links, escapes outside the skill directory, depth limits.
• Cross-agent compatibility: Claude Code, VS Code, Codex, Cursor.
• Capability graph (--analyze-graph): orphaned capabilities, unused inputs, unproduced outputs, unreferenced tools.
• History ledger (--history): per-skill append-only JSON file tracking validation results across runs.

Agent modes

When the calling agent can run a prompt, skillcheck can ingest its response and merge findings into the report:

skillcheck SKILL.md --emit-critique-prompt > prompt.txt
# hand prompt.txt to the agent, then:
skillcheck SKILL.md --ingest-critique response.json

The same flow exists for capability graph extraction (--emit-graph-prompt / --ingest-graph). Prompt variants are tuned per agent via --critique-agent and --graph-agent (claude, codex, cursor).

Exit codes

Code	Meaning
0	No errors. Warnings alone exit 0 unless --strict is set.
1	One or more errors, or warnings with --strict, or regression with --fail-on-regression.
2	Input or argument error (missing path, conflicting flags, malformed input).
3	Symbolic checks passed but an ingested critique reported semantic errors.

Configuration

Defaults live in a skillcheck.toml discovered upward from the validated path. Override per invocation with --config PATH. Organization-specific frontmatter keys belong under [frontmatter] extension_fields.

Documentation

• CONTRIBUTING.md: testing, maintainer workflows, rule-authoring conventions.
• docs/case-study-v1-real-world-runs.md: runs against the Anthropic skills corpus.
• docs/case-study-silent-skill-failure.md: VS Code dirname-mismatch incident.
• skills/skillcheck/SKILL.md: a SKILL.md that passes every rule.

License

MIT. See LICENSE.