please-optimize-my-claude
Optimize your CLAUDE.md hierarchy — deduplicate content, detect misplacement, compress bloat, and visualize token usage across global/project/repo levels.
The Problem
Every word in your CLAUDE.md files is injected into every Claude request — silently, on every keystroke.
Most developers start with one global ~/.claude/CLAUDE.md. That's fine. But as soon as you work across multiple projects or organizations, the hierarchy grows:
~/.claude/CLAUDE.md ← loaded in EVERY project, for EVERY organization you work in
org-a/
├── CLAUDE.md ← loaded for all repos in org-a
├── repo-a/CLAUDE.md ← loaded when working in repo-a
├── repo-b/CLAUDE.md
├── repo-c/CLAUDE.md
└── repo-d/CLAUDE.md
org-b/
├── CLAUDE.md ← different org, different conventions
├── api/CLAUDE.md
└── frontend/CLAUDE.md
The hidden cost: When working in org-a/repo-a, Claude loads ~/.claude/CLAUDE.md + org-a/CLAUDE.md + org-a/repo-a/CLAUDE.md — all at once, every request. If the same rule appears in all three levels, you're paying for it three times. If your global file has org-specific ticket formats or framework rules that only apply to one project, you're paying for those everywhere.
For a single global CLAUDE.md: Even without a monorepo, your global file loads in every project — personal, work, client. Rules that only make sense for one context (a specific commit format, a framework preference, an internal tool) inflate every other session. This skill identifies exactly what should stay global vs. what belongs in a project-level file.
No tool analyzes the full hierarchy and helps you fix it. This skill does.
Why This Skill?
Key Features
- Full discovery — maps every CLAUDE.md, CLAUDE.local.md,
.claude/rules/, and @import reference across all levels
- Cross-level deduplication — detects duplicates across hierarchy levels and keeps content at the right one
- "What Claude Sees" simulator — shows tokens loaded per directory, including conditional rules
- Visual token reports — Unicode bar charts with before/after comparison
- Misplacement detection — finds organization-specific content in global, repo-specific content in root, and generic content buried in repo files
- Security scan — detects accidentally committed secrets, API keys, internal URLs, credentials, and PII; flags with line numbers and suggests safe replacements
- Contradiction detection — catches conflicting instructions with confidence levels ("Definite conflict" vs "Possible tension"), respects path-scoped rules
- Stale content check — uses git blame and package.json script verification to find outdated sections
- Migration mode — helps split a monolithic CLAUDE.md into a proper hierarchy
- Auto-generate repo index — creates a directory map in your root CLAUDE.md for quick navigation
- Three modes — interactive (guided review), auto (apply all), analyze (report only)
- Backup & restore — reversible changes with scope-matched backups (
~/.claude/backups/ for global, .claude-md-backup/ for project)
- Live best practices research — optionally fetch the latest CLAUDE.md recommendations from the web
Quick Start
Install via skills.sh marketplace:
npx skills add thedoublejay/please-optimize-my-claude
Note: This skill is designed for and tested with Claude Code. The analyze mode works best in other agents; interactive and auto modes may have limited support.
Then run from any project directory:
/please-optimize-my-claude
Usage
| Command | Mode | Behavior |
|---|
/please-optimize-my-claude | Interactive (default) | Walk through findings with summary-then-batch approach |
/please-optimize-my-claude auto | Auto | Apply all optimizations automatically (prompts for backup first) |
/please-optimize-my-claude analyze | Analyze | Report only — no files modified |
/please-optimize-my-claude restore | Restore | Undo all changes from latest .claude-md-backup/ |
Any mode + --research | Live research | Also fetch latest best practices from web before analyzing |
Examples
# Just see what's wrong — no changes
/please-optimize-my-claude analyze
# Interactive: review findings and decide what to apply
/please-optimize-my-claude
# Auto-apply everything with backup
/please-optimize-my-claude auto