<!-- Generated by scripts/generate-site-content.py — do not edit by hand -->


# context-budget

Warn when instruction or config files exceed recommended token limits

| | |
|---|---|
| **Severity** | warning (auto) |
| **Autofix** | - |
| **Since** | v0.7.0 |
| **Category** | [Context Budget](context-budget.md) |

## 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.

`content-progressive-disclosure` is the companion rule: it flags
over-budget files that haven't started this split (no references to
other local files) and recommends the split-and-link refactor
specifically.

## Tuning

Override per-category token limits:

```yaml
rules:
  context-budget:
    limits:
      claude-md:
        warn: 8000
        error: 16000
      skill:
        warn: 4000
        error: 8000
      memory:            # committed .agents/memory/ notes
        warn: 6000
        error: 12000
```

## Configuration

```yaml
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}, "qwen-md": {"warn": 6000, "error": 12000}, "instruction": {"warn": 4000, "error": 8000}, "memory": {"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.*