claude-md-writer
Toolkit de productividad para Claude Code: skills, agents, commands y configuraciones para desarrollo con LLMs
npx skills add https://github.com/testacode/llm-toolkit --skill claude-md-writerSKILL.md
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
| ✅ 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 |
|---|---|
| Reglas amplias que aplican siempre | Conocimiento de dominio solo relevante a veces |
| Code style y workflow | Workflows especializados reutilizables |
| Convenciones del repo | Info que cambia por contexto |
| Se carga en cada sesión | Se cargan on-demand |
Usage Modes
El skill acepta argumentos para diferentes flujos:
| Invocación | Comportamiento |
|---|---|
/claude-md-writer | Proceso completo: analizar proyecto → escribir/mejorar CLAUDE.md |
/claude-md-writer actualiza con la sesión | Extraer info relevante de la sesión actual y agregar a CLAUDE.md |
/claude-md-writer agrega regla: [descripción] | Agregar una regla específica con el formato correcto |
/claude-md-writer revisa y optimiza | Auditar CLAUDE.md existente, eliminar redundancias, mejorar énfasis |
/claude-md-writer convierte a skill | Identificar contenido que debería ser skill y extraerlo |
Content Triage
Antes de agregar contenido a CLAUDE.md, evaluar:
| Si el contenido es... | Entonces... |
|---|---|
| Regla que aplica a TODAS las tareas | ✅ Agregar a CLAUDE.md |
| Domain knowledge específico | 🔄 Sugerir crear skill con /skill-creator |
| Workflow que solo aplica a veces | 🔄 Sugerir crear skill |
| Info que cambia frecuentemente | ❌ No agregar, linkear a docs |
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-creatorodocument-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:
| 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? |
Triage Check
Para cada pieza de información, preguntar:
- ¿Aplica a TODAS las tareas en este repo? → CLAUDE.md
- ¿Solo aplica a ciertos tipos de tareas? → Skill
- ¿Cambia frecuentemente? → Link externo
Step 3: Write Following Best Practices
Length: Keep under 200 lines (ideal ~100 lines)
Structure (in order):
- Repository Overview (1 paragraph)
- Why This Exists (purpose, users)
- Quick Start & Commands (bash with descriptions)
- Architecture Overview (key patterns)
- Key Development Rules (with emphasis)
- References (links to detailed
...
Repository
