home / skills / serejaris / ris-claude-code / claude-md-writer

claude-md-writer skill

Q: What line counts should I enforce?

Main CLAUDE.md: aim <200 lines (prefer <100 for new projects). Rules files: keep each <500 lines.

Q: How do path-specific rules save tokens?

Rules with YAML frontmatter 'paths:' are only loaded when working on matching files, reducing the amount of memory Claude loads and lowering token costs.

safe

/skills/claude-md-writer

This skill helps create and refactor CLAUDE.md files by enforcing size, structure, and content organization according to official best practices.

npx playbooks add skill serejaris/ris-claude-code --skill claude-md-writer

Review the files below or copy the command above to add this skill to your agents.

Files (3)

skill.md

6.4 KB

---
name: claude-md-writer
description: Use when creating or refactoring CLAUDE.md files - enforces best practices for size, structure, and content organization
---

# 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

```markdown
# 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:

```markdown
---
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

```yaml
# 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

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

## Workflow: Refactor Existing

1. **Count lines** — if > 300, must split
2. **Find task-specific content** — SQL, debugging, deploy → extract
3. **Create `.claude/rules/`**:
   - `database.md` - queries, schema, connection
   - `deploy.md` - deployment process
   - `messaging.md` - integrations (Telegram, etc.)
4. **Use `@file` references** — don't duplicate
5. **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:

```markdown
@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):

```markdown
# 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

Overview

This skill helps create and refactor CLAUDE.md files to follow Anthropic best practices for size, structure, and conditional loading. It enforces concise main files, modular rules, path-specific loading, and a clear memory hierarchy so Claude loads only what’s necessary. Use it to reduce token costs and improve maintainability across projects.

How this skill works

The skill inspects CLAUDE.md and .claude/rules/ content, checks line counts, identifies task-specific material to extract, and validates YAML frontmatter with paths globs. It suggests breaking large files into modular rules, ordering critical rules first, and replacing duplicated content with file pointers. It also verifies memory hierarchy placement and recommends CLAUDE.local.md for personal preferences.

When to use it

Creating a new CLAUDE.md for a project
Refactoring an oversized CLAUDE.md (>200–300 lines)
Organizing domain-specific guidance into .claude/rules/
Adding path-specific rules to reduce token load
Auditing project memory hierarchy and file loading order

Best practices

Keep main CLAUDE.md under ~200 lines; prefer <100 for new projects
Put critical constraints at the top so they load first
Move SQL, deployment, and API docs to .claude/rules/ with <500 lines each
Use YAML frontmatter paths: load rules only when matching files
Reference files with @pointers instead of copying content
Store personal prefs in CLAUDE.local.md (gitignored)

Example use cases

Run /init to bootstrap a minimal CLAUDE.md and then trim to essentials
Refactor a 700-line CLAUDE.md: extract database.md, deploy.md, api.md into .claude/rules/
Add paths: 'src/api/**/*.ts' to API rules so they load only during backend work
Create component-specific rules under .claude/rules/frontend/ with globs for UI files
Replace repeated deployment steps with @deploy.md pointers to keep docs single-sourced

FAQ

What line counts should I enforce?

Main CLAUDE.md: aim <200 lines (prefer <100 for new projects). Rules files: keep each <500 lines.

How do path-specific rules save tokens?

Rules with YAML frontmatter 'paths:' are only loaded when working on matching files, reducing the amount of memory Claude loads and lowering token costs.