claude-md-writer

CLAUDE.md Writer

A skill for creating and optimizing CLAUDE.md files following official Anthropic best practices.

Golden Rule

For each line, ask: "Would removing this cause Claude to make mistakes?" If not, remove it. Bloated CLAUDE.md files cause Claude to ignore instructions.

"Think of CLAUDE.md as the 'unwritten knowledge' in your codebase"

Quick Tools

• /init - Generates initial CLAUDE.md based on the project structure
• # key - Add instructions dynamically during the session

@import Syntax

CLAUDE.md can import other files:

See @README.md for overview and @package.json for commands.
Git workflow: @docs/git-instructions.md

Reference Documentation

For examples and validation checklist, see:

• references/good-example.md - Well-structured CLAUDE.md example
• references/bad-example.md - Common anti-patterns to avoid
• references/checklist.md - Quality validation checklist
• references/dead-weight-audit.md - Dead weight audit (5 criteria for trimming instructions)

What to Include vs Exclude

Include	Exclude
Bash commands Claude can't guess	Anything Claude can figure out by reading code
Code style rules that differ from defaults	Standard language conventions
Testing instructions and preferred test runners	Detailed API docs (link instead)
Repository etiquette (branch naming, PR)	Information that changes frequently
Architectural decisions specific to project	Long explanations or tutorials
Developer environment quirks (env vars)	File-by-file descriptions
Common gotchas or non-obvious behaviors	Self-evident practices

CLAUDE.md vs Skills

CLAUDE.md	Skills
Broad rules that always apply	Domain knowledge only sometimes relevant
Code style and workflow	Specialized reusable workflows
Repo conventions	Info that changes by context
Loaded in every session	Loaded on-demand

Content Triage

Before adding content to CLAUDE.md, evaluate:

If the content is...	Then...
Rule that applies to ALL tasks	Add to CLAUDE.md
Specific domain knowledge	Suggest creating a skill
Workflow that only applies sometimes	Suggest creating a skill
Info that changes frequently	Do not add, link to docs

If the user wants to add conditional info ("When you work with X...", "For tasks of type Y..."), suggest creating a separate skill.

Usage Modes

Invocation	Behavior
/claude-md-writer	Full process: analyze project, write/improve CLAUDE.md
/claude-md-writer actualiza con la sesion	Extract relevant info from the current session and add it to CLAUDE.md
/claude-md-writer agrega regla: [descripcion]	Add a specific rule with the correct format
/claude-md-writer revisa y optimiza	Audit existing CLAUDE.md, remove redundancies, improve emphasis
/claude-md-writer audita	Dead weight audit: apply the 5 criteria against the current setup (see references/dead-weight-audit.md)
/claude-md-writer convierte a skill	Identify content that should be a skill and extract it

Process

Step 1: Analyze the Project

Identify tech stack, project structure, and existing documentation.

Step 2: Apply the Three Dimensions

Dimension	Question to Answer
WHAT	What is this project? Tech stack? Structure?
WHY	Why does it exist? What problem does it solve?
HOW	How do I work on it? Commands? Workflows?

Step 3: Write Following Best Practices

Length: Keep under 200 lines (ideal ~100 lines)

Structure (in order):

1. Repository Overview (1 paragraph)
2. Why This Exists (purpose, users)
3. Quick Start & Commands (bash with descriptions)
4. Architecture Overview (key patterns)
5. Key Development Rules (with emphasis)
6. References (links to detailed docs)

Emphasis for Critical Rules:

- **CRITICAL**: [Never violate this]
- **IMPORTANT**: [Always do this]

Progressive Disclosure:

• Use file references instead of code snippets
• Link to external docs for detailed topics
• Keep CLAUDE.md focused on universal instructions

Step 4: Verify with Checklist

Before finalizing, run through the checklist in references/checklist.md.

Template

# CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

## Repository Overview

[One paragraph: what this project is, tech stack, main purpose]

## Why This Exists

[What problem it solves, who uses it, business context]

## Quick Start & Commands

\`\`\`bash
npm ci        # Install dependencies
npm start     # Start dev server
npm test      # Run tests
npm run build # Production build
\`\`\`

## Architecture Overview

[Key patterns, folder structure, main concepts - keep brief]

## Key Development Rules

- **CRITICAL**: [Most important rule that must never be violated]
- **IMPORTANT**: [Second most important rule]

## References

- `/docs/` - Detailed documentation
- `README.md` - Project readme

Dead Weight Audit

When the user asks to audit their setup, apply the 5 criteria from references/dead-weight-audit.md against each rule:

1. Default? — Claude already does it without being told
2. Conflict? — Contradicts another rule in the setup
3. Redundancy? — Covered by another rule or process
4. One-off patch? — Added to fix a specific bad output
5. Vague? — Interpreted differently every time

Expected output:

• List of cuts with a one-line reason each
• List of conflicts found between files
• Clean version of CLAUDE.md without dead weight

Post-audit process: delete → test 3 typical tasks → re-add only what broke.

Anti-Patterns to Avoid

Anti-Pattern	Why It's Bad	Do This Instead
Code snippets	Become stale, waste tokens	Use file:line references
Styling rules	LLM is slow for deterministic tasks	Configure linters
Kitchen sink	Dilutes instruction effectiveness	Keep < 200 lines
No emphasis	Critical rules same weight as minor	Use CRITICAL/IMPORTANT
Auto-generated	Misses project nuances	Manually craft
Domain knowledge	Inflates every session	Move to skills