skill-lint

A zero-dependency, deterministic linter and token-budget estimator for AI agent specifications (SKILL.md). Compatible with OpenCode, Cursor, Claude Code, and MCP skill ecosystems.

---

Why skill-lint?

AI agent contexts are precious. Adding bloated or malformed skills to your agent workflows leads to:

1. Context Waste: Descriptions exceeding 300+ characters eat your context window on every single request.
2. Execution Drift: Vague, non-imperative descriptions ("A skill that helps with...") reduce agent trigger reliability.
3. Broken References: Relative markdown links to non-existent scripts or docs cause agent hallucinations.

skill-lint enforces clean, concise, production-ready agent skills locally and in CI pipelines.

---

Installation

Run directly with npx (zero install needed):

npx skill-lint ./skills

Or install globally:

npm install -g skill-lint

---

Rules Enforced

Rule ID	Severity	Description
frontmatter/required	Error	Ensures standard --- YAML frontmatter exists.
frontmatter/name-kebab-case	Error	Enforces lower-case kebab-case names (e.g. db-migrate).
frontmatter/description-imperative	Warning / Error	Ensures description begins with an active action verb (Inspect, Generate, Audit).
frontmatter/description-cliché	Warning / Error	Flags lazy clichés like "A skill that..." or "Used to...".
markdown/single-h1	Warning	Forbids multiple # headers to keep document topology clear.
markdown/broken-local-link	Error	Validates that local referenced paths (scripts, configs) actually exist.
budget/token-limit-exceeded	Warning / Error	Flags skills that exceed the context token budget (default: 2500 tokens).

---

Usage & CLI Options

skill-lint [path] [options]

Options

• -s, --strict: Treat all warnings as errors (recommended for CI).
• -m, --max-tokens <n>: Override maximum allowed token threshold (default: 2500).
• --json: Output raw JSON report for tooling integration.
• -q, --quiet: Silence non-error output.

---

GitHub Actions Integration

Add this to .github/workflows/lint-skills.yml:

name: Lint Agent Skills

on:
  pull_request:
    paths:
      - '**/SKILL.md'
      - '**/*.skill.md'

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx skill-lint . --strict

---

License

MIT © luckdevx