skillint

A zero-dependency CLI that statically validates SKILL.md and CLAUDE.md files against the Claude Code spec — frontmatter schema, size budgets, dangling tool/file references — so broken or oversized memory/skill files fail CI before they silently degrade an agent's context.

For maintainers of Claude Code skill libraries and multi-repo CLAUDE.md hierarchies.

Install

npm install

Once published, the CLI will also be installable globally:

npm install -g skillint

Usage

skillint check <dir>

Recursively finds every SKILL.md / CLAUDE.md file under a directory and runs the full rule set against each one, printing a report:

node bin/skillint.js check path/to/skills

✖ path/to/skills/broken/SKILL.md
  4:1  DANGLING_FILE_REFERENCE  Referenced file does not exist: "./scripts/missing.sh"
✔ path/to/skills/valid/SKILL.md

2 files checked, 1 file failed, 1 error

Pass --json for a machine-readable report instead:

node bin/skillint.js check path/to/skills --json

{
  "ok": false,
  "files": [
    { "filePath": "...", "ok": false, "errors": [ { "code": "...", "message": "...", "line": 4 } ] }
  ],
  "summary": { "filesChecked": 2, "filesFailed": 1, "errorCount": 1 }
}

skillint check exits with status 1 if any file fails a check, 2 on a usage error (missing/invalid directory argument), and 0 otherwise — so it can be dropped straight into CI.

Direct file mode

Parse and print the frontmatter of one or more files directly:

node bin/skillint.js path/to/SKILL.md

node bin/skillint.js path/to/SKILL.md path/to/CLAUDE.md

Each file's name / description / type frontmatter fields are printed as JSON on success. If a file's frontmatter block is missing, unterminated, or malformed, skillint prints an error to stderr for that file and exits with a non-zero status.

Both modes run the same structural rules engine against every file:

• Line-count budgets — MEMORY.md files are truncated by Claude Code at 200 lines, so anything beyond that is silently invisible to the agent; skillint reports LINE_BUDGET_EXCEEDED if a file crosses its budget (200 lines for MEMORY.md, 500 for SKILL.md / CLAUDE.md / others).
• Required fields — name and description must be present and non-empty in frontmatter, or skillint reports MISSING_REQUIRED_FIELD.
• Duplicate names — if two or more files passed on the command line share the same frontmatter name, skillint reports DUPLICATE_NAME for each file involved, which catches accidental copy-pasted skills in a skills directory.
• Dangling file references — markdown links ([text](path)) and path-like inline code spans (`scripts/setup.sh`) in the file body are resolved relative to the skill file's directory; if the target doesn't exist on disk, skillint reports DANGLING_FILE_REFERENCE. URLs and anchor links are ignored.
• Unknown tool references — `Read` tool-style prose mentions and entries in the allowed-tools frontmatter field are checked against the known Claude Code tool list; anything else is reported as UNKNOWN_TOOL_REFERENCE, catching typoed or renamed tool names before they silently no-op.

Run the test suite:

npm test

CI

An example GitHub Actions workflow that installs skillint and runs skillint check on every push and pull request lives at .github/workflows/skillint.yml. Copy it into your own repo (adjusting the check target directory) to fail CI when a SKILL.md / CLAUDE.md file breaks the spec.

Status

Built autonomously, one milestone at a time. Changes are gated on a passing test suite (npm test) before being merged.