name: claude-md-improver
description: Audit every CLAUDE.md file in a repository against a quality template, identify stale instructions, detect contradictions, flag missing sections, and produce a quality report with targeted improvements. Makes surgical edits rather than rewrites.
triggers:
- /claude-md-improver
- "improve claude.md"
- "audit claude.md"
- "update memory files"
- "claude.md quality check"
- "fix my claude.md"

CLAUDE.md Improver

Purpose

CLAUDE.md files are the persistent memory that shapes how Claude Code behaves in every session. Stale, contradictory, or incomplete CLAUDE.md files cause Claude Code to make incorrect assumptions, follow outdated patterns, or miss critical constraints. This skill finds all CLAUDE.md files in the repository tree, evaluates each against a quality standard, and produces a report with specific, targeted improvements — not wholesale rewrites that discard institutional knowledge.

Phase 1: Discovery

Find every CLAUDE.md file in the repository:

# Find all CLAUDE.md files from the repo root
find . -name "CLAUDE.md" -not -path "*/node_modules/*" -not -path "*/.git/*"

Also check for alternate names:

find . -name ".claude" -type f -not -path "*/node_modules/*"
find . -name "CLAUDE" -not -path "*/node_modules/*"

Record the full path of each file found. Note whether each is:
- Root-level (affects all sessions in this repo)
- Service-level (affects sessions opened in that service directory)
- Global user-level (~/.claude/CLAUDE.md — affects all repos)

Phase 2: Read Each File

Read every discovered CLAUDE.md in full. Do not summarize or skim. For each file, extract:

1. All commands and rules stated
2. All workflow descriptions
3. All references to external files, services, or systems
4. All dates, version numbers, or time-sensitive references
5. All contradictions with other CLAUDE.md files in the same repo

Phase 3: Quality Evaluation

Evaluate each file against this quality template. Score each dimension 1-5.

Dimension 1: Freshness (1-5)

Look for indicators of staleness:
- Dates more than 3 months old attached to "current" or "temporary" instructions
- References to services, APIs, or files that no longer exist in the codebase
- Instructions that contradict what you observe in the actual code
- TODO items that appear to have been completed but not removed
- "Will be reverted for production" notices that have not been reverted

Score 5: All instructions reflect current state of the codebase
Score 3: Some stale references but core instructions are accurate
Score 1: Significant portions describe a state that no longer exists

Dimension 2: Clarity (1-5)

Evaluate whether each instruction can be followed without ambiguity:
- Are rules stated as imperatives ("ALWAYS use X", "NEVER do Y")?
- Do examples accompany abstract rules?
- Are exceptions to rules documented?
- Is the scope of each rule clear (does it apply to all files? One service? One team?)?

Score 5: Every rule is actionable with no interpretation required
Score 3: Most rules are clear but some require judgment
Score 1: Many rules are vague or contradictory

Dimension 3: Completeness (1-5)

Check for missing sections that should be present:

• [ ] Project overview (what is this codebase for?)
• [ ] Tech stack (languages, frameworks, runtime versions)
• [ ] Development workflow (how to run tests, how to run dev server)
• [ ] Branching and commit conventions
• [ ] Critical constraints (DO NOT do X type rules)
• [ ] Architecture notes (patterns to follow, patterns to avoid)
• [ ] Environment setup (required env vars, external dependencies)

Score 5: All applicable sections present and complete
Score 3: Core sections present, some detail missing
Score 1: Only fragments present

Dimension 4: Contradiction Check (1-5)

Compare instructions within the file and across all CLAUDE.md files in the repo:

• Does the root CLAUDE.md contradict a service-level CLAUDE.md?
• Are there conflicting "NEVER" and "ALWAYS" rules for the same action?
• Do different sections give different answers to the same question?
• Has a rule been updated in one place but not others?

Score 5: No contradictions found
Score 3: Minor inconsistencies that would not cause errors in practice
Score 1: Direct contradictions that would cause Claude to behave unpredictably

Dimension 5: Actionability (1-5)

Can Claude Code actually follow these instructions?

• Are file paths absolute or clearly relative to a known root?
• Are commands copy-pasteable and correct for the stated environment?
• Are external references (URLs, issue numbers) still valid?
• Are role-based constraints (NEVER push to main) clearly stated?

Score 5: Every instruction is directly executable
Score 3: Most instructions are clear; some require inference
Score 1: Many instructions cannot be followed without additional context

Phase 4: Produce Quality Report

CLAUDE.MD QUALITY REPORT
Generated: <date>
Files scanned: <count>

