CLAUDE.md Writer

A skill for creating and optimizing CLAUDE.md files following official Anthropic best practices (2026-01).

When to Use This Skill

• Creating a new CLAUDE.md for a project
• Reviewing/auditing an existing CLAUDE.md
• Optimizing documentation for better Claude Code performance
• User asks about CLAUDE.md best practices

Golden Rule

Para cada línea, preguntá: “¿Eliminar esto causaría que Claude cometa errores?” Si no, eliminalo. CLAUDE.md inflados causan que Claude ignore instrucciones.

“Think of CLAUDE.md as the ‘unwritten knowledge’ in your codebase”

Quick Tools

• /init – Genera CLAUDE.md inicial basado en la estructura del proyecto
• # key – Agregar instrucciones dinámicamente durante la sesión

@import Syntax

CLAUDE.md puede importar otros archivos:

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

Reference Documentation

For detailed best practices, read: docs/claude-md-best-practices.md

What to Include vs Exclude

CLAUDE.md vs Skills

Usage Modes

El skill acepta argumentos para diferentes flujos:

Content Triage

Antes de agregar contenido a CLAUDE.md, evaluar:

Detectar candidatos a Skill

Si el usuario quiere agregar info que cumple estos criterios, sugerir skill:

• “Cuando trabajes con X…” (condicional)
• “Para tareas de tipo Y…” (específico)
• “Si estás haciendo Z…” (situacional)
• Workflows con muchos pasos
• Conocimiento de dominio especializado

Respuesta sugerida:

Esta información parece ser domain knowledge/workflow específico que no aplica a todas las tareas. Te sugiero crear un skill separado usando /skill-creator o document-skills:skill-creator. Así se carga on-demand sin inflar cada sesión.

Process

Step 1: Analyze the Project

Before writing, gather information:

# Check project type and structure
ls -la
cat package.json 2>/dev/null || cat pom.xml 2>/dev/null || cat Cargo.toml 2>/dev/null

# Find existing documentation
ls -la docs/ 2>/dev/null
ls -la README.md 2>/dev/null

Identify:

• Tech stack (language, framework, build tools)
• Project structure (monorepo, single app, library)
• Existing documentation to reference

Step 2: Apply the Three Dimensions

Every CLAUDE.md must address:

Triage Check

Para cada pieza de información, preguntar:

1. ¿Aplica a TODAS las tareas en este repo? → CLAUDE.md
2. ¿Solo aplica a ciertos tipos de tareas? → Skill
3. ¿Cambia frecuentemente? → Link externo

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]
- **YOU MUST**: [Mandatory action]

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, verify:

• Under 200 lines?
• Passes Golden Rule? (each line prevents mistakes)
• Has WHAT, WHY, HOW sections?
• Critical rules have emphasis (CRITICAL/IMPORTANT)?
• Code snippets replaced with file references?
• Bash commands have descriptions?
• References external docs for detailed topics?
• No styling rules that should be in linters?
• Domain-specific content moved to skills?

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

> **Note**: [Any important setup notes, env files, postinstall behavior]

## 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]
- [Other rules...]

## References

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

Anti-Patterns to Avoid