AgentSkillsCN

claude-md-doctor

审计并改进 CLAUDE.md 文件。当规则失效、上下文过于冗长，或在汲取经验教训并将其转化为新规则后，可使用此功能。

SKILL.md
--- frontmatter
name: claude-md-doctor
description: Audit and improve CLAUDE.md files. Use when rules aren't working, context is bloated, or after learning a lesson that should become a rule.
disable-model-invocation: true

CLAUDE.md Doctor

Audit, diagnose, and improve CLAUDE.md files for this project.

Usage

  • •/claude-md-doctor or /claude-md-doctor audit — Full audit of all CLAUDE.md files
  • •/claude-md-doctor add-rule <description> — Add a new rule based on a lesson learned

Audit Procedure

When invoked with audit or no arguments:

Step 1: Discover All CLAUDE.md Files

Search for CLAUDE.md files at all levels:

  • •Project root: ./CLAUDE.md
  • •Subdirectories: ./**/CLAUDE.md
  • •User-level: ~/.claude/CLAUDE.md

Report which files exist and their line counts.

Step 2: Check Structure Against Best Practices

A well-structured CLAUDE.md should have these sections (in order of importance):

  1. •What — Project architecture overview (what this project IS)
  2. •Domain — Tech stack, key dependencies, language/framework conventions
  3. •Validation — Build, test, and lint commands (the verification loop)
  4. •Critical Rules — Never/always rules that prevent recurring mistakes

Check for each section. Report missing sections as warnings.

Step 3: Analyze Health Metrics

  • •Line count: Warn if >200 lines (bloat risk — Claude loads this into every context)
  • •Duplicate rules: Flag rules that say the same thing in different words
  • •Stale references: Flag mentions of files/paths that don't exist
  • •Vague rules: Flag rules without concrete actions (e.g., "write clean code" — too vague)
  • •Missing validation loop: Critical warning if no build/test/lint commands are defined

Step 4: Check Git Status

Run git status CLAUDE.md to check if the file is:

  • •Tracked and committed (good)
  • •Modified but uncommitted (warn: team won't see changes)
  • •Untracked (warn: not shared with team)

Step 5: Generate Report

Output a structured report:

code
## CLAUDE.md Health Report

### Files Found
- ./CLAUDE.md (N lines) [committed/uncommitted/untracked]
- ./src/CLAUDE.md (N lines) [committed/uncommitted/untracked]

### Section Coverage
- [x] What (architecture)
- [ ] Domain (tech stack) — MISSING
- [x] Validation (build/test/lint)
- [ ] Critical Rules — MISSING

### Warnings
- Line count: N (target: <200)
- Duplicate rules found: ...
- Stale path references: ...

### Recommendations
1. Add a "Domain" section describing...
2. Add a "Critical Rules" section with...

Add Rule Procedure

When invoked with add-rule <description>:

Step 1: Parse the Lesson

Read the $ARGUMENTS after add-rule to understand what lesson was learned.

Step 2: Formulate the Rule

Convert the lesson into a concrete, actionable rule:

  • •Start with "Always" or "Never"
  • •Be specific (mention files, commands, patterns)
  • •Include the WHY (so future Claude instances understand the reason)

Example: "Never use rm -rf on the build directory — use make clean instead, which preserves the cache"

Step 3: Add to CLAUDE.md

  • •If a "Critical Rules" section exists, append the rule there
  • •If not, create the section at the end of the file
  • •Format as a bullet point

Step 4: Confirm

Show the user the exact rule added and its location.