Skip to content
waza

Token Limits Configuration

waza tokens check enforces per-file token budgets so skills stay within the context window constraints required for submission.

Configuration Priority

Section titled “Configuration Priority”

Token limits are resolved in this order — the first source that provides limits wins:

Priority Source Notes
1 .waza.yaml → tokens.limits Recommended. Workspace-level config.
2 .token-limits.json in the skill directory Legacy fallback. Emits a deprecation warning.
3 Built-in defaults Applied when neither source is present.
Section titled “.waza.yaml tokens Section (Recommended)”

Add a tokens section to your project’s .waza.yaml to manage all limits in one place:

tokens:
  warningThreshold: 2500   # Print a warning when a file exceeds this many tokens
  fallbackLimit: 2000      # Limit applied to files that match no pattern
  limits:
    defaults:
      "SKILL.md": 500
      "references/**/*.md": 1000
      "*.md": 2000
    overrides:
      "README.md": 3000

tokens fields

Section titled “tokens fields”
Field Type Default Description
warningThreshold integer 2500 Token count at which a soft warning is shown
fallbackLimit integer 1000 Limit for files that match no pattern
limits.defaults map (built-in) Glob patterns → token limits
limits.overrides map {} Exact file paths → token limits (take precedence over defaults)

Both limits.defaults and limits.overrides are optional — you can set only one of them. If tokens.limits is present in .waza.yaml but neither map is set, .token-limits.json is not consulted as a fallback; .waza.yaml is the definitive source.

.token-limits.json (Legacy Fallback)

Section titled “.token-limits.json (Legacy Fallback)”

Skills that don’t use .waza.yaml can still configure limits in a .token-limits.json file placed inside the skill directory:

{
  "description": "Optional human-readable description",
  "defaults": {
    "SKILL.md": 500,
    "references/**/*.md": 1000,
    "*.md": 2000
  },
  "overrides": {
    "README.md": 3000
  }
}
Field Required Type Description
description No string Ignored by the CLI; for humans only
defaults Yes object Glob patterns → token limits
overrides No object Exact file paths → token limits

Pattern Matching

Section titled “Pattern Matching”

The same pattern matching rules apply to both .waza.yaml limits.defaults and .token-limits.json defaults.

Overrides (exact-path matching)

Section titled “Overrides (exact-path matching)”

Entries in overrides match by suffix — the pattern is compared against the end of the normalized file path:

overrides:
  "README.md": 4000       # matches ./README.md and subdir/README.md
  "docs/API.md": 3000     # matches ./docs/API.md and subdir/docs/API.md

Overrides are checked before defaults and always take precedence.

Defaults (glob matching)

Section titled “Defaults (glob matching)”
Pattern Matches
*.md Any .md file at any depth
SKILL.md Files named exactly SKILL.md in any directory
references/*.md .md files directly in references/
references/**/*.md .md files in subdirectories of references/
docs/**/*.md .md files in subdirectories of docs/

Glob Syntax Reference

Section titled “Glob Syntax Reference”
Syntax Meaning
* Any characters except /
** Any characters including / (recursive)
/ Directory separator; patterns containing / are anchored to the project root
. Literal dot (automatically escaped)

Pattern Specificity

Section titled “Pattern Specificity”

When multiple patterns in defaults match the same file, the most specific pattern wins:

  1. Exact match (no wildcards): +10 000 points
  2. Path depth: +100 points per / in the pattern
  3. Single wildcards (*): +10 points each
  4. Globstars (**): −50 points each
  5. Pattern length: +1 point per character

Example — resolving references/test-templates/jest.md:

Pattern Specificity Result
*.md Low Fallback
references/*.md Medium No match (file is nested)
references/**/*.md Medium-high Match
references/test-templates/*.md Higher Wins

Built-in Defaults

Section titled “Built-in Defaults”

When neither .waza.yaml nor .token-limits.json provides limits, these defaults apply:

{
  "defaults": {
    "SKILL.md": 500,
    "references/**/*.md": 1000,
    "docs/**/*.md": 1500,
    "*.md": 2000
  },
  "overrides": {
    "README.md": 3000,
    "CONTRIBUTING.md": 2500
  }
}

Complete Example

Section titled “Complete Example”

Resolution table

Section titled “Resolution table”

Given this .waza.yaml configuration:

tokens:
  limits:
    defaults:
      "SKILL.md": 500
      "references/*.md": 2000
      "references/**/*.md": 2000
      "references/test-templates/*.md": 1500
      "*.md": 4000
    overrides:
      "README.md": 4000
File Matching Rule Limit
SKILL.md SKILL.md in defaults 500
README.md README.md in overrides 4000
references/scoring.md references/*.md 2000
references/test-templates/jest.md references/test-templates/*.md 1500
assets/guide.md *.md 4000

Migrating from .token-limits.json

Section titled “Migrating from .token-limits.json”

  1. Copy the defaults and overrides maps from .token-limits.json into .waza.yaml:

    tokens:
      limits:
        defaults:
          "SKILL.md": 500
          "*.md": 2000
        overrides:
          "README.md": 3000

  2. Delete (or keep for reference) .token-limits.json.

  3. Run waza tokens check — no more deprecation warning.

Section titled “Related Commands”