please-optimize-my-claude

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