{"id":50422391,"url":"https://github.com/rock070/claude-docs-diagnose","last_synced_at":"2026-05-31T09:01:21.877Z","repository":{"id":354816671,"uuid":"1225341558","full_name":"Rock070/claude-docs-diagnose","owner":"Rock070","description":"Claude Code skill that audits, writes, and prunes CLAUDE.md files using a 3-phase + parallel-subagent pattern (token-aware, docu-optimize style).","archived":false,"fork":false,"pushed_at":"2026-04-30T08:26:29.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T09:23:07.333Z","etag":null,"topics":["ai-agents","anthropic","claude-code","claude-md","skill"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rock070.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-30T07:19:48.000Z","updated_at":"2026-04-30T08:26:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Rock070/claude-docs-diagnose","commit_stats":null,"previous_names":["rock070/claude-docs-diagnose"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Rock070/claude-docs-diagnose","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rock070%2Fclaude-docs-diagnose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rock070%2Fclaude-docs-diagnose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rock070%2Fclaude-docs-diagnose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rock070%2Fclaude-docs-diagnose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rock070","download_url":"https://codeload.github.com/Rock070/claude-docs-diagnose/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rock070%2Fclaude-docs-diagnose/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33725060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","anthropic","claude-code","claude-md","skill"],"created_at":"2026-05-31T09:01:20.545Z","updated_at":"2026-05-31T09:01:21.871Z","avatar_url":"https://github.com/Rock070.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-docs-diagnose\n\nA Claude Code skill that audits, writes, and maintains `CLAUDE.md` files using battle-tested patterns from Anthropic (Boris Cherny, Thariq Shihipar), Addy Osmani, termdock, and the ETH Zurich / Lulla et al. (ICSE JAWs 2026) empirical studies.\n\n## Why\n\n\u003e ETH Zurich found that auto-generated `AGENTS.md` files **decreased** task success by 2–3% and increased reasoning cost by 20%+. Hand-written files only improved success by ~4% — and still cost 19% more tokens.\n\nMost `CLAUDE.md` files are too long, too redundant, and too prescriptive. Every bad line competes with the user's actual task for the model's attention. This skill encodes the rules for writing instruction files that **earn their token cost**.\n\n## What it does\n\nWhen triggered, the skill:\n\n- Audits your existing `CLAUDE.md` against a 16-point anti-pattern checklist.\n- Suggests cuts (every line that Claude could have discovered on its own).\n- Reorders content for prompt-cache friendliness (static on top, dynamic at the bottom).\n- Recommends a modular `.claude/rules/` split if the file exceeds ~3k tokens.\n- Generates a fresh `CLAUDE.md` for projects that don't have one (in `create` mode).\n\n## How it runs (token-aware)\n\nThe skill runs in three phases:\n\n1. **Phase 1 — Discovery (sequential):** the main agent inventories your `CLAUDE.md` hierarchy, `.claude/` ecosystem, `docs/` tree, and `MEMORY.md`.\n2. **Phase 2 — Parallel analysis (3 subagents, single message):** three `Task`-spawned subagents work in parallel, each focused on a slice of the 16 anti-patterns. Subagents are **read-only** — their long tool output never enters the main context, keeping token cost low.\n3. **Phase 3 — Synthesis (sequential):** the main agent collects the subagent reports and produces the user-facing audit (and an optimized draft, in `optimize` / `apply` mode).\n\nDetailed anti-pattern explanations live in `claude-docs-diagnose/skills/claude-docs-diagnose/references/anti-patterns.md` and are loaded only by the subagent that needs them — never inlined into the main `SKILL.md`.\n\n## Install\n\nThis repo is a [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Install the plugin from inside Claude Code:\n\n```text\n/plugin marketplace add Rock070/claude-docs-diagnose\n/plugin install claude-docs-diagnose@claude-docs-diagnose\n```\n\nThat's it. After install, test it with:\n\n\u003e \"Audit my CLAUDE.md.\"\n\n### Updating\n\n```text\n/plugin marketplace update claude-docs-diagnose\n```\n\n### Uninstalling\n\n```text\n/plugin uninstall claude-docs-diagnose@claude-docs-diagnose\n```\n\n## Usage\n\nOnce installed, trigger the skill by asking Claude any of:\n\n- \"Audit my CLAUDE.md.\"\n- \"Write a CLAUDE.md for this repo.\"\n- \"My CLAUDE.md is 600 lines, help me prune it.\"\n- \"Split this CLAUDE.md into modular rules.\"\n- \"Is my CLAUDE.md too long?\"\n\nYou can also invoke it explicitly via `/claude-docs-diagnose:claude-docs-diagnose`.\n\n### Modes\n\n- **analyze** (default) — report only, no writes.\n- **audit** — full ecosystem audit including `.claude/` and `MEMORY.md`.\n- **optimize** — analyze + produce an optimized `CLAUDE.md` draft (do not apply).\n- **apply** — analyze + write the optimized version directly to `CLAUDE.md` (confirms first).\n- **create** — generate a fresh `CLAUDE.md` from project structure when none exists.\n- **prune** — drop redundant lines from an existing `CLAUDE.md` without restructuring.\n\n## What's in this repo\n\n| Path | Purpose |\n|---|---|\n| `.claude-plugin/marketplace.json` | Marketplace manifest — declares this repo as a Claude Code plugin marketplace |\n| `claude-docs-diagnose/.claude-plugin/plugin.json` | Plugin manifest — version, license, and skill discovery path |\n| `claude-docs-diagnose/skills/claude-docs-diagnose/SKILL.md` | The skill itself — frontmatter + 3-phase orchestration (~180 lines) |\n| `claude-docs-diagnose/skills/claude-docs-diagnose/references/anti-patterns.md` | Detailed 16-mistake catalog, loaded on demand by Phase 2 subagents |\n| `claude-docs-diagnose/skills/claude-docs-diagnose/references/recommended-template.md` | Recommended `CLAUDE.md` template + cheatsheet, loaded in `optimize`/`apply`/`create` modes |\n| `claude-docs-diagnose/skills/claude-docs-diagnose/references/claude-best-practices.md` | Anthropic's official best-practices doc (English) |\n| `claude-docs-diagnose/skills/claude-docs-diagnose/references/agents-md.md` | Addy Osmani's `AGENTS.md` research roundup (English) |\n| `claude-docs-diagnose/skills/claude-docs-diagnose/references/claude-md-common-mistakes.md` | termdock's 10-mistake write-up (English) |\n| `LICENSE` | MIT |\n| `README.md` | This file |\n\n## The 16-point checklist (summary)\n\nGrouped by the Phase 2 subagent that owns the check.\n\n**Subagent A — Size, cache order, and core hygiene**\n\n| # | Mistake |\n|---|---|\n| 1 | Context Stuffing |\n| 2 | Static Learnings |\n| 3 | Missing Plan Mode guidance |\n| 4 | Weak Verification |\n| 5 | Undocumented Permissions (team) |\n| 6 | No Format Standards |\n| 11 | Cache-Hostile Ordering |\n\n**Subagent B — Documentation sync and `docs/` health**\n\n| # | Mistake |\n|---|---|\n| 7 | Stale Documentation |\n| 8 | Missing `docs/` Index |\n| 9 | Orphan Docs |\n| 10 | Code-Doc Drift |\n\n**Subagent C — Modularity, emphasis, memory**\n\n| # | Mistake |\n|---|---|\n| 12 | Instruction Overload (\u003e150) |\n| 13 | Missing Modular Rules |\n| 14 | No Feedback Loop |\n| 15 | Critical Rules Not Emphasized |\n| 16 | `MEMORY.md` Truncation |\n\nFull table with symptoms and fixes lives in `claude-docs-diagnose/skills/claude-docs-diagnose/references/anti-patterns.md`.\n\n## Target metrics\n\n- **Ideal `CLAUDE.md` size:** ~2.5k tokens (~100–150 lines)\n- **Maximum recommended:** 4k tokens\n- **Warning threshold:** 5k+ tokens (causes context rot)\n- **Instruction cap:** ≤ 150 imperative rules across `CLAUDE.md` + `.claude/rules/`\n\n## References\n\n- [Anthropic — Claude Code Best Practices](https://code.claude.com/docs/en/best-practices)\n- [Addy Osmani — AGENTS.md as a living list of code smells](https://addyosmani.com/blog/agents-md/)\n- [termdock — 10 common CLAUDE.md mistakes](https://www.termdock.com/zh/blog/claude-md-common-mistakes)\n- [Lulla et al. — ICSE JAWs 2026 paired experiment](https://arxiv.org/abs/2601.20404)\n- [ETH Zurich — Evaluating AGENTS.md (Gloaguen, Mündler, Müller, Raychev, Vechev)](https://arxiv.org/abs/2602.11988)\n\n## Contributing\n\nIssues and pull requests welcome. If you find a `CLAUDE.md` anti-pattern not covered by the 16-point checklist, open an issue with a concrete example.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frock070%2Fclaude-docs-diagnose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frock070%2Fclaude-docs-diagnose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frock070%2Fclaude-docs-diagnose/lists"}