| name | Optimize Claude.md |
| description | This skill should be used when the user says "optimize claude.md", "claude.md is too big", "shrink claude.md", "claude.md taking too many tokens", "trim claude.md", "rewrite claude.md", or "my claude.md is bloated". |
| version | 1.0.0 |
Optimize Claude.md
Read, analyze, and rewrite claude.md (or CLAUDE.md) to reduce token cost while preserving all meaningful constraints. Target: under 300 tokens.
Step 1: Find and Read the File
Check these locations in order:
./CLAUDE.md (project root)
./claude.md
~/.claude/CLAUDE.md (global)
~/.claude/claude.md
Read the file. Count approximate word count.
Step 2: Analyze Content
Categorize each section:
| Category | Keep? | Action |
|---|
| Coding style rules | Yes | Compress to bullets |
| Project structure | Yes | One-line per item |
| Important constraints | Yes | Keep verbatim |
| Pleasantries / tone instructions | Maybe | Cut if not essential |
| Repeated instructions | No | Remove duplicates |
| Obvious defaults | No | Remove ("always use git" etc.) |
| Long explanations | No | Replace with one-line rule |
| Examples longer than 3 lines | No | Remove or move to references/ |
Step 3: Rewrite
Apply these compression rules:
- Bullets over prose — Replace paragraphs with bullet lists
- Imperative tense — "Use TypeScript strict mode" not "You should use TypeScript strict mode"
- No justifications — Remove "because X" explanations
- Merge related rules — Combine similar rules into one line
- Cut obvious defaults — Remove anything Claude does by default anyway
Target structure:
# Project: [NAME]
Stack: [tech stack, one line]
## Code Style
- [rule 1]
- [rule 2]
## Constraints
- [hard constraint 1]
- [hard constraint 2]
## Structure
- [key path 1]: [purpose]
- [key path 2]: [purpose]
Step 4: Show Diff and Confirm
Present:
BEFORE: ~[N] words (~[N*1.3] tokens)
AFTER: ~[N] words (~[N*1.3] tokens)
Reduction: [%]%
Show the optimized version. Ask user to confirm before writing.
Step 5: Write File
On confirmation, overwrite the file with the optimized version.
Additional Resources
references/claudemd-templates.md — Optimized claude.md templates for common project types