skills.rest
Tgoldi
TgoldiCOMMUNITY
Explore all skills by this author →
GitHub

claude-md-improver

Audit and improve CLAUDE.md files against quality rubrics and templates.

1|Updated May 10, 2026
Search Tags:#code quality#documentation#claude code#audit#monorepo#claude.md#project context
One-click install
npx skills add https://github.com/Tgoldi/claude-skills --skill claude-md-improver-tgoldi
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: claude-md-improver
Source: https://github.com/Tgoldi/claude-skills/tree/main/claude-md-improver
Command: npx skills add https://github.com/Tgoldi/claude-skills --skill claude-md-improver-tgoldi

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? CLAUDE.md files often become stale, incomplete, or vague, leaving Claude Code without accurate project context. This Skill scans every CLAUDE.md file in a repository, scores each one against a structured quality rubric, and applies targeted improvements after user approval. ## Core Features & Use Cases - Repository-wide discovery: Finds all CLAUDE.md variants including project root, package-level, local overrides, and global defaults. - Scored quality report: Grades each file A-F across six weighted criteria such as commands, architecture clarity, currency, and actionability. - Targeted updates with diffs: Proposes minimal, project-specific additions shown as diffs, then applies them with the Edit tool after confirmation. - Use Case: After a major refactor, run an audit to find that your build commands are outdated and your new packages/ directory is undocumented, then apply the suggested fixes in one pass. ## Quick Start Ask Claude to audit and improve the CLAUDE.md files in this repository and show a quality report first.

Frequently Asked Questions about claude-md-improver

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I audit CLAUDE.md files in my repository?▼

Ask Claude to audit your CLAUDE.md files and it will discover all variants including root, package-level, and local override files. Each file is scored against six weighted criteria and reported with a letter grade before any changes are made.

What makes a good CLAUDE.md file for Claude Code?▼

A good CLAUDE.md is concise, actionable, and project-specific, with copy-paste-ready commands, clear architecture notes, and documented gotchas. It should avoid generic best practices and restating information obvious from the code.

Does this skill modify CLAUDE.md files automatically?▼

No, it always outputs a quality report first and asks for confirmation before editing. Proposed changes are shown as diffs with explanations, and updates are only applied after you approve them.

Can it handle monorepos with multiple CLAUDE.md files?▼

Yes, it discovers CLAUDE.md files in nested packages and subdirectories, assessing each one individually. Claude Code auto-discovers these files in parent directories, so monorepo setups work without extra configuration.

What should not go into a CLAUDE.md file?▼

Avoid obvious code descriptions, generic best practices, one-off bug fix notes, and verbose explanations. Every line should be project-specific and useful to a future Claude session, since context window space is limited.

Related Skills

Explore More Software Engineering Skills→
applied-artificial-intelligenceapplied-artificial-intelligence
81

project-setup

Scaffold Claude Code project infrastructure with .claude directories and CLAUDE.md templates.

Official
Intermediate
anton-abyzovanton-abyzov
43

agents-md-author

Generates AGENTS.md and CLAE.md files from a project's codebase and its README documentation.

Community
Advanced
rayvoidxrayvoidx

init

Analyze a codebase and generate CLAUDE.md with architecture and tech stack.

Community
Advanced
bryonjacobbryonjacob

documenting-with-claude-md

Organizes and loads CLAUDE.md documentation hierarchies for AI context.

Community
Basic