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

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

# Undo last optimization
/please-optimize-my-claude restore

# Include live research from Anthropic docs
/please-optimize-my-claude analyze --research

How It Works

The skill runs a 5-phase pipeline:

1. Discovery — finds all CLAUDE.md, CLAUDE.local.md, .claude/rules/, and @import references. Resolves symlinks. Strips HTML comments. Counts tokens (word count × 1.5).
2. Analysis — runs 9 detectors: duplication, misplacement, bloat, stale content, contradictions, token budget audit, best practices comparison, missing index detection, security scan.
3. Visual Report — outputs a Unicode-rich terminal report with hierarchy tree, freshness scores, token bar charts, and "What Claude Sees" per working directory.
4. Apply — in interactive mode: summary-then-batch approach. In auto mode: backup first, then apply all. In analyze mode: report only.
5. Before/After Comparison — re-counts tokens post-optimization, shows savings as percentages.

Visual Report Examples

Hierarchy Tree

📁 Instruction Surface
──────────────────────
~/.claude/CLAUDE.md (global)
~/.claude/rules/ (global rules)
│   └── 2 rule files
└── ./CLAUDE.md (project root)
    ├── .claude/rules/ (project rules)
    │   └── 1 rule file (path-scoped: src/**)
    ├── ./api/CLAUDE.md
    ├── ./auth/CLAUDE.md
    ├── ./frontend/CLAUDE.md
    │   └── CLAUDE.local.md (personal, not committed)
    ├── 3 @import references resolved
    └── 9 repos without CLAUDE.md ⚠️

Freshness via git blame

📅 CLAUDE.md Freshness
──────────────────────
Global          last modified 3 days ago
Root            last modified 45 days ago  ⚠️ review recommended
api             last modified 12 days ago
frontend        last modified 2 days ago

Token Usage Bar Chart

📊 Token Usage Per File
───────────────────────
Global          ████░░░░░░░░░░░░░░░░   920 tokens  (budget: 1,000) ✅
Root            ████████████████░░░░ 4,200 tokens  (budget: 3,000) ⚠️ OVER
api             ███████████████░░░░░ 3,800 tokens  (budget: 2,500) ⚠️ OVER

"What Claude Sees" Simulator

📈 Tokens Loaded Per Working Directory
──────────────────────────────────────
Working in ./api/          → 8,920 tokens (CLAUDE.md: 7,400 + rules: 1,200 + local: 320)
Working in ./auth/         → 8,520 tokens (CLAUDE.md: 7,800 + rules: 720)
Working in root ./         → 5,120 tokens (CLAUDE.md: 4,200 + rules: 920)

  Includes: global + root + repo CLAUDE.md, CLAUDE.local.md, unconditional rules
  Path-scoped rules shown separately (load only when matching files are read)

Before/After Comparison

╔══════════════════════════════════════════════════════════════╗
║              ✅ Optimization Complete                        ║
╠══════════════════════════════════════════════════════════════╣

📊 Before vs After
──────────────────
                    BEFORE          AFTER           SAVED
Global              ████  920    →  ███  720     →  -200 (22%)
Root                ████████ 4,200 → █████ 2,800 → -1,400 (33%)
api                 ███████ 3,800  → ████ 2,100  → -1,700 (45%)
─────────────────────────────────────────────────────────────
TOTAL               14,820         → 10,520       → -4,300 (29%)

Sample Report

A complete example run against a synthetic 4-repo "Mavs Org" organization — showing the full analysis output, issue breakdown, and before/after token savings.

→ examples/sample-report.md

Token Budgets

Token estimate: word count × 1.5 (HTML comments not counted — Claude Code strips them before injection).

Compatibility

This skill is designed for and tested with Claude Code. CLAUDE.md is a Claude Code convention — the hierarchical file discovery, CLAUDE.local.md, .claude/rules/, and @import syntax are all Claude Code features.

Recommendation: Use this skill with Claude Code. If you use it with another agent, analyze mode works best — read-only, no interactive prompts.

Edge Cases

Contributing

See CONTRIBUTING.md for guidelines on making changes, commit conventions, and the PR process.

Issues: github.com/thedoublejay/please-optimize-my-claude/issues

License

MIT — see LICENSE

Support

If this skill saves you tokens, Claude credits donations are always welcome — they go straight into running more /please-optimize-my-claude sessions.

This skill is provided as-is, with no warranty. See LICENSE for details.

Created by JJ Adonis — Powered by Claude