/memory-md-management

name: memory-md-management
description: Provides comprehensive memory file management capabilities including auditing, quality assessment, and targeted improvements for files such as CLAUDE.md. Use when user asks to check, audit, update, improve, fix, maintain, or validate project memory files. Also triggers for "project memory optimization", "CLAUDE.md quality check", "documentation review", or when a project memory file needs to be created from scratch. This skill scans memory files, evaluates quality against standardized criteria, outputs detailed quality reports with scores and recommendations, then makes targeted updates with user approval.
allowed-tools: Read, Glob, Grep, Bash, Edit

Memory.md Management

Provides comprehensive project memory file management capabilities including auditing, quality assessment, and targeted improvements. This skill ensures the coding agent has optimal project context by maintaining high-quality documentation files such as `CLAUDE.md`.

Overview

Project memory files such as `CLAUDE.md` are the primary mechanism for providing project-specific context to coding agent sessions. This skill manages their complete lifecycle: discovery, quality assessment, reporting, and improvement. It follows a 5-phase workflow that ensures documentation is current, actionable, and concise.

The skill evaluates CLAUDE.md files against standardized quality criteria across 6 dimensions: Commands/Workflows, Architecture Clarity, Non-Obvious Patterns, Conciseness, Currency, and Actionability. Each file receives a score (0-100) and letter grade (A-F) with specific improvement recommendations.

When to Use

Use this skill when:

• User explicitly asks to "check", "audit", "update", "improve", "fix", or "maintain" CLAUDE.md
• User mentions "CLAUDE.md quality", "documentation review", or "project memory optimization"
• A project memory file needs to be created from scratch for a new project
• User asks about improving Claude's understanding of the codebase
• Documentation has become stale or outdated
• Starting work on a new codebase and need to understand existing documentation
• User presses `#` during a session to incorporate learnings into a memory file

**Trigger phrases:** "audit CLAUDE.md", "check documentation quality", "improve project context", "review CLAUDE.md", "validate documentation"

Instructions

Phase 1: Discovery

Find all CLAUDE.md files in the repository:

find . -name "CLAUDE.md" -o -name ".claude.md" -o -name ".claude.local.md" 2>/dev/null | head -50

**File Types & Locations:**

| Type | Location | Purpose | |------|----------|---------| | Project root | `./CLAUDE.md` | Primary project context (checked into git, shared with team) | | Local overrides | `./.claude.local.md` | Personal/local settings (gitignored, not shared) | | Global defaults | `~/.claude/CLAUDE.md` | User-wide defaults across all projects | | Package-specific | `./packages/*/CLAUDE.md` | Module-level context in monorepos | | Subdirectory | Any nested location | Feature/domain-specific context |

Phase 2: Quality Assessment

For each CLAUDE.md file, read [references/quality-criteria.md](references/quality-criteria.md) and evaluate against these criteria:

| Criterion | Weight | What to Check | |-----------|--------|---------------| | Commands/workflows | 20 pts | Are build/test/deploy commands present and working? | | Architecture clarity | 20 pts | Can Claude understand the codebase structure? | | Non-obvious patterns | 15 pts | Are gotchas and quirks documented? | | Conciseness | 15 pts | Is content dense without filler? | | Currency | 15 pts | Does it reflect current codebase state? | | Actionability | 15 pts | Are instructions executable and copy-paste ready? |

**Quality Scores:** A (90-100), B (70-89), C (50-69), D (30-49), F (0-29)

Phase 3: Quality Report Output

**CRITICAL: Always output the quality report BEFORE making any updates.**

Format:

## CLAUDE.md Quality Report

### Summary
- Files found: X
- Average score: X/100
- Files needing update: X

### File-by-File Assessment
#### 1. ./CLAUDE.md (Project Root)
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | X/20 | ... |
| Architecture clarity | X/20 | ... |
| Non-obvious patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]

Phase 4: Targeted Updates

After report output, ask user for confirmation before updating.

**Read [references/update-guidelines.md](references/update-guidelines.md) for detailed update principles.**

Key principles: 1. **Propose targeted additions only** - commands, gotchas, patterns, configs 2. **Keep it minimal** - avoid obvious info, generic advice, one-off fixes 3. **Show diffs** - file, change (diff format), explanation

Diff format:

### Update: ./CLAUDE.md
**Why:** [Brief explanation of why this helps]

```diff
+ ## Quick Start
+
+ ```bash
+ npm install
+ npm run dev
+ ```

### Phase 5: Apply Updates

After user approval, use Edit tool to apply changes. Preserve existing content structure.

## Examples

### Example 1: Quality Assessment

**User request:** "Check if my CLAUDE.md is good"

**Response:**
~~~markdown
## CLAUDE.md Quality Report

### Summary
- Files found: 1
- Average score: 65/100
- Files needing update: 1

### File-by-File Assessment

#### 1. ./CLAUDE.md
**Score: 65/100 (Grade: C)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Commands/workflows | 10/20 | Only npm install documented |
| Architecture clarity | 15/20 | Basic tree, missing module relationships |
| Non-obvious patterns | 5/15 | No gotchas documented |
| Conciseness | 15/15 | Concise and dense |
| Currency | 10/15 | Some outdated paths |
| Actionability | 10/15 | Some vague instructions |

**Issues:**
- Missing t