claude-md-writer - SKILL.md Agent Skill

name: claude-md-writer description: This skill should be used when the user asks to "create CLAUDE.md", "refactor CLAUDE.md", "split large CLAUDE.md", "optimize memory files", "set up .claude/rules", "my CLAUDE.md is too big", "organize project documentation", "implement 3-tier documentation", "add conditional rules", "use paths frontmatter", or needs guidance on CLAUDE.md best practices, size limits, memory hierarchy, or the official 3-Tier documentation system.

CLAUDE.md Writer

Creates and refactors CLAUDE.md files following official Anthropic best practices (2025).

Golden Rules

Rule	Why
CLAUDE.md < 200 lines	Loads on EVERY request, costs tokens
Rules files < 500 lines each	Official recommendation per file
Critical rules FIRST	Top = highest priority
Modular rules → `.claude/rules/`	Conditional loading, organized
Use `paths:` frontmatter	Load rules only for matching files
No linting rules	Use ESLint/Prettier/Biome instead
Pointers over copies	Files change, references stay valid

Memory Hierarchy

Claude Code loads memory in this order (higher = higher priority):

Priority	Type	Location
Highest	Enterprise	`/Library/Application Support/ClaudeCode/CLAUDE.md`
↓	Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`
↓	Rules	`./.claude/rules/*.md` (conditional)
↓	User	`~/.claude/CLAUDE.md`
Lowest	Local	`./CLAUDE.local.md` (gitignored)

Use /memory command to see currently loaded files.

3-Tier Documentation System

Official recommendation for large projects:

Tier	Location	Loads	Target
1. Foundation	`CLAUDE.md`	Always	< 200 lines
2. Component	`.claude/rules/{component}/`	When working in component	< 500 lines
3. Feature	Co-located with code	When working on feature	As needed

Example structure:

.claude/
├── CLAUDE.md                 # Tier 1: always loaded
└── rules/
    ├── database.md           # Tier 2: SQL, migrations
    ├── api.md                # Tier 2: API patterns
    └── frontend/             # Tier 2: subdirectory
        ├── components.md     # paths: src/**/*.tsx
        ├── layout.md         # paths: src/pages/**/*.tsx
        └── tokens.md         # paths: **/*.tsx

Structure Template

# Project Name

One-line description.

## Commands

- `npm run dev` - Development
- `npm run build` - Production
- `npm run test` - Tests

## Architecture

| Path | Purpose |
|------|---------|
| `lib/` | Core logic |
| `app/api/` | API routes |

## Key Patterns

**Pattern Name**: One-line explanation.

## Database (if applicable)

| Table | Key Fields |
|-------|------------|

## Modular Docs

See `.claude/rules/` for:
- `database.md` - queries, schema
- `deploy.md` - deployment

## Tech Stack

One line: Next.js 15, PostgreSQL, TypeScript

Conditional Rules (Path-Specific)

Use YAML frontmatter for file-type-specific rules:

---
paths: "src/api/**/*.ts"
---

# API Rules

- All endpoints must validate input
- Use standard error format

Glob Patterns

Pattern	Matches
`*/.ts`	All .ts files anywhere
`src/*/`	All files under src/
`*.md`	Markdown in project root
`src/components/*.tsx`	Components in specific dir

Combining Patterns

# Multiple extensions
paths: "src/**/*.{ts,tsx}"

# Multiple directories
paths: "{src,lib}/**/*.ts, tests/**/*.test.ts"

Note: Wrap patterns in quotes for YAML safety.

Rules with paths: only load when working with matching files → saves tokens.

Workflow: New Project

Run /init for base CLAUDE.md
Review and trim generated content
Identify critical rules — what breaks if ignored?
Create .claude/rules/ for domain-specific docs
Keep main file < 100 lines

Workflow: Refactor Existing

Count lines — if > 300, must split
Find task-specific content — SQL, debugging, deploy → extract
Create .claude/rules/:
- database.md - queries, schema, connection
- deploy.md - deployment process
- messaging.md - integrations (Telegram, etc.)
Use @file references — don't duplicate
Keep in CLAUDE.md — only what applies to EVERY task

What Goes Where

Content	Location
Project description	CLAUDE.md
Critical constraints	CLAUDE.md (top!)
Quick start (3 commands)	CLAUDE.md
Architecture overview	CLAUDE.md
Key patterns (1-liners)	CLAUDE.md
SQL queries/schema	`.claude/rules/database.md`
Deployment steps	`.claude/rules/deploy.md`
API documentation	`.claude/rules/api.md`
Git workflow	`.claude/rules/git.md`
Personal preferences	`CLAUDE.local.md` (gitignored)
Code style rules	`.eslintrc` / `biome.json` (NOT docs)

Import Syntax

Reference files instead of duplicating:

@README.md
@docs/architecture.md
@~/.claude/snippets/common.md

Relative: @docs/file.md
Absolute: @~/path/file.md
Max depth: 5 hops

CLAUDE.local.md

Personal project settings (auto-gitignored):

# My Local Settings

- Prefer verbose output
- Run tests after every change
- My worktree location: .trees/

Common Mistakes

Mistake	Fix
500+ lines	Split into `.claude/rules/`
SQL examples inline	→ `rules/database.md`
"Run prettier" rules	Use tool config files
Full API docs	→ `rules/api.md`
Deployment instructions	→ `rules/deploy.md`
Code in CLAUDE.md	Use `@file:line` references
Negative rules only	Add alternatives: "Don't X; use Y instead"

Quality Checklist

Before finishing:

CLAUDE.md < 200 lines?
Each rules file < 500 lines?
Critical rules at top?
No task-specific content in main file?
No code style rules (use ESLint/Prettier)?
.claude/rules/ for domain-specific docs?
Subdirectories for components (frontend/, backend/)?
paths: frontmatter for conditional loading?
@ references instead of duplication?
CLAUDE.local.md for personal prefs?

Useful Commands

Command	Purpose
`/init`	Generate initial CLAUDE.md
`/memory`	View loaded memory files

Sources

Official:

code.claude.com/docs/en/memory (Memory management, paths, globs)
anthropic.com/engineering/claude-code-best-practices
claude.com/blog/using-claude-md-files

Community:

thedocumentation.org/claude-code-development-kit (3-Tier System)
claudefa.st/blog/guide/mechanics/rules-directory
humanlayer.dev/blog/writing-a-good-claude-md

Updated: Jan 2026