Config Schema

Reference for .skills-lint.config.json.

Top-Level

Field	Type	Required	Description
patterns	string[]	Yes	Glob patterns for skill files
rules	object	Yes	Rule config (see below)
overrides	object[]	No	Per-file overrides (applies to token-limit only)
cache	boolean	No	Enable token-count caching (default: true, see Caching)

rules.token-limit.models.<name>

Model name must be one of: gpt-5, gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo.

Field	Type	Required	Default	Description
warning	number	Yes	—	Warning threshold
error	number	Yes	—	Error threshold
encoding	string	No	Auto	Encoding override

rules.frontmatter-limit (optional)

Counts tokens in just the YAML frontmatter of each file. Same models schema as token-limit — no per-file overrides.

rules.frontmatter-limit.models.<name>

Model name must be one of: gpt-5, gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo.

Field	Type	Required	Default	Description
warning	number	Yes	—	Warning threshold for frontmatter
error	number	Yes	—	Error threshold for frontmatter
encoding	string	No	Auto	Encoding override

Omit the entire frontmatter-limit key to disable the rule. Files without frontmatter are skipped.

rules.skill-index-budget (optional)

Aggregates YAML frontmatter from all discovered SKILL.md files and checks the combined token count per model. Same schema as token-limit — no per-file overrides.

rules.skill-index-budget.models.<name>

Model name must be one of: gpt-5, gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo.

Field	Type	Required	Default	Description
warning	number	Yes	—	Warning threshold for aggregate frontmatter
error	number	Yes	—	Error threshold for aggregate frontmatter
encoding	string	No	Auto	Encoding override

Omit the entire skill-index-budget key to disable the rule. Skipped when using --file.

rules.skill-structure (optional)

Validates the structure of each SKILL.md file: frontmatter presence, name and description fields, and non-empty body.

Value	Behavior
true	Rule is enabled
false or absent	Rule is skipped

Runs in both aggregate and --file modes.

rules.unique-name (optional)

Checks that no two skill files share the same name in their frontmatter.

Value	Behavior
true	Rule is enabled
false or absent	Rule is skipped

Skipped when using --file.

rules.unique-description (optional)

Checks that no two skill files share the same description in their frontmatter.

Value	Behavior
true	Rule is enabled
false or absent	Rule is skipped

Skipped when using --file.

overrides[]

Field	Type	Required	Description
files	string[]	Yes	Exact file paths
rules	object	Yes	Same structure as top-level rules

Override fields are optional — unspecified fields inherit from global config.

Minimal

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

Full

{
  "patterns": ["./.github/**/SKILL.md"],
  "rules": {
    "token-limit": {
      "models": {
        "gpt-4o": { "warning": 8000, "error": 16000 },
        "gpt-4": { "warning": 2000, "error": 4000 }
      }
    },
    "frontmatter-limit": {
      "models": {
        "gpt-4o": { "warning": 1000, "error": 2000 },
        "gpt-4": { "warning": 500, "error": 1000 }
      }
    },
    "skill-index-budget": {
      "models": {
        "gpt-4o": { "warning": 2000, "error": 4000 },
        "gpt-4": { "warning": 1000, "error": 2000 }
      }
    },
    "skill-structure": true,
    "unique-name": true,
    "unique-description": true
  },
  "overrides": [
    {
      "files": [".github/skills/large-skill/SKILL.md"],
      "rules": {
        "token-limit": {
          "models": {
            "gpt-4o": { "warning": 16000, "error": 32000 }
          }
        }
      }
    }
  ]
}