claude-plugins/claude-code/skills/claude-memory/SKILL.md

name, description

name	description
Claude Code Memory Specialist	Optimize and troubleshoot Claude Code memory files (CLAUDE.md) for efficiency, token management, and team collaboration. Use PROACTIVELY when memory isn't loading, context is bloated, optimizing existing memory files, or when users mention "CLAUDE.md", "memory file", or "project context". NOT for initial setup - use /init command first.

Claude Code Memory Optimization & Troubleshooting

When to Use This Skill

Use this skill when:

• Troubleshooting memory files that aren't loading
• Optimizing bloated CLAUDE.md files (>200 lines)
• Managing token consumption in project memory
• Setting up memory hierarchy (project/user/subfolder)
• Debugging why Claude isn't following instructions
• Organizing memory for team collaboration

Do NOT use this skill for:

• Initial setup - Use /init command instead
• Creating slash commands (use claude-command-expert skill)
• General Claude Code issues

Important: Always start with /init for initial project memory setup.

Quick Reference: Memory Hierarchy

1. Enterprise Policy       ~/.claude/enterprise/CLAUDE.md (highest priority)
2. Project Memory          ./CLAUDE.md or ./.claude/CLAUDE.md
3. User Memory             ~/.claude/CLAUDE.md
4. Subfolder Memory        ./subfolder/CLAUDE.md

Lookup Order: Claude searches upward from current directory, loading all CLAUDE.md files found.

Core Principles

1. Target Size: 100-200 Lines

Why: Each CLAUDE.md loaded consumes tokens in every conversation.

# ❌ Bad (500+ lines)
Extensive documentation embedded inline

# ✓ Good (150 lines)
Core info + imports for details

2. Progressive Disclosure Pattern

# CLAUDE.md (Core - always loaded)
Quick reference, critical rules, imports

# docs/architecture.md (Loaded on demand)
Detailed architecture information

# docs/style-guide.md (Loaded on demand)
Comprehensive coding standards

3. Use Specific, Emphatic Language

# ❌ Weak
Use functional components

# ✓ Strong
IMPORTANT: ALL React components MUST be functional (no class components).

Essential Structure

Minimal Template (100 lines)

# ProjectName

Brief description.

## Tech Stack
- Key technologies
- See @docs/tech-stack.md for details

## Common Commands
```bash
npm run dev    # Start development
npm test       # Run tests

Conventions

• 2-space indentation
• ESLint + Prettier
• See @docs/style-guide.md

IMPORTANT Rules

• YOU MUST run tests before commits
• Never commit secrets
• Update docs with code changes

For complete templates, see [templates.md](templates.md)

## Common Problems (Quick Fixes)

| Problem | Quick Fix |
|---------|-----------|
| Memory not loading | Check filename case: `CLAUDE.md` |
| Claude ignores rules | Add `IMPORTANT:` or `YOU MUST` |
| Too many tokens | Move details to @docs/ imports |
| Updates not working | Restart session or use `/memory` |
| Conflicting memories | Project wins over user (check hierarchy) |

For detailed troubleshooting, see [troubleshooting.md](troubleshooting.md)

## Optimization Quick Win

**Before (bloated)**:
```markdown
This project is a comprehensive platform built with React, Node.js, Express,
PostgreSQL... [extensive paragraph explaining everything]

After (lean):

Tech Stack: React + Node.js + PostgreSQL
See @docs/architecture.md for details

Result: 80% token reduction

For optimization patterns, see patterns.md

File Locations

Project (Team-Shared)

.claude/CLAUDE.md         # Team standards (in git)
.claude/settings.json     # Team configuration

Personal (Not Shared)

.claude/CLAUDE.local.md   # Personal overrides (gitignored)
~/.claude/CLAUDE.md       # Global defaults

Import Best Practices

✓ Do

# CLAUDE.md
Quick reference content

For detailed architecture: @docs/architecture.md
For API reference: @docs/api-reference.md

❌ Don't

# CLAUDE.md
@docs/a.md → @docs/b.md → @docs/c.md → @docs/d.md → @docs/e.md → @docs/f.md
# Max depth is 5, avoid deep chains

Rules:

• Max import depth: 5 levels
• No circular references
• Use relative paths for project files
• Keep import chains flat, not deep

Quick Update Methods

Method 1: # Shortcut (Fastest)

# Press # at input start
# Type your update
# Auto-adds to appropriate CLAUDE.md

Method 2: /memory Command

/memory
# Opens memory management interface

Method 3: Direct Edit

vim CLAUDE.md
# Then ask Claude to reload

Emphasis Techniques

For critical rules:

IMPORTANT: [Critical rule]
YOU MUST [mandatory action]
NEVER [forbidden action]
**Bold** for emphasis
ALL CAPS for maximum attention

Testing Memory Effectiveness

Quick Test

# Add temporary marker to CLAUDE.md
**MEMORY TEST: If you see this, memory loaded correctly**

# Ask Claude: "What's the first line of your memory?"
# Should see marker, then remove it

Team Setup Example

# .gitignore
.claude/CLAUDE.local.md       # Personal only
.claude/settings.local.json   # Personal settings

# .claude/CLAUDE.md (in git)
# Team Standards

@docs/architecture.md
@docs/conventions.md

IMPORTANT: All team members follow these standards.

## Git Workflow
1. Feature branch from develop
2. PR requires 2 approvals
3. Squash merge

## NEVER
- Commit directly to main
- Merge without tests passing

For team workflows, see workflows.md

Resources

• Memory File Templates - Ready-to-use CLAUDE.md templates
• Troubleshooting Guide - Detailed problem-solution guide
• Optimization Patterns - Advanced token-saving techniques
• Team Workflows - Collaboration strategies
• Official Documentation

---

Remember: Practice what we preach - keep memory lean (100-200 lines), be specific not vague, use imports for details, emphasize critical rules, test effectiveness.