# Token Budget Check

> Analyze markdown files for token budget compliance. Checks word count, section lengths, and overall file size against documentation guidelines. Use proactively when creating or reviewing documentation files, knowledge-copilot pages, or when a doc might be over-budget for agent context loading.

- Skill: `everyone-needs-a-copilot/token-budget-check` (Agent Skill)
- Install (CLI): `npx skillmds@latest add everyone-needs-a-copilot/token-budget-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/everyone-needs-a-copilot/token-budget-check/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Everyone-Needs-A-Copilot (https://skillmd.com/u/everyone-needs-a-copilot)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/everyone-needs-a-copilot/token-budget-check

---


# Token Budget Check

Analyze markdown files to ensure they comply with token budget guidelines.

## Purpose

Knowledge Copilot files have token budgets to optimize AI ingestion. This skill checks files against those budgets and suggests optimizations when over budget.

## Token Budgets by Document Type

| Document Type | Max Tokens | Max Words |
|---------------|------------|-----------|
| Skill (SKILL.md) | 2,000 | 1,400 |
| Product overview | 800 | 560 |
| Product architecture | 1,200 | 840 |
| Product API summary | 1,000 | 700 |
| Product integration | 800 | 560 |
| Operational guide | 4,000 | 2,800 |
| Agent profile | 2,000 | 1,400 |
| Index/navigation | 400 | 280 |

## Procedure

### 1. Identify Target Files

If a specific file is provided, check that file. Otherwise, scan the directory:

```bash
find . -name "*.md" -type f | head -20
```

### 2. Calculate Token Estimate

For each file, estimate tokens (words × 1.4):

```bash
file="path/to/file.md"
words=$(wc -w < "$file" | tr -d ' ')
tokens=$((words * 14 / 10))
echo "$file: ~$tokens tokens ($words words)"
```

### 3. Determine Document Type

Infer type from:
- Filename: `SKILL.md` → skill, `00-overview.md` → overview
- Path: `02-products/` → product doc, `03-ai-enabling/02-profiles/` → agent profile
- Frontmatter: `doc_type` field if present

### 4. Compare Against Budget

| Status | Condition | Action |
|--------|-----------|--------|
| OK | Under budget | Report as compliant |
| WARNING | 80-100% of budget | Suggest review |
| OVER | Exceeds budget | Analyze and suggest cuts |

### 5. If Over Budget, Analyze Content

Identify optimization opportunities:
- Prose that could be tables (30-50% savings)
- Redundant explanations
- Examples that could be shortened
- Content that belongs in linked docs

## Output Format

```markdown
## Token Budget Report

### Summary
- Files checked: N
- Compliant: N
- Warnings: N
- Over budget: N

### Details

| File | Type | Tokens | Budget | Status |
|------|------|--------|--------|--------|
| path/to/file.md | skill | 1,850 | 2,000 | OK |
| path/to/doc.md | overview | 950 | 800 | OVER (+150) |

### Recommendations

#### path/to/doc.md (950 tokens, budget 800)
- Lines 45-60: Convert feature list to table (-80 tokens)
- Lines 72-85: Remove redundant introduction (-50 tokens)
```

## Efficiency Patterns Reference

| Pattern | Token Savings |
|---------|---------------|
| Tables over prose | 30-50% |
| Bullet points over paragraphs | 20-30% |
| Omit articles in table cells | 5-10% |
| Use abbreviations (env, config, auth) | 5-10% |
| Remove redundant headers | 5-10% |