Create and optimize CLAUDE.md memory files or .claude/rules/ modular rules for Claude Code projects. Covers file hierarchy, content structure, path-scoped rules, best practices, and anti-patterns. Use when working with CLAUDE.md files, .claude/rules directories, setting up new projects, or improving Claude Code's context awareness — even when the user just says "memory file" or mentions Claude instructions without naming the filename.
Create and optimize CLAUDE.md memory files or .claude/rules/ modular rules for Claude Code projects. Covers file hierarchy, content structure, path-scoped rules, best practices, and anti-patterns. Use when working with CLAUDE.md files, .claude/rules directories, setting up new projects, or improving Claude Code's context awareness — even when the user just says "memory file" or mentions Claude instructions without naming the filename.
when_to_use
When the user wants to create, clean up, or update Claude Code memory files. Routes via `$ARGUMENTS` — `init` (scaffold minimal CLAUDE.md), `optimize` (deep cleanup of bloat), `revise` (capture session learnings). Keywords — CLAUDE.md, memory file, instructions file, .claude/rules, optimize CLAUDE, init CLAUDE, revise CLAUDE, auto memory, MEMORY.md, subagent memory. Without a subcommand, treat the argument as free-form guidance about memory files. Skip for subagent system prompts and .claude/agents/ configs — use /agent-creator.
argument-hint
["init | optimize | revise | task description"]
license
MIT
compatibility
Optimized for Claude Code; degrades gracefully on any agent implementing the Agent Skills standard.
These rules govern every prose artifact this skill emits — READMEs, CHANGELOGs, commit messages, PR bodies, release notes, doc paragraphs, non-trivial comments. Apply them at draft time, verify before output.
Match the surrounding style — punctuation, capitalization, backtick conventions, em-dash vs parens, bullet style.
Every sentence changes the reader's understanding. Cut it otherwise.
Front-load the verb — "Creates", not "This helps you create".
Concrete over abstract. Lists for ≥3 enumerable items.
Assert positively. Reserve negation for real constraints (NEVER commit secrets).
No marketing words: powerful, robust, seamlessly, leverage, unlock, comprehensive, delightful.
No AI tells: delve, tapestry, intricate, pivotal, testament, underscore, crucial, garner, showcase, additionally, moreover, furthermore, indeed.
After drafting English prose, invoke /humanize-en if installed.
Core Principle
Memory files consume tokens every session. Keep them minimal — include only what the agent cannot discover on its own or what a tool doesn't already enforce (linter, TypeScript, tests).
Three mechanisms carry knowledge across sessions:
CLAUDE.md — single-file instructions you write. Always loaded.
Auto memory — notes Claude writes itself per project. See Auto Memory below.
For most projects, CLAUDE.md and rules combine (hybrid pattern). See Workflow > Storage Strategy for the pick-which decision.
Quick Start
Run /init to auto-generate a CLAUDE.md. Or create manually:
# Project Name## Tech Stack- [Primary framework]
- [Key non-obvious libraries]
## Commands-`npm run dev` - Dev server
-`npm test` - Run tests
-`npm run build` - Build
## Rules- [2-3 critical project-specific rules]
Run /memory to view all loaded files (CLAUDE.md, CLAUDE.local.md, rules), toggle auto memory, and open any file in your editor
File Hierarchy
Location
Scope
Notes
Managed policy (OS-specific path managed by IT)
All org users
Cannot be excluded by individual settings
./CLAUDE.md or ./.claude/CLAUDE.md
Team via git
Project-wide
./.claude/rules/*.md
Team via git
Modular, optionally path-scoped
~/.claude/CLAUDE.md
All your projects
Personal, applies everywhere
~/.claude/rules/*.md
All your projects
Personal rules, loaded before project rules
./CLAUDE.local.md
Just you (this project)
Add to .gitignore yourself (or use /init personal option)
All discovered files are concatenated, not overridden. More specific locations take precedence in conflicts. Within a directory, CLAUDE.local.md loads after CLAUDE.md, so personal notes win over team instructions at the same level.
Claude recurses UP from the CWD, loading all files found. Subtree CLAUDE.md files load on-demand when Claude reads files in those directories.
AGENTS.md is not read directly. If your repo uses it for other agents, import it from CLAUDE.md with @AGENTS.md so both tools share one source.
Managed CLAUDE.md ≠ managed settings. Enterprise deployments can push both, and they serve different purposes. Settings enforce (blocked tools, sandbox, auth, env); CLAUDE.md guides (coding standards, compliance reminders, behavioral instructions). Security-critical rules belong in settings — CLAUDE.md shapes Claude's behavior but is not a hard enforcement layer.
The .claude/rules/ directory splits instructions into focused markdown files.
Use .claude/rules/ when: many concerns, different rules for different file types, team maintains different areas
Use CLAUDE.md when: tiny project, universal rules, single source of truth
Combine both (hybrid) for most projects — CLAUDE.md stays slim and @-imports the active rules, giving humans a visible TOC while the rules carry the content. See Workflow > Storage Strategy below for when to pick which.
Path-scoped rules use YAML frontmatter:
---paths:-"src/api/**/*.ts"---# API Rules-Allendpointsmustincludeinputvalidation
The 6 sections every CLAUDE.md should have and the 6 bloat categories to avoid (linter rules, agent-discoverable, marketing/vision, redundant specs, verbose prose, generic best-practices): references/optimize-guide.md.
CLAUDE.md-specific writing rules
The canonical Writing rules block above carries the universal prose rules. The rules below add what is specific to authoring CLAUDE.md and .claude/rules/ files — directive phrasing, emphasis discipline, HTML-comment behavior under context injection.
Golden rule: If someone with zero project context reads your CLAUDE.md and gets confused, Claude will too.
Be specific, never vague:
❌ "Format code properly" / "Write good tests" / "Follow best practices"
✅ "Run `pnpm lint` before committing" / "Tests in `__tests__/` using Vitest"
Be directive; reserve prohibitions for real constraints:
❌ "Try to use TanStack Form for forms"
✅ "Use TanStack Form for all forms (not native form/useState)"
Lead with the action. Keep NEVER for genuine constraints — secrets, data loss, breaking changes — not ordinary preferences.
Show, don't tell: When format matters, show a concrete example (3–5 lines max).
HTML comments: Block-level <!-- comments --> are stripped from CLAUDE.md before injection into context. Use them for human-only maintainer notes without spending tokens. Comments inside code blocks are preserved.
Emphasis, sparingly: Reserve bold + a single keyword for non-negotiable rules (**Never commit secrets**).
Put critical rules first in each section — placement beats emphasis.
Don't stack CRITICAL/MUST/ALWAYS on ordinary guidance. Current models follow instructions literally, so over-emphasis dilutes the rules that matter and can overtrigger.
Target under 200 lines per file. Longer files consume more context and reduce adherence — directives start getting lost.
When exceeding, split via @path imports or .claude/rules/:
# API patterns
@docs/api-patterns.md
# Testing
@docs/testing-guide.md
Imports load eagerly at launch alongside the referencing file. Relative and absolute paths work, ~ expands to home, maximum depth is 5 hops. External imports (outside the project) trigger a one-time approval dialog on first encounter.
Auto Memory
Auto memory layout, loading caps, settings keys, env overrides, and subagent memory: references/auto-memory.md.
Workflow
ALWAYS ASK FIRST: Storage Strategy
Before creating or updating memory files, use AskUserQuestion:
Option 1: Single CLAUDE.md — tiny project, one file carries everything
Option 2: Hybrid (CLAUDE.md slim + .claude/rules/)(recommended default) — CLAUDE.md stays small: intro + @-imports of the active rules + a short At a glance for repo-specific divergences. Rules carry the actual content and can be path-scoped. Zero duplication, since rules load eager and CLAUDE.md doesn't repeat them.
Option 3: Mostly .claude/rules/ — every rule is path-scoped and CLAUDE.md has nothing universal worth stating at the top level.
CLAUDE.md and non-path-scoped .claude/rules/*.md load at launch; path-scoped rules (paths: frontmatter) load on-demand when Claude reads matching files. Either way the slim-hub pattern doesn't lose content, it places it in focused files instead of one long CLAUDE.md.
Creating new memory:
Start with /init or minimal template
Add tech stack and commands first
Add rules only as you encounter friction
Test with real tasks, iterate based on Claude's behavior
Maintaining:
Review quarterly or when project changes significantly
Remove outdated instructions
Add patterns that required repeated explanation
Ask Claude to edit CLAUDE.md directly, or open it via /memory
Troubleshooting:
Problem
Solution
Claude ignores instructions
Check specificity and placement first — move the rule to the top of its section; add one emphatic marker only for a genuine constraint
Context overflow
Use /clear, split into .claude/rules/
Instructions conflict
Consolidate, use hierarchy (root vs subtree)
Path rules not applying
Verify glob pattern matches target files
Debug which instructions load
Use the InstructionsLoaded hook to log files, timing, and reasons
Monorepo picks up irrelevant files
Add claudeMdExcludes glob patterns in .claude/settings.local.json
Memory files not loading from --add-dir
Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 — --add-dir alone gives file access, this env var adds CLAUDE.md/rules loading
CLAUDE.md guidance ignored for security-critical rules
CLAUDE.md is guidance, not enforcement. Use --append-system-prompt for strict-compliance automation, or push rules into permissions.deny/sandbox.enabled settings
Tips:
Set CLAUDE_CODE_NEW_INIT=1 before /init for an interactive multi-phase flow (explores codebase with subagent, asks follow-up questions, presents reviewable proposal)
Instructions survive /compact — project-root CLAUDE.md is re-read from disk and re-injected. Nested CLAUDE.md files reload on-demand the next time Claude reads a file in that subdirectory.
Subcommands
The skill supports three argument-driven workflows via $ARGUMENTS. $SKILL_DIR = this skill's folder — ${CLAUDE_SKILL_DIR} in Claude Code, the directory containing this SKILL.md elsewhere. Load the matching step file when the argument is present:
init — Scaffold a minimal CLAUDE.md: detect the project, draft the file, write after user approval; the Rules section starts empty. See steps/init.md. Optional layout scaffold: bash "$SKILL_DIR"/scripts/init_structure.sh <mode> writes starter rule stubs — use only when the user asks for a pre-seeded layout.
optimize — Deep cleanup of a bloated CLAUDE.md. See steps/optimize.md. Always start with python3 "$SKILL_DIR"/scripts/audit_claude_md.py <path> — the JSON hit-list is your fix list. Read references/optimize-guide.md for the WHY behind each category.
revise — Capture session learnings into CLAUDE.md. See steps/revise.md.
Without a subcommand, treat the argument as free-form guidance about memory files and answer from the sections above.
Script schemas: references/schemas.md — JSON / RESULT shapes for the three deterministic scripts (audit, validate, init)
Deterministic scripts
scripts/audit_claude_md.py — line-count + 6-category bloat scan + @import resolver. Run first for optimize — the JSON output is your hit-list; revise consults it when drift is suspected. Python 3.7+.
scripts/init_structure.sh — idempotent scaffold for the three storage strategies (single, hybrid, rules-only). Never overwrites.
See also
/agent-creator — subagent configuration and orchestration. A CLAUDE.md that defines project-wide instructions often pairs with .claude/agents/*.md files; use /agent-creator to author those.
About
claude-md contains the reserved substring claude. This is intentional: the agentskills.io open standard reserves anthropic / claude in skill names but permits a narrow exception for first-party filename conventions, declared in the skill body. This skill operates directly on the first-party CLAUDE.md filename; alternatives (memory-md, ctx-md) lose essential semantic clarity.