=== FILE: /path/to/CLAUDE.md ===
Overall Score: <X>/25

Dimension Scores:
  Freshness:     <X>/5
  Clarity:       <X>/5
  Completeness:  <X>/5
  Contradictions:<X>/5
  Actionability: <X>/5

ISSUES FOUND:

[STALE] Line 34: "TEMPORARY - August 2025" — This testing configuration
  note is 6+ months old. Either revert the described change or remove
  the note if this is now permanent.

[CONTRADICTION] Line 67 vs Line 89: Line 67 says "ALWAYS use INNER JOIN"
  but line 89 says "Use LEFT JOIN for optional relationships." These rules
  apply to the same query context. Clarify which takes precedence.

[MISSING SECTION] No tech stack section. Add versions of Node, TypeScript,
  and the primary framework so Claude does not make incorrect assumptions.

[AMBIGUOUS RULE] Line 102: "Write good tests" — Not actionable. Specify:
  test framework (bun/vitest/jest), test file location convention, and
  minimum coverage expectation.

[DEAD REFERENCE] Line 78 references C:\projects\anshin\old-service\ which
  does not exist in the current repo structure.

RECOMMENDED CHANGES: <count> targeted edits

Phase 5: Targeted Improvements

For each issue, propose a specific edit. Do not rewrite the entire file. Surgical changes only.

Removing Stale Content

Present the stale section and the proposed removal:

PROPOSED REMOVAL (Stale):

CURRENT (lines 34-49):
  ### Current Testing Configuration (TEMPORARY - August 2025)
  The following changes were made to allow testing without proper
  tenant configuration. These MUST be reverted for production...

PROPOSED: Remove this entire section OR update with current status.

Reason: This note is dated August 2025. It is now 2026-03-02.
Either the revert happened and this should be removed, or this
is now permanent and the "TEMPORARY" framing is misleading.

Resolving Contradictions

PROPOSED RESOLUTION (Contradiction):

CONFLICTING RULES:
  Line 67: "ALWAYS use INNER JOIN"
  Line 89: "Use LEFT JOIN for optional relationships"

PROPOSED UNIFIED RULE:
  "Use INNER JOIN when the related record is required for business logic.
   Use LEFT JOIN only when the relationship is optional and NULL results
   are handled by the application. Document the reason in a SQL comment."

Apply to: Line 67 (replace) + Remove line 89 (redundant after clarification)

Adding Missing Sections

PROPOSED ADDITION (Missing Section):

INSERT AFTER line 15 (after project overview):

## Tech Stack

- Runtime: Node 20 / Bun 1.1
- Language: TypeScript 5.4 (strict mode)
- Frontend: Next.js 14 App Router
- Backend: FastAPI 0.110 (Python 3.12)
- Database: PostgreSQL 16
- Testing: Bun test (TS) / pytest (Python)
- Package manager: bun (NEVER npm or yarn for TS projects)

Phase 6: Apply Changes (With Confirmation)

Present all proposed changes to the user. Apply only after explicit confirmation.

For each change:
1. Show the current text (with line numbers)
2. Show the proposed replacement
3. Explain the reason
4. Wait for approval

Do not batch all changes into a single approval. Each substantive change deserves independent review.

Phase 7: Post-Improvement Verification

After applying all approved changes:

# Confirm the file is valid (no syntax issues for markdown)
# Re-read the modified file to verify changes applied correctly
# Confirm no new contradictions were introduced

Run a second pass of the contradiction check across all CLAUDE.md files in the repo to confirm the overall system is now consistent.

Output Format

CLAUDE.MD IMPROVEMENT COMPLETE

Files audited: <count>
Issues found: <count>
  Stale content: N
  Contradictions: N
  Missing sections: N
  Ambiguous rules: N
  Dead references: N

Changes applied: <count>
Changes deferred (user declined): <count>
Changes pending (awaiting user): <count>

Files modified:
  - /path/to/CLAUDE.md (<N> changes)

Overall quality improvement: <before score>/25 -> <after score>/25

Next recommended action: <re-audit in 90 days | address deferred items | none>

Integration Notes

• This skill is safe to run on any repository — it reads before proposing any writes
• For large repositories with many CLAUDE.md files, process root-level files first, then service-level files
• When a global ~/.claude/CLAUDE.md exists, audit it separately as it affects all repositories
• Pair with /automation-recommender after improving CLAUDE.md to identify automation opportunities enabled by cleaner project instructions
• Run this skill when onboarding to a new codebase to understand the stated constraints before writing any code