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

85%

Does it follow best practices?

Impact

92%

1.39x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

The canonical home for this skill is claude-md-improver in anthropics/claude-plugins-official

Quality

Content

70%Weight 40%Scale 1-5

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

The body is well-structured with a clear phased workflow and explicit approval validation before destructive writes. Its main weaknesses are broken reference links (referenced files are absent) and generic best-practice padding that could be trimmed or moved to reference files.

Suggestions

Create the missing references/quality-criteria.md and references/templates.md files (or remove the links) so the signaled navigation actually resolves.

Trim or relocate the "User Tips to Share" and "What Makes a Great CLAUDE.md" sections, which restate generic best practices already covered by the quality-criteria checklist.

Add an executable command or concrete heuristic for the Phase 2 quality assessment instead of relying solely on a subjective checklist.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with tables and code blocks, but "User Tips to Share" and "What Makes a Great CLAUDE.md" restate generic best practices Claude already knows and overlap the quality-criteria table, so it could be tightened.	3 / 5
Actionability	Provides a copy-paste `find` command and concrete report/diff format templates with explicit update guidelines, but quality assessment relies on a checklist rather than executable analysis commands, leaving minor gaps.	4 / 5
Workflow Clarity	Five phases are clearly sequenced with explicit checkpoints ("ALWAYS output the quality report BEFORE making any updates"; user-approval gate before Phase 5 destructive writes), satisfying the validation requirement for batch/destructive operations.	5 / 5
Progressive Disclosure	References to references/quality-criteria.md and references/templates.md are clearly signaled one level deep, but those files do not exist in the bundle, breaking navigation; some bulk (report/diff formats, tips) is inlined that could live in references.	3 / 5
	Total	15 / 20 Passed

Description

100%Weight 40%Scale 1-5

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

The description is strong: third-person voice, concrete multi-action capability statement, and explicit trigger guidance with natural synonyms. It cleanly hits the top anchor on all four dimensions.

Dimension	Reasoning	Score
Specificity	"Scans for all CLAUDE.md files, evaluates quality against templates, outputs quality report, then makes targeted updates" lists multiple concrete actions with comprehensive coverage, matching the score-5 anchor.	5 / 5
Completeness	It explicitly answers what (audit/improve, scan, evaluate, report, update) and when ("Use when user asks to check, audit, update, improve, or fix..."; "Also use when the user mentions...") with concrete trigger phrases.	5 / 5
Trigger Term Quality	"check, audit, update, improve, or fix CLAUDE.md files" plus "CLAUDE.md maintenance" and "project memory optimization" gives comprehensive natural-term coverage including synonyms users would actually say.	5 / 5
Distinctiveness Conflict Risk	The CLAUDE.md-specific niche and file-extension-anchored triggers make it clearly distinguishable with minimal conflict risk versus other skills.	5 / 5
	Total	20 / 20 Passed

Validation

81%

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 — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 2 missing	Warning
referenced_paths_exist	Referenced path issues: 4 missing	Warning

	Total	13 / 16 Passed

Repository: mattermost/mattermost-ai-marketplace
Path: plugins/claude-md-improver/skills/claude-md-improver/SKILL.md
Commit: 9cbc484

Reviewed: 5 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.