claude-md-optimizer
Skill2 starsChanged 9 months agoMITView on GitHub
Optimize CLAUDE.md using Addy Osmani's agents-md methodology: remove agent-discoverable information, add gotchas and landmines. CLAUDE.md에서 코드로 발견 가능한 정보를 제거하고 gotcha/landmine을 추가. Use when the user says 'optimize CLAUDE.md', 'streamline CLAUDE.md', 'agents-md', 'discoverability filter', 'add gotchas', 'CLAUDE.md 최적화', 'CLAUDE.md 줄이기', 'CLAUDE.md 다이어트'.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- yht-4403/jc-agent-skillstheir own version, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- yht-4403/jc-agent-skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- wrap-upSkill
- dd-configSkill
- dd-doctorSkill
- dd-feedbackSkill
- dd-helpSkill
- dd-pack-createSkill
- dd-setupSkill
- dd-soundsSkill
- dd-testSkill
- dd-tts-packSkill
- dd-uninstallSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
If --help is present, display available flags and a brief description of the 4-step workflow, then stop.
- Distinctive: line 30
Read the target CLAUDE.md.
- Very specific: line 62
If --report-only, stop here.
- Distinctive: line 92
Use AskUserQuestion to confirm before modifying:
- Very specific: line 106
If --dry-run, show the diff but do not write.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md Optimizer
Optimize CLAUDE.md files by applying the discoverability filter: remove information agents can discover from code, keep only non-discoverable operational knowledge (gotchas, landmines, non-standard conventions), and mine source code for undocumented gotchas.
Research shows redundant context (directory trees, data flow diagrams) degrades agent performance by 15-20%, while human-authored operational knowledge reduces runtime by ~28%.
Flag Parsing
Parse $ARGUMENTS for optional flags:
| Flag | Effect |
--dry-run | Analyze and show diff without modifying the file |
--report-only | Output statistics and classification table only |
--path <path> | Target CLAUDE.md path (default: ./CLAUDE.md) |
--help | Display usage and exit |
If --help is present, display available flags and a brief description of the 4-step workflow, then stop.
Workflow
Step 1: Baseline Analysis
Read the target CLAUDE.md. Collect line statistics:
node .claude/skills/claude-md-optimizer/scripts/line-count.mjs '<TARGET_PATH>'Classify each ##/### section into one of three categories:
| Category | Meaning | Action |
discoverable | Agent can find this via Glob/Grep/Read within 10 seconds | Remove |
operational | Non-discoverable, operationally significant | Keep |
verbose | Operational knowledge but overly detailed | Compress |
To classify, actually read the source files referenced in each section. Verify whether the information is truly discoverable. Detailed classification criteria are in references/methodology.md.
Present results as a table:
## Baseline Analysis — <filename>
Total: XXX lines (YY sections)
| Section | Lines | Category | Rationale |
|---------|-------|----------|-----------|
| Directory Structure | 63 | discoverable | Glob **/* reveals this instantly |
| Design Rules | 8 | operational | Non-standard constraints, not in code |
| Config & State | 24 | verbose | Operational but compressible to ~6 lines |
Removal candidates: XX lines (XX%)If --report-only, stop here.
Step 2: Gotcha Mining
Scan project source code to find non-obvious operational knowledge missing from CLAUDE.md. Use the systematic checklist in references/gotcha-mining.md.
Key Grep patterns to run on the codebase:
MUST|WARNING|HACK|TODO|FIXME → developer-flagged gotchas
catch.*exit\(0\)|process\.exit → error exit policies
setTimeout|setInterval|deadline → timing constraints
=== null|== null|delete result → implicit semantics
process\.platform|/proc/version → platform detection quirks
cooldown|throttle|lastNotified → rate limiting scopePresent findings:
## Discovered Gotchas
| # | Category | Description | Source | Already in CLAUDE.md? |
|---|----------|-------------|--------|-----------------------|
| 1 | Timing | 5s→4s→2s budget | _common.mjs:21,52 | No → Add |
| 2 | Implicit | null = key deletion | config.mjs:157 | No → Add |Step 3: Generate Optimized CLAUDE.md
Use AskUserQuestion to confirm before modifying:
Based on the analysis:
- Remove: X lines of discoverable content (Y sections)
- Compress: X lines → ~Y lines (Z sections)
- Add: X new gotcha items
Options:
- Apply all — Remove discoverable, compress verbose, add gotchas
- Item by item — Review each change individually
- Cancel — No changes
Apply the selected changes using Edit (prefer surgical edits over full rewrite).
If --dry-run, show the diff but do not write.
Structure for optimized CLAUDE.md (recommended section order):
- Project description (1-2 lines)
- Development Commands
- Design Rules (non-negotiable constraints)
- Gotchas & Landmines (categorized subsections)
- Conventions (non-standard project patterns)
- Version/Release Management
- Testing
Detailed anti-pattern examples with before/after are in references/anti-patterns.md.
Step 4: Verification
Re-run statistics and present before/after comparison:
node .claude/skills/claude-md-optimizer/scripts/line-count.mjs '<TARGET_PATH>'## Optimization Results
| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Total lines | 182 | 90 | -51% |
| Discoverable lines | 80 | 0 | Removed |
| Operational lines | 60 | 55 | Kept |
| Gotcha items | 0 | 25 | Added |
Discoverability filter: all remaining lines pass "not discoverable from code" check.Reference Files
references/methodology.md— Discoverability filter decision tree, category classification criteria, compression techniques, efficiency research datareferences/anti-patterns.md— 6 anti-pattern catalog with real before/after examples from dding-dong (182→90 lines)references/gotcha-mining.md— 8-category mining checklist with Grep patterns and source code analysis techniques
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

