skill-check
Validate agent skill files (SKILL.md) using the skill-check tool. Support both local paths and GitHub repos.
Installation
Ensure skill-check is available before running checks:
- No install (recommended for one-off or agent use):
npx skill-check— uses npm to run the latest version; requires Node.js and network on first run. - Global install (curl):
curl -fsSL https://raw.githubusercontent.com/thedaviddias/skill-check/main/scripts/install.sh | bash— installs a globalskill-checkbinary. - Homebrew:
brew tap thedaviddias/skill-check https://github.com/thedaviddias/skill-checkthenbrew install skill-check.
If the user has not installed skill-check, use npx skill-check so no prior install is needed. To confirm the tool is available, run npx skill-check rules and expect a list of built-in rule IDs.
When to use
- User asks to validate, lint, or check skill files
- User provides a local path (e.g.
~/.cursor/skills,./skills, or a repo root) - User provides a GitHub repo URL and wants skills in that repo validated
Local validation
- Run skill-check against the given path:
- Quick lint only:
npx skill-check check <path> --no-security-scan --format json - Full check (includes security scan):
npx skill-check check <path> --format json
- Quick lint only:
- Parse the JSON output to get diagnostics (ruleId, severity, message, file, line).
- Summarize results for the user: number of skills found, errors vs warnings, and any suggested fixes.
Use --format json when you need to parse output programmatically. Use default text format when showing output directly to the user.
GitHub repo validation
- Clone the repo shallowly into a temp directory, e.g.
git clone --depth 1 <url> /tmp/skill-check-<short-hash>(or use a system temp path). - Run
npx skill-check check /tmp/skill-check-<hash>(with--format jsonif you will parse results). - Report findings to the user.
- Remove the temp directory when done.
Commands reference
npx skill-check check [path]— run validation (+ optional security scan). Default path is.npx skill-check check [path] --no-security-scan— lint only, skip security scannpx skill-check check [path] --format json— machine-readable output with quality scoresnpx skill-check check [path] --format github— GitHub Actions::error/::warningannotationsnpx skill-check check [path] --format html --no-open— self-contained HTML reportnpx skill-check check [path] --fix— auto-fix supported findingsnpx skill-check check [path] --fix --interactive— prompt before each fix (TTY only)npx skill-check check [path] --baseline baseline.json— compare against previous runnpx skill-check new <name>— scaffold a new skill directorynpx skill-check watch [path]— re-run on file changesnpx skill-check diff <pathA> <pathB>— compare diagnostics between two directoriesnpx skill-check rules— list all built-in rules with severity and fixable statusnpx skill-check rules <id>— show detail for a specific rulenpx skill-check report [path]— generate a markdown health report
Interpreting results
- error — spec or rule violation; should be fixed.
- warn — recommendation; may be acceptable depending on context.
- suggestion — every diagnostic includes an actionable suggestion text.
- quality score — 0-100 per skill, weighted across frontmatter (30%), description (30%), body (20%), links (10%), file (10%).
- duplicates —
duplicates.name/duplicates.descriptionwarnings when multiple skills share the same name or description. - Exit code 0 means no errors; non-zero means validation failed or security scan found issues.
Testing this skill
To verify this skill and the skill-check CLI work:
- Check CLI is available: Run
npx skill-check rules. You should see a list of built-in rules (e.g.frontmatter.required,body.max_tokens, etc.). - Validate this repo's skills: From the skill-check repo root, run
npx skill-check check skills/ --no-security-scan. Expect one skill (skills/skill-check/SKILL.md) and zero diagnostics (PASS). - Scaffold a test skill: Run
npx skill-check new test-skill --dir /tmp. Verify/tmp/test-skill/SKILL.mdwas created, thennpx skill-check check /tmp/test-skill --no-security-scanshould pass. - Optional — validate with security scan: Run
npx skill-check check skills/(no--no-security-scan). Requiresmcp-scanoruv/pipxfor the security scan step.
