{
  "markdown": "# please-optimize-my-claude\n\n> Optimize your CLAUDE.md hierarchy — deduplicate content, detect misplacement, compress bloat, and visualize token usage across global/project/repo levels.\n\n[![CI](https://github.com/thedoublejay/please-optimize-my-claude/actions/workflows/ci.yml/badge.svg)](https://github.com/thedoublejay/please-optimize-my-claude/actions/workflows/ci.yml)\n[![Latest Release](https://img.shields.io/github/v/release/thedoublejay/please-optimize-my-claude)](https://github.com/thedoublejay/please-optimize-my-claude/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n---\n\n## The Problem\n\nEvery word in your CLAUDE.md files is injected into every Claude request — silently, on every keystroke.\n\nMost 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:\n\n```text\n~/.claude/CLAUDE.md          ← loaded in EVERY project, for EVERY organization you work in\n  org-a/\n  ├── CLAUDE.md              ← loaded for all repos in org-a\n  ├── repo-a/CLAUDE.md       ← loaded when working in repo-a\n  ├── repo-b/CLAUDE.md\n  ├── repo-c/CLAUDE.md\n  └── repo-d/CLAUDE.md\n  org-b/\n  ├── CLAUDE.md              ← different org, different conventions\n  ├── api/CLAUDE.md\n  └── frontend/CLAUDE.md\n```\n\n**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.\n\n**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.\n\nNo tool analyzes the full hierarchy and helps you fix it. This skill does.\n\n---\n\n## Why This Skill?\n\n### Key Features\n\n- **Full discovery** — maps every CLAUDE.md, CLAUDE.local.md, `.claude/rules/`, and `@import` reference across all levels\n- **Cross-level deduplication** — detects duplicates across hierarchy levels and keeps content at the right one\n- **\"What Claude Sees\" simulator** — shows tokens loaded per directory, including conditional rules\n- **Visual token reports** — Unicode bar charts with before/after comparison\n- **Misplacement detection** — finds organization-specific content in global, repo-specific content in root, and generic content buried in repo files\n- **Security scan** — detects accidentally committed secrets, API keys, internal URLs, credentials, and PII; flags with line numbers and suggests safe replacements\n- **Contradiction detection** — catches conflicting instructions with confidence levels (\"Definite conflict\" vs \"Possible tension\"), respects path-scoped rules\n- **Stale content check** — uses git blame and package.json script verification to find outdated sections\n- **Migration mode** — helps split a monolithic CLAUDE.md into a proper hierarchy\n- **Auto-generate repo index** — creates a directory map in your root CLAUDE.md for quick navigation\n- **Three modes** — interactive (guided review), auto (apply all), analyze (report only)\n- **Backup & restore** — reversible changes with scope-matched backups (`~/.claude/backups/` for global, `.claude-md-backup/` for project)\n- **Live best practices research** — optionally fetch the latest CLAUDE.md recommendations from the web\n\n---\n\n## Quick Start\n\nInstall via [skills.sh](https://skills.sh) marketplace:\n\n```bash\nnpx skills add thedoublejay/please-optimize-my-claude\n```\n\n> **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.\n\nThen run from any project directory:\n\n```bash\n/please-optimize-my-claude\n```\n\n---\n\n## Usage\n\n| Command | Mode | Behavior |\n|---------|------|----------|\n| `/please-optimize-my-claude` | Interactive (default) | Walk through findings with summary-then-batch approach |\n| `/please-optimize-my-claude auto` | Auto | Apply all optimizations automatically (prompts for backup first) |\n| `/please-optimize-my-claude analyze` | Analyze | Report only — no files modified |\n| `/please-optimize-my-claude restore` | Restore | Undo all changes from latest `.claude-md-backup/` |\n| Any mode + `--research` | Live research | Also fetch latest best practices from web before analyzing |\n\n### Examples\n\n```bash\n# Just see what's wrong — no changes\n/please-optimize-my-claude analyze\n\n# Interactive: review findings and decide what to apply\n/please-optimize-my-claude\n\n# Auto-apply everything with backup\n/please-optimize-my-claude auto\n\n# Undo last optimization\n/please-optimize-my-claude restore\n\n# Include live research from Anthropic docs\n/please-optimize-my-claude analyze --research\n```\n\n---\n\n## How It Works\n\nThe skill runs a 5-phase pipeline:\n\n1. **Discovery** — finds all CLAUDE.md, CLAUDE.local.md, `.claude/rules/`, and `@import` references. Resolves symlinks. Strips HTML comments. Counts tokens (word count × 1.5).\n2. **Analysis** — runs 9 detectors: duplication, misplacement, bloat, stale content, contradictions, token budget audit, best practices comparison, missing index detection, security scan.\n3. **Visual Report** — outputs a Unicode-rich terminal report with hierarchy tree, freshness scores, token bar charts, and \"What Claude Sees\" per working directory.\n4. **Apply** — in interactive mode: summary-then-batch approach. In auto mode: backup first, then apply all. In analyze mode: report only.\n5. **Before/After Comparison** — re-counts tokens post-optimization, shows savings as percentages.\n\n---\n\n## Visual Report Examples\n\n### Hierarchy Tree\n\n```text\n📁 Instruction Surface\n──────────────────────\n~/.claude/CLAUDE.md (global)\n~/.claude/rules/ (global rules)\n│   └── 2 rule files\n└── ./CLAUDE.md (project root)\n    ├── .claude/rules/ (project rules)\n    │   └── 1 rule file (path-scoped: src/**)\n    ├── ./api/CLAUDE.md\n    ├── ./auth/CLAUDE.md\n    ├── ./frontend/CLAUDE.md\n    │   └── CLAUDE.local.md (personal, not committed)\n    ├── 3 @import references resolved\n    └── 9 repos without CLAUDE.md ⚠️\n```\n\n### Freshness via git blame\n\n```text\n📅 CLAUDE.md Freshness\n──────────────────────\nGlobal          last modified 3 days ago\nRoot            last modified 45 days ago  ⚠️ review recommended\napi             last modified 12 days ago\nfrontend        last modified 2 days ago\n```\n\n### Token Usage Bar Chart\n\n```text\n📊 Token Usage Per File\n───────────────────────\nGlobal          ████░░░░░░░░░░░░░░░░   920 tokens  (budget: 1,000) ✅\nRoot            ████████████████░░░░ 4,200 tokens  (budget: 3,000) ⚠️ OVER\napi             ███████████████░░░░░ 3,800 tokens  (budget: 2,500) ⚠️ OVER\n```\n\n### \"What Claude Sees\" Simulator\n\n```text\n📈 Tokens Loaded Per Working Directory\n──────────────────────────────────────\nWorking in ./api/          → 8,920 tokens (CLAUDE.md: 7,400 + rules: 1,200 + local: 320)\nWorking in ./auth/         → 8,520 tokens (CLAUDE.md: 7,800 + rules: 720)\nWorking in root ./         → 5,120 tokens (CLAUDE.md: 4,200 + rules: 920)\n\n  Includes: global + root + repo CLAUDE.md, CLAUDE.local.md, unconditional rules\n  Path-scoped rules shown separately (load only when matching files are read)\n```\n\n### Before/After Comparison\n\n```text\n╔══════════════════════════════════════════════════════════════╗\n║              ✅ Optimization Complete                        ║\n╠══════════════════════════════════════════════════════════════╣\n\n📊 Before vs After\n──────────────────\n                    BEFORE          AFTER           SAVED\nGlobal              ████  920    →  ███  720     →  -200 (22%)\nRoot                ████████ 4,200 → █████ 2,800 → -1,400 (33%)\napi                 ███████ 3,800  → ████ 2,100  → -1,700 (45%)\n─────────────────────────────────────────────────────────────\nTOTAL               14,820         → 10,520       → -4,300 (29%)\n```\n\n---\n\n## Sample Report\n\nA complete example run against a synthetic 4-repo \"Mavs Org\" organization — showing the full analysis output, issue breakdown, and before/after token savings.\n\n→ [examples/sample-report.md](examples/sample-report.md)\n\n---\n\n## Token Budgets\n\n| Level | Budget | Rationale |\n|-------|--------|-----------|\n| Global (`~/.claude/CLAUDE.md`) | < 1,000 tokens | Loaded in EVERY project. Must be lean. |\n| Project root (`./CLAUDE.md`) | < 3,000 tokens | Loaded for all work in this project. |\n| Subdirectory (`<repo>/CLAUDE.md`) | < 2,500 tokens | Loaded when working in that directory. |\n\nToken estimate: word count × 1.5 (HTML comments not counted — Claude Code strips them before injection).\n\n---\n\n## Compatibility\n\nThis 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.\n\n| Feature | Claude Code | Other Agents |\n|---------|-------------|--------------|\n| SKILL.md execution | Full support | Varies by agent |\n| `AskUserQuestion` tool | Supported | May not be available — interactive mode may not work |\n| `WebSearch` / `WebFetch` tools | Supported | May not be available — `--research` flag may not work |\n| `$ARGUMENTS` | Supported | May not be available |\n| CLAUDE.md hierarchy concept | Native | Agent may not use CLAUDE.md at all |\n\n**Recommendation:** Use this skill with Claude Code. If you use it with another agent, `analyze` mode works best — read-only, no interactive prompts.\n\n---\n\n## Edge Cases\n\n| Scenario | Behavior |\n|----------|----------|\n| No CLAUDE.md files found | Shows message and exits gracefully |\n| Only global exists | Reports global stats, suggests creating project-level file |\n| Git not initialized | Skips stale content check and freshness scoring |\n| Large monorepo (50+ files) | Processes all files, shows progress, groups issues by type |\n| File is empty | Flags as `[EMPTY]` in report |\n| Symlinked CLAUDE.md | Resolves to canonical path, warns before modifying |\n| `@import` references | Resolves up to 5 levels deep, tracks effective token count |\n| `.claude/rules/` with `paths:` frontmatter | Marks as \"conditional\" in token simulator |\n| CLAUDE.local.md present | Included in analysis, noted as personal/gitignored |\n| Backup directory conflict | Always uses ISO timestamp — guaranteed unique |\n| No backup found for restore | Shows message: \"No backup found. Nothing to restore.\" |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on making changes, commit conventions, and the PR process.\n\nIssues: [github.com/thedoublejay/please-optimize-my-claude/issues](https://github.com/thedoublejay/please-optimize-my-claude/issues)\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\n## Support\n\nIf this skill saves you tokens, Claude credits donations are always welcome — they go straight into running more `/please-optimize-my-claude` sessions.\n\nThis skill is provided **as-is**, with no warranty. See [LICENSE](LICENSE) for details.\n\n---\n\nCreated by JJ Adonis — Powered by Claude\n",
  "bytes": 11333,
  "sha": "b9d292e5e53e0cda7b5aa8da98c74e051b6942246293d1be039787ab4b9ec1bd",
  "repo_slug": "thedoublejay/please-optimize-my-claude",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_thedoublejay_please_optimize_my_claude_p_8d13664e/readme"
}