Skillcheck

skillcheck is a static analyzer for SKILL.md files. It validates frontmatter structure, scores description discoverability, checks file references, and extracts a capability graph from heading and backtick-reference patterns. Run it before committing a skill, plugging it into CI, or publishing to a skill registry.

Prerequisites

• path - the SKILL.md file or directory to validate
• prompt.txt - file path for a saved agent prompt (critique or graph extraction)
• response.json - file path for an agent-provided JSON response

Validate a skill

Pass path to skillcheck for a full structural check against the agentskills.io specification. Validates name constraints, description quality, body sizing, file references, and cross-agent compatibility. The validation report is written to stdout. Exit codes: 0 no errors, 1 errors found, 2 input error (missing file), 3 symbolic passed but semantic critique flagged errors.

skillcheck <path>
skillcheck <path> --format json

Review a skill with an agent

skillcheck generates a structured critique prompt for path and ingests response.json as the agent's reply. Save the emitted prompt to prompt.txt. The merged validation report combines symbolic diagnostics and semantic findings from the critique.

skillcheck <path> --emit-critique-prompt > prompt.txt

Hand prompt.txt to your agent. The agent returns JSON. Save the response as response.json, then ingest it.

skillcheck <path> --ingest-critique response.json

Pass --critique-agent codex or --critique-agent cursor to select a prompt variant tuned for that platform. The critique JSON schema is identical across all agent targets.

Extract a capability graph

skillcheck extracts the capability graph from heading structure and backtick references in the body of path. Use prompt.txt for emitted graph prompts and ingest response.json from your agent for richer extraction.

Run graph analysis using the heuristic extractor (no agent needed):