token-budget-check

name	token-budget-check
description	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.
version	1.0.0
allowed-tools	["Read","Bash","Glob"]
tags	["tokens","documentation","budget","validation","knowledge-copilot"]

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:

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

2. Calculate Token Estimate

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

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

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