skills-lint

Token budget linter for agent skill files. Validates that your markdown skill files stay within per-model token limits so they work reliably across LLMs.

Install

npm install skills-lint

Or run directly:

npx skills-lint

Usage

# Lint all files matched by .skills-lint.config.json
skills-lint

# Lint a single file
skills-lint --file path/to/SKILL.md

# Use a custom config
skills-lint --config my-config.json

# Suppress the ASCII banner (useful in CI)
skills-lint --quiet

# Disable token-count caching
skills-lint --no-cache

Configuration

Create a .skills-lint.config.json in your project root:

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

Supported models

| Model | Context | Max Input | Encoding | Recommended Warning | Recommended Error | |---|---|---|---|---:|---:| | gpt-5 | 400K | 272K | o200k_base | 16,000 | 32,000 | | gpt-4o | 128K | 112K | o200k_base | 8,000 | 16,000 | | gpt-4o-mini | 128K | 112K | o200k_base | 8,000 | 16,000 | | gpt-4-turbo | 128K | 124K | cl100k_base | 8,000 | 16,000 | | gpt-4 | 8K | 4K | cl100k_base | 2,000 | 4,000 | | gpt-3.5-turbo | 16K | 12K | cl100k_base | 4,000 | 8,000 |

Skill files are loaded lazily into the model's context window. The recommended budgets keep skill files to roughly 5–10% of the model's effective input capacity. Encoding is auto-selected from the model name.

Fields

| Field | Description | |---|---| | patterns | Glob patterns to discover skill files | | rules.token-limit.models | Per-model token counting configuration | | models.<name>.warning | Token count threshold for warnings | | models.<name>.error | Token count threshold for errors | | models.<name>.encoding | (Optional) override the default tokenizer encoding |

Per-file overrides

Override thresholds for specific files:

{
  "patterns": ["./.github/**/SKILL.md"],
  "rules": {
    "token-limit": {
      "models": {
        "gpt-4o": { "warning": 8000, "error": 16000 }
      }
    }
  },
  "overrides": [
    {
      "files": [".github/skills/large-skill/SKILL.md"],
      "rules": {
        "token-limit": {
          "models": {
            "gpt-4o": { "warning": 16000, "error": 32000 }
          }
        }
      }
    }
  ]
}

Caching

Token counts are cached to .skills-lint-cache/tokens.json by default. Subsequent runs skip tokenization for unchanged files. Disable with --no-cache or set "cache": false in the config. Add .skills-lint-cache/ to your .gitignore.

Exit codes

| Code | Meaning | |---|---| | 0 | All checks passed | | 1 | One or more files exceed the error threshold | | 2 | One or more files exceed the warning threshold (no errors) | | 3 | Configuration or runtime error |

Supported platforms

Pre-built binaries are available for:

| OS | Architecture | |---|---| | macOS | ARM64, x64 | | Linux | ARM64, x64 | | Windows | ARM64, x64 |

License

MIT