@jkeskikangas/skillcheck

Linter for agent skill directories (for example skills/<skill-name>/SKILL.md + agents/openai.yaml + references/).

Use it to catch broken links, missing frontmatter, and rubric drift before you ship skills to your team or publish them.

• Fast local feedback (npx @jkeskikangas/skillcheck skills/)
• CI-friendly exit codes + optional JSON output (--format json)
• Cross-platform (Node.js 18+, no native deps)

Install

# Recommended (project devDependency)
npm install -D @jkeskikangas/skillcheck

# Or run without installing (great for CI / one-offs)
npx @jkeskikangas/skillcheck skills/

# Or install globally
npm install -g @jkeskikangas/skillcheck

Quick start

Lint all skills under skills/:

skillcheck skills/

Lint a single skill directory:

skillcheck skills/<skill-name>

Help:

skillcheck --help

Usage

skillcheck skills/                    # lint all skills
skillcheck skills/<skill-name>        # lint a single skill
skillcheck --fix skills/              # auto-fix rubric drift
skillcheck --format json skills/      # machine-readable output
skillcheck --skills-only skills/      # skip rubric checks
skillcheck --rubrics-only skills/     # skip skill checks
skillcheck --max-lines 500 skills/    # max allowed SKILL.md lines

What it checks

• Frontmatter — required fields, valid types, schema conformance
• Links — referenced files exist (agents/, references/)
• Rubrics — validates markdown rubrics discovered in references/*rubric*.md
• openai.yaml — tool definitions, token budget, safety constraints

Example output

When diagnostics are found, skillcheck exits non-zero and prints a one-line summary to stdout, with details on stderr:

[FAIL] 4 diagnostics in 1 skill.
P1 frontmatter-invalid  skills/writing-skills/SKILL.md  Missing required field: name
P2 link-missing         skills/writing-skills/SKILL.md  references/portability.md not found

When everything is valid:

[OK] 4 skills and 2 rubrics valid.

Options

• --format stylish|json (default: stylish)
• --max-lines <n>: max allowed SKILL.md lines (default: 500)
• --fix: auto-fix rubric drift (only applies to rubric checks)
• --skills-only: skip rubric checks
• --rubrics-only: skip skill checks

Exit codes

• 0 — no diagnostics found
• 1 — diagnostics found
• 2 — CLI usage / argument error

JSON output

Use --format json for tooling and CI integrations:

skillcheck --format json skills/ > skillcheck.json

The JSON shape matches the schema in the source repo:

• schemas/lint-output.schema.json

Source: https://github.com/jkeskikangas/skills

CI (GitHub Actions)

Typical consumer usage (no repo checkout needed):

- name: Lint skills
  run: npx @jkeskikangas/skillcheck skills/

If you vendor skillcheck into a monorepo (this package’s own repo layout):

- name: Install
  run: npm ci
  working-directory: packages/skillcheck

- name: Build
  run: npm run build
  working-directory: packages/skillcheck

- name: Lint skills (repo-local)
  run: node packages/skillcheck/bin/skillcheck.js skills/

Development

cd packages/skillcheck && npm ci
cd packages/skillcheck && npm run build
cd packages/skillcheck && npm test

Related tooling

skillcheck focuses on structural validation and rubric consistency. For spec-level portability linting across agents, pair it with agnix in CI.

License

Apache-2.0