claude-md-improver

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".

1.39x

Quality

—

Does it follow best practices?

Impact

92%

1.39x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Content

77%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-sequenced, actionable workflow with good discovery and reporting guidance, but it carries redundant inline content that duplicates an existing bundle file and an under-signaled reference, hurting both conciseness and progressive disclosure.

Suggestions

Link references/update-guidelines.md from Phase 4 and replace the inline 'Update Guidelines' content with a one-line pointer, removing the duplication.

Trim or remove the closing 'What Makes a Great CLAUDE.md' section since its principles already appear in Phase 4 and the assessment criteria.

Consolidate the duplicated quality-scoring tables (Phase 2 checklist vs. report-format criteria) so weights and grades appear in one place.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with concrete tables and a copy-paste find command, but the closing 'What Makes a Great CLAUDE.md' section restates Phase 4 principles and the Phase 4 update guidelines duplicate the unreferenced references/update-guidelines.md bundle file — content that could be tightened.	2 / 3
Actionability	Provides executable guidance throughout: a runnable `find` discovery command, a file-type table, a concrete report-format template, and a diff-format example with a real `npm` code block — copy-paste ready.	3 / 3
Workflow Clarity	Five phases are clearly sequenced with explicit validation checkpoints for the destructive write operation — 'ALWAYS output the quality report BEFORE making any updates' and 'ask user for confirmation before updating' — plus a Quick Assessment checklist.	3 / 3
Progressive Disclosure	Body signals references/quality-criteria.md and references/templates.md (both real, one level deep), but references/update-guidelines.md exists as a bundle file yet is never linked — its content is instead duplicated inline in Phase 4, fitting the 2-anchor of content that should be separate being inline.	2 / 3
	Total	10 / 12 Passed

Description

100%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: specific actions, natural trigger terms, explicit when-guidance, and a clear niche. Uses proper third-person voice throughout.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'Audit and improve CLAUDE.md files', 'Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates' — matching the 3-anchor of several specific concrete actions.	3 / 3
Completeness	Explicitly answers both what (audit/improve CLAUDE.md files) and when ('Use when user asks to... Also use when the user mentions...'), with explicit trigger clauses rather than implied ones.	3 / 3
Trigger Term Quality	Covers natural user phrasings — 'check, audit, update, improve, or fix CLAUDE.md files', 'CLAUDE.md maintenance', 'project memory optimization' — the terms a user would actually say.	3 / 3
Distinctiveness Conflict Risk	Scoped narrowly to CLAUDE.md files with distinct triggers, making it unlikely to fire for unrelated skills; written in third person ('Audit', 'Scans', 'evaluates') with no voice penalty.	3 / 3
	Total	12 / 12 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: anthropics/claude-plugins-official
Commit: 30a213f

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.