Getting Started

What is skills-lint?

Token budget linter for agent skill files. Counts tokens using tiktoken and reports when files exceed per-model thresholds.

Install

npm install -g @haasstefan/skills-lint

Pre-built binaries for macOS, Linux, and Windows (ARM64 + x64).

Quick Start

1. Create a config file:

Run the interactive wizard to generate .skills-lint.config.json:

skills-lint init

This walks you through selecting models, rules, and token budgets with recommended defaults.

Alternatively, create .skills-lint.config.json manually in your project root:

{
  "patterns": ["./.github/**/SKILL.md"],
  "rules": {
    "token-limit": {
      "models": {
        "gpt-4o": { "warning": 8000, "error": 16000 },
        "gpt-4": { "warning": 2000, "error": 4000 }
      }
    }
  }
}

Encoding is selected automatically from the model name.

2. Run:

skills-lint

3. Exit codes:

Code	Meaning
0	All pass
1	Error (at least one file over error threshold)
2	Warning only
3	Runtime error

Next

• Configuration — models, overrides, patterns
• Rules — all six rules: token-limit, frontmatter-limit, skill-index-budget, skill-structure, unique-name, unique-description
• CI Integration — GitHub Actions setup
• CLI Reference — flags and output format