our-claude-skills/custom-skills/00-claude-code-setting/code/references/token-optimization.md

Token Optimization Best Practices

Context Window Budget

Total Available: 200,000 tokens

Budget Allocation

Component	Target	Max	Notes
System prompt	~5,000	Fixed	Claude Code internal
CLAUDE.md	2,000	3,000	Under your control
MCP Servers	5,000	10,000	With Tool Search enabled
Skills metadata	500	1,000	Description + frontmatter only
Working space	>140,000	—	Goal: 70%+ available

Why 70%+ Available?

• Complex tasks need context for code, files, conversation
• Long sessions accumulate context
• Safety buffer prevents truncation

MCP Server Optimization

serverInstructions (CRITICAL)

Every MCP server MUST have serverInstructions for Tool Search to work:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-playwright"],
      "serverInstructions": "Browser automation. Use for: SEO audits, screenshots, page analysis. Keywords: browser, page, DOM, screenshot"
    }
  }
}

Pattern: [What it does]. Use for: [use case 1], [use case 2]. Keywords: [keyword1], [keyword2]

Load Strategies

Strategy	When to Use	Example Servers
always	Essential for daily work	Playwright, Notion, Filesystem
lazy	Occasionally needed	GitHub, PostgreSQL, Slack
disable	Rarely used or token-heavy	Zapier (25K+ tokens)

Token Estimates by Server

Server	Approx. Tokens	Strategy
Playwright	13,500	always
Notion	5,000	always
GitHub	18,000	lazy
PostgreSQL	8,000	lazy
Zapier	25,000+	disable
Memory	3,000	lazy
Filesystem	4,000	always

CLAUDE.md Optimization

Size Limits

• Lines: Under 200
• Tokens: Under 3,000 (~2,300 words)

What to Include

1. Role context (1-2 sentences)
2. Output preferences (format, language)
3. Domain standards (brief, essential only)
4. Available commands (reference list)
5. Quality checklist (3-5 items)

What to Exclude

• Self-descriptions ("You are Claude...")
• Information Claude already knows
• Verbose explanations
• Long code examples (use skills instead)
• Duplicate information

Optimal Structure

# Project Context

## Role
[1-2 sentences]

## Preferences
- Output: [format]
- Language: [preference]

## Standards
### Domain 1
- [Key point 1]
- [Key point 2]

## Commands
- /command1: [brief description]
- /command2: [brief description]

## Checklist
- [ ] Item 1
- [ ] Item 2

Session Management

During Work

1. Check context: Run /context before complex tasks
2. Compact early: Run /compact at 70% usage
3. Clear between tasks: Run /clear for unrelated work

Weekly Maintenance

1. Run /doctor for MCP health
2. Review command usage patterns
3. Update CLAUDE.md with new patterns
4. Check for unused extensions

Monthly Audit

1. Run full settings audit
2. Review and prune unused MCP servers
3. Update serverInstructions
4. Check for new optimization opportunities

Quick Diagnostics

High Token Usage Signs

• Slow response times
• Context getting truncated
• Claude "forgetting" earlier context

Common Fixes

Issue	Fix
CLAUDE.md too long	Move details to skills/references
MCP missing instructions	Add serverInstructions
Too many always-loaded MCPs	Switch some to lazy
Unused extensions	Remove or disable

Commands Reference

Command	Purpose
/context	Check current context usage
/compact	Compress context
/clear	Clear conversation
/doctor	Check MCP server health
/settings-audit	Run this skill's audit