context-budget

Warn when instruction or config files exceed recommended token limits

Severity	warning (auto)
Autofix	-
Since	v0.7.0
Category	Context Budget

Why

Instruction and configuration files share the model's context window. When a single file exceeds its recommended token limit, it crowds out other files and degrades the model's ability to follow instructions from any of them. Limits vary by file type — a CLAUDE.md has a larger budget than a skill description.

Examples

Bad:

A 25,000-token CLAUDE.md that includes full API documentation inline.

Good:

A 4,000-token CLAUDE.md with key instructions, linking to external docs via @references/ or @ imports for detail.

How to fix

Split large files into smaller, focused files. Move reference material into @-imported files or .claude/rules/ scoped rule files that only load when relevant. For skill and command descriptions, shorten the frontmatter description to a concise trigger phrase.

Tuning

Override per-category token limits:

rules:
  context-budget:
    limits:
      claude-md:
        warn: 8000
        error: 16000
      skill:
        warn: 4000
        error: 8000

Configuration

rules:
  context-budget:
    enabled: auto  # true | false | auto
    severity: warning

Parameter	Description	Default
limits	Token limits per file category (int for warn-only, or {warn, error} dict)	{"agents-md": {"warn": 6000, "error": 12000}, "claude-md": {"warn": 6000, "error": 12000}, "gemini-md": {"warn": 6000, "error": 12000}, "instruction": {"warn": 4000, "error": 8000}, "skill": {"warn": 3000, "error": 6000}, "command": {"warn": 2000, "error": 4000}, "agent": {"warn": 2000, "error": 4000}, "rule": {"warn": 2000, "error": 4000}, "skill-description": {"warn": 200, "error": 500}, "command-description": {"warn": 200, "error": 500}}

Run skillsaw explain context-budget to see this documentation and the rule's effective configuration in your terminal.