skilld
All skills
anthropics avatar

/claude-md-improver

@a86e346
by Anthropicanthropics/claude-plugins-official37k stars
4,179

Audit and improve CLAUDE.md files in repositories. Use when user asks to check, audit, update, improve, or fix CLAUDE.md files. Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates. Also use when the user mentions "CLAUDE.md maintenance" or "project memory optimization".

Ask your Agent

Use this Skill: https://skilld.dev/gh/anthropics/claude-plugins-official/claude-md-improver

This session only. Nothing lands on disk.

referencesquality-criteria.md

≈655 tokens on demand. Your agent reads this file only when SKILL.md points to it.

CLAUDE.md Quality Criteria

Scoring Rubric

1. Commands/Workflows (20 points)

20 points: All essential commands documented with context

  • Build, test, lint, deploy commands present
  • Development workflow clear
  • Common operations documented

15 points: Most commands present, some missing context

10 points: Basic commands only, no workflow

5 points: Few commands, many missing

0 points: No commands documented

2. Architecture Clarity (20 points)

20 points: Clear codebase map

  • Key directories explained
  • Module relationships documented
  • Entry points identified
  • Data flow described where relevant

15 points: Good structure overview, minor gaps

10 points: Basic directory listing only

5 points: Vague or incomplete

0 points: No architecture info

3. Non-Obvious Patterns (15 points)

15 points: Gotchas and quirks captured

  • Known issues documented
  • Workarounds explained
  • Edge cases noted
  • "Why we do it this way" for unusual patterns

10 points: Some patterns documented

5 points: Minimal pattern documentation

0 points: No patterns or gotchas

4. Conciseness (15 points)

15 points: Dense, valuable content

  • No filler or obvious info
  • Each line adds value
  • No redundancy with code comments

10 points: Mostly concise, some padding

5 points: Verbose in places

0 points: Mostly filler or restates obvious code

5. Currency (15 points)

15 points: Reflects current codebase

  • Commands work as documented
  • File references accurate
  • Tech stack current

10 points: Mostly current, minor staleness

5 points: Several outdated references

0 points: Severely outdated

6. Actionability (15 points)

15 points: Instructions are executable

  • Commands can be copy-pasted
  • Steps are concrete
  • Paths are real

10 points: Mostly actionable

5 points: Some vague instructions

0 points: Vague or theoretical

Assessment Process

  1. Read the CLAUDE.md file completely
  2. Cross-reference with actual codebase:
    • Run documented commands (mentally or actually)
    • Check if referenced files exist
    • Verify architecture descriptions
  3. Score each criterion
  4. Calculate total and assign grade
  5. List specific issues found
  6. Propose concrete improvements

Red Flags

  • Commands that would fail (wrong paths, missing deps)
  • References to deleted files/folders
  • Outdated tech versions
  • Copy-paste from templates without customization
  • Generic advice not specific to the project
  • "TODO" items never completed
  • Duplicate info across multiple CLAUDE.md files

Source: SKILL.md on GitHub

Third-party checks

1 warning17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    This skill includes some security considerations such as indirect prompt injection risks and access to local configuration files. While these warrant review, they are part of the skill's intended functionality for auditing project documentation. See detailed analysis for context.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer7mo

    1/4 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at a86e346. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 9 months ago

Capability

tools
Read, Glob, Grep, Bash, Edit

Topics

  • Documentation
  • claude-md
  • project-context
  • audit
  • code-quality
  • repository-management
  • ai-coding-agents

README badge

README badge for anthropics/claude-plugins-official/claude-md-improver

What it does

Scans a repository for CLAUDE.md files, evaluates them against quality criteria, outputs a quality report with scores and recommendations, then applies targeted improvements with user approval. Designed for teams maintaining project context files that Claude Code reads during sessions.

Generated from the current SKILL.md.

Frequently asked

What file types and locations does this skill scan?
The skill finds CLAUDE.md files in multiple locations: project root (./CLAUDE.md), local overrides (./.claude.local.md), global defaults (~/.claude/CLAUDE.md), package-specific files in monorepos (./packages/*/CLAUDE.md), and nested subdirectories. It searches up to 50 files per scan.
Does this skill write to CLAUDE.md files automatically?
No. The skill presents a quality report and list of recommended changes first, then asks for user approval before making any updates to files.
What happens if CLAUDE.md is missing or outdated?
The skill flags this during the quality assessment phase (typically a D or F grade) and recommends specific additions based on discovered commands, architecture patterns, and gotchas found in the codebase.
Can this skill work with monorepo projects?
Yes. The skill scans for CLAUDE.md files at package level and automatically handles monorepos because Claude's file discovery works across parent directories.

Generated from the current SKILL.md. These answers refresh after source changes.