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 -50File 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 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 for detailed update principles.
Key principles:
- Propose targeted additions only - commands, gotchas, patterns, configs
- Keep it minimal - avoid obvious info, generic advice, one-off fixes
- Show diffs - file, change (diff format), explanation
Diff format:
### Update: ./CLAUDE.md
**Why:** [Brief explanation of why this helps]
+ ## 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 test command
- Missing build command
- No documentation of auth flow complexity
- References to old src/structure
Recommended additions:
- Add Commands section with test/build
- Document auth module gotcha
- Update architecture paths
### Example 2: Creating from Scratch
**User request:** "Create a CLAUDE.md for this React project"
**Response:**I'll create a CLAUDE.md for your React project. Let me first analyze the codebase structure.
[Scans package.json, src/, and key config files]
CLAUDE.md Quality Report
Summary
- Files found: 0
- Creating new CLAUDE.md at project root
Proposed CLAUDE.md Content:
Project Name
Commands
| Command | Description |
|---|---|
npm install | Install dependencies |
npm run dev | Start dev server (Vite on port 5173) |
npm run build | Production build |
npm run test | Run Vitest tests |
npm run lint | ESLint check |
Architecture
src/
├── components/ # Reusable UI components
├── pages/ # Route pages
├── hooks/ # Custom React hooks
├── lib/ # Utilities and API clients
└── main.tsx # Entry pointGotchas
- Vite requires files in
public/for static assets - State updates in
useEffectneed proper dependency arrays
Shall I create this file?Example 3: Update Proposal
User request: "Update my CLAUDE.md with what you learned"
Response:
### Update: ./CLAUDE.md
**Why:** Discovered that tests require database setup which wasn't documented.
Testing
+ Prerequisites: Start test database first with docker-compose up -d test-db + npm run test - Run all tests + npm run test:unit - Unit tests only (no DB required)
Also found issue with API_BASE_URL:
Environment
API_BASE_URL- API endpoint (default: localhost:3000)
+ API_BASE_URL - API endpoint (required for production, defaults to http://localhost:3000 in dev)
Apply these changes?
~~~
## Best Practices
1. **Always read references before acting**: Quality criteria, templates, and update guidelines contain essential details
2. **Report before editing**: Never modify CLAUDE.md without first presenting a quality report
3. **Preserve existing structure**: When updating, maintain the existing organization and style
4. **Be project-specific**: Only add information specific to this codebase, not generic advice
5. **Verify commands work**: Before suggesting commands, mentally or actually verify they execute correctly
6. **Use progressive disclosure**: Keep SKILL.md lean, reference detailed rubrics in separate files
7. **Score consistently**: Apply the same scoring standards across all files for fair comparison
## Constraints and Warnings
1. **Never modify without approval**: Always get user confirmation before editing CLAUDE.md files
2. **Don't remove content without asking**: If suggesting deletions, explicitly mark them and get approval
3. **Respect `.claude.local.md`**: These are personal settings; never suggest modifying them in shared docs
4. **Avoid generic advice**: Do not add "write good code" type content - focus on project-specific patterns
5. **Keep diffs concise**: Show only the actual changes, not entire file contents
6. **Verify file paths**: Ensure all referenced files exist before documenting them
7. **Score objectively**: Use the rubric consistently; don't inflate scores for incomplete documentation
