skillcheck

Lint SKILL.md files — the format used by Claude Code, Codex, Cursor, and other agent tools — for the kind of mistakes that don't show up until an agent silently fails to load the skill you wrote.

Marketplaces like SkillsMP and aiskillstore scan skills for malicious content when you submit them. skillcheck checks the thing before that: is the file even well-formed? Run it locally or in CI, on your own repo, before you ever publish anywhere.

What it catches

Rule	Severity	What it means
missing-frontmatter	error	No --- YAML block at the top of the file
missing-name	error	Frontmatter has no name field
missing-description	error	Frontmatter has no description field
name-format	warning	name contains characters outside a-z0-9:_-
empty-body	warning	Frontmatter exists but there's no content below it
description-too-short	warning	Description is unlikely to give Claude enough signal to trigger on
description-too-long	warning	Every installed skill's description loads up front — bloat adds up
token-budget	warning	Estimated token count of the whole file exceeds your budget
broken-reference	error	A relative markdown link points at a file that doesn't exist
duplicate-name	error	Two skills in the same tree share a name, making triggering ambiguous

Install

npm install -D skillcheck

Or run it once without installing:

npx skillcheck ./skills

Usage

skillcheck                          # lint SKILL.md files under the current directory
skillcheck ./skills                 # lint a specific directory
skillcheck ./skills/my-skill/SKILL.md   # lint a single file
skillcheck --json                   # machine-readable output
skillcheck --strict                 # exit 1 on warnings too, not just errors
skillcheck --max-body-tokens 1500   # tighten the token budget

Exit code is 0 when there are no errors, 1 otherwise (or when there are warnings and --strict is set) — safe to drop straight into CI.

GitHub Action

- uses: diya73/skillcheck@v0
  with:
    path: ./skills
    strict: true

(Replace diya73/skillcheck with wherever this ends up living once it's pushed — the action definition is action.yml at the repo root.)

Programmatic use

import { lint } from "skillcheck";

const result = lint("./skills", { maxBodyTokens: 1500 });
console.log(result.errorCount, result.warningCount);

Config

All options are CLI flags (see skillcheck --help) or the second argument to lint():

Option	Default
minDescriptionWords	8
maxDescriptionChars	1024
maxBodyTokens	2500
strict	false

Development

npm install
npm run build     # compile src/ -> dist/
npm test          # node's built-in test runner against test/fixtures
npm run lint:self # run skillcheck against this repo's own skills, if any

License

MIT