CLAUDE.md, SKILL.md y MCP: ¿Qué capa contiene qué instrucciones?
Por qué un CLAUDE.md gigante falla con los agentes de programación, qué debe incluirse en las reglas, habilidades y conexiones MCP, alcances y rutas, un árbol de decisiones y la trampa en la denominación AGENTS.md.
Fuentes: CLAUDE.md vs SKILL.md vs MCP: The Modern Agent Stack Explained
Los nuevos usuarios de Claude Code y otros agentes de programación similares tienden a cometer el mismo error durante el primer mes: abren CLAUDE.md y siguen escribiendo guías de estilo, pasos de despliegue, listas de verificación para revisiones y esquemas de bases de datos en bruto, hasta que el archivo alcanza las 600 o 900 líneas. La suposición es que más contexto al principio hará que el agente sea más inteligente.
Pero ocurre lo contrario. La memoria de trabajo se llena, las respuestas se vuelven menos precisas y los comandos que antes funcionaban dejan de hacerlo. Algo no está bien, pero es difícil determinar qué. Ante cada solicitud sencilla, el modelo primero debe revisar cientos de líneas de instrucciones irrelevantes antes de llegar a una sola línea de código. La culpa no es del modelo ni del comando; simplemente se le pidió a un único archivo de texto que realizara tres tareas diferentes.
Los agentes de programación modernos funcionan mejor cuando las instrucciones se dividen en tres capas claras: reglas del proyecto que siempre están activas, habilidades de tarea que se cargan según sea necesario, y conexiones con herramientas en tiempo real a través de MCP. Al mantener estas capas separadas, el modelo recibe únicamente lo que necesita, en el momento en que lo necesita.
¿Por qué tres capas?
Es lógico preguntarse por qué tres y no un único archivo grande, o diez archivos pequeños especializados. Cada capa aborda un problema diferente, y estos problemas se superponen menos de lo esperado.
- CLAUDE.md se encarga de las cosas que siempre deben ser verdaderas.
- SKILL.md se ocupa de las cosas que solo importan en ocasiones.
- MCP gestiona los datos que se vuelven obsoletos en el momento en que se registran.
Estos son tres modos de fallo distintos y no tres variantes del mismo. Si se incluyen las habilidades relacionadas con el plegado en CLAUDE.md, el resultado es un archivo enorme que se carga completo en cada sesión, independientemente de si se necesita o no una lista de verificación para el despliegue. Cualquier capa adicional resulta ser una subdivisión de uno de los tres modos de fallo y no una tarea nueva.
¿Qué debe incluirse en CLAUDE.md o AGENTS.md?
Imagínese CLAUDE.md como una nota dejada para un ingeniero desde el primer día. No es el documento completo de incorporación, sino solo las pocas cosas no escritas que todos en el equipo ya conocen, como que aquí no se usan componentes de clase o que nunca se debe acceder directamente a la base de datos, sino pasar por la capa de servicios.
El archivo se encuentra en la raíz del proyecto, y Claude Code lo lee automáticamente al inicio de cada sesión. Nadie lo llama ni lo solicita. Simplemente está presente, al igual que la memoria de las convenciones del equipo cuando alguien se sienta a programar.
Los buenos criterios son las convenciones de codificación, la estructura del proyecto, las restricciones estrictas, las reglas de seguridad como no exponer nunca las claves API en el código, y la personalidad que el agente debe adoptar al revisar el trabajo.
Los criterios deficientes son una guía de despliegue de 40 pasos, un esquema de base de datos y cualquier elemento relevante solo una vez cada diez días. Es en este segundo grupo donde la mayoría de las personas cometen errores. Si algo no es aplicable en cada sesión, probablemente no debería estar allí. Un CLAUDE.md que intenta serlo todo termina siendo una versión lenta y sobredimensionada de nada.
También existe una versión global en ~/.claude/CLAUDE.md que se aplica a todos los proyectos. Por lo general, las personas guardan allí sus hábitos personales, como el estilo preferido para los mensajes de commit o el idioma para las respuestas, y dejan las reglas específicas del proyecto en el archivo del proyecto mismo.
Un archivo que cumple con su función se ve como sigue, adaptado de un conjunto ampliamente compartido de pautas de comportamiento.
# CLAUDE.md
Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
## 1. Think Before Coding
**Don't assume. Don't hide confusion. Surface tradeoffs.**
Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
## 2. Simplicity First
**Minimum code that solves the problem. Nothing speculative.**
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
## 3. Surgical Changes
**Touch only what you must. Clean up only your own mess.**
When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.
When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
The test: Every changed line should trace directly to the user's request.
## 4. Goal-Driven Execution
**Define success criteria. Loop until verified.**
Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"
For multi-step tasks, state a brief plan:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
---
**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
Es breve y específico, y no hay nada en él que necesite ser revisado la próxima semana. Aquí se muestra cómo queda cuando surge un problema, un patrón común en las versiones iniciales.
# Project Notes
Our database has these tables: users, orders, products, sessions,
audit_log (schema pasted below, 340 lines)...
To deploy, first SSH into staging, then run these 47 commands...
Here's our Slack webhook URL for notifications: hooks.slack.com/...
When reviewing PRs, check for: [12 paragraphs of instructions]
Cada elemento de ese segundo ejemplo es incorrecto para CLAUDE.md, y cada uno por una razón distinta. Un esquema queda desactualizado en cuanto alguien agrega una columna. Los pasos de despliegue describen una tarea con nombre específico. Una URL de webhook es un dato confidencial y debe almacenarse en una variable de entorno, no en el markdown comprometido. Las instrucciones para la revisión de PR son una habilidad disfrazada con las características de CLAUDE.md.
Una prueba útil: ¿siguiría siendo cierta esta frase si se leyera de nuevo en tres meses, un martes al azar, mientras se hace algo sin relación? Si no, no pertenece al archivo.
SKILL.md: conocimiento especializado que solo aparece cuando es necesario
Agent Skills provino de Anthropic en octubre de 2025; fue diseñado para que las instrucciones de una tarea específica pudieran almacenarse en una carpeta y cargarse cuando fuera necesario, en lugar de ocupar constantemente el contexto. En diciembre de 2025, este formato se abrió como un estándar independiente, y otras herramientas lo adoptaron rápidamente. VS Code, Cursor, el IDE Antigravity de Google, Gemini CLI, Goose y varios otros agentes de programación ahora soportan el mismo formato SKILL.md que utiliza Claude Code. Es el mismo estándar que convirtió a MCP en el estándar de la industria para las conexiones con herramientas.
La idea resulta útil una vez que se comprende: no es necesario que todo el conocimiento esté siempre en la mente del agente. La mayor parte de lo que sabe un ingeniero solo se vuelve relevante para una tarea específica. Nadie recuerda la lista de verificación de despliegue mientras escribe una función auxiliar. Las habilidades siguen esa misma lógica. Una carpeta que contiene SKILL.md permanece sin usar hasta que llega una solicitud como “revisar este PR”, y en ese momento Claude utiliza la lista de verificación real para la revisión.
Un archivo de habilidad comienza con una breve descripción, llamada frontmatter, que indica qué hace la habilidad y cuándo debe activarse. Cuando un mensaje coincide, Claude carga el resto del contenido. Cuando no coincide, dicho contenido no ocupa espacio alguno en la conversación. Por eso las habilidades parecen más ligeras que cuando se incluye todo en CLAUDE.md. Una habilidad para revisar solicitudes de pull request, otra para migraciones de bases de datos y otra para notas de lanzamiento no compiten por espacio a menos que se esté realizando esa tarea específica.
.claude/skills/
├── code-review/
│ └── SKILL.md
├── pr-description/
│ └── SKILL.md
└── anti-sycophancy/
└── SKILL.md
Las habilidades a nivel de proyecto se encuentran en .claude/skills/ dentro del repositorio. Las habilidades personales que deben seguir al usuario a todas partes se guardan en ~/.claude/skills/. Esta división refleja la estructura de CLAUDE.md: proyecto versus global. Una versión real, simplificada:
---
name: production-code-validation-checklist
description: "Run this checklist before pushing code to GitHub"
---
# Production Code Validation Checklist
**Run this checklist before pushing code to GitHub.**
This is not optional. This is how you prevent broken repositories.
## Secrets Audit
- [ ] Searched for: password, secret, token, key, api_key, credential
- [ ] All secrets are in environment variables or .env, not in code
- [ ] .env file is in .gitignore
## Failure Scenario Testing: Deliberately Break It
This is the most important step. Production code breaks. Can your code
handle it?
- [ ] Run without a required environment variable, does it fail with a
clear error?
- [ ] Simulate a timeout on any HTTP request, does the code handle it?
- [ ] Feed it empty input, null input, and malformed input, one at a time
## Final Production Readiness Assessment
Choose ONE:
- [ ] PROTOTYPE: concept proven, not production ready
- [ ] DEVELOPMENT READY: works for development, not production
- [ ] PRODUCTION CANDIDATE: ready for real-world testing
- [ ] PRODUCTION VERIFIED: tested in a real environment, known to work
**If you cannot check a box, you are not done.**
Fíjese en lo que evita. Tampoco sigue convenciones de codificación ni un esquema de base de datos. Tiene una tarea con nombre, activada por un tipo específico de situación, y eso es lo que la convierte en una habilidad y no en un CLAUDE.md más pequeño. La prueba simple es determinar si algo solo se necesita al realizar una tarea específica y con nombre. Si es así, se trata de una habilidad y no de una regla.
MCP: acceso, no solo conocimiento
Tanto CLAUDE.md como SKILL.md son archivos en formato markdown escritos por alguien. MCP es diferente: conecta a Claude, mientras está en ejecución, con un recurso fuera del chat, ya sea una base de datos, GitHub, Slack, el sistema de archivos o cualquier otro recurso conectado.
En un proyecto basado en RAG, conectar directamente Chroma es un caso típico. El servidor oficial chroma-mcp expone colecciones como herramientas que Claude puede consultar.
{
"mcpServers": {
"chroma": {
"command": "uvx",
"args": [
"chroma-mcp",
"--client-type", "persistent",
"--data-dir", "/path/to/your/chroma/data"
]
}
}
}
Dentro de Claude Code, la configuración se realiza con un único comando sin necesidad de editar manualmente archivos JSON.
claude mcp add --scope project chroma \
-- uvx chroma-mcp --client-type persistent --data-dir ./chroma-data
Registra el servidor y escribe la configuración en .mcp.json dentro del proyecto, el cual puede ser guardado para que todo el equipo tenga la misma conexión sin necesidad de configurarla manualmente. Claude Code ofrece tres niveles de acceso: local, que corresponde a un usuario en una sola máquina; proyecto, que significa que está guardado en el repositorio y es compartido; y usuario, que se refiere a todos los proyectos con los que interactúa una persona. El mismo patrón de proyecto frente a global aparece por tercera vez, lo que facilita recordarlo una vez se ha observado.
El protocolo ha crecido tan rápidamente que ese crecimiento ya forma parte de su historia. El registro oficial de servidores enumera más de 9,000 servidores, y las descargas mensuales del SDK de referencia aumentaron de aproximadamente 2 millones a casi 100 millones en unos 16 meses, según los datos compartidos por Anthropic. Ya no se trata de una función de nicho. Cualquiera que siga pegando un esquema o una propuesta de GitHub en un prompt está realizando a mano lo que una conexión MCP hace en tiempo real, y la copia pegada se vuelve obsoleta tan pronto como cambia algo en el origen.
Un árbol de decisiones
- ¿Debe ser cierto en cada sesión, sea cual sea la tarea? Si sí, guárdalo en CLAUDE.md. Si no, continúa.
- ¿Se trata de una tarea específica, con nombre y repetible, que tiene sus propios pasos? Si sí, conviértelo en un SKILL.md. Si no, continúa.
Una trampa en la nomenclatura
Cualquiera que cambie de herramienta se topará con esto en algún momento. Claude Code y Cursor leen CLAUDE.md, mientras que Codex CLI y algunas otras plataformas utilizan AGENTS.md, que cumple la misma función bajo un nombre diferente. Antigravity de Google, desarrollado por el antiguo equipo Windsurf tras el acuerdo de Google con ellos a mediados de 2025, también emplea su propia convención AGENTS.md. Sin embargo, todas ellas —Claude Code, Cursor, Codex y Antigravity— leen el mismo formato SKILL.md para las habilidades. Así, la capa de reglas varía según la herramienta, pero la capa de habilidades se mantiene uniforme. Eso es importante antes de asumir que una habilidad escrita para un agente debe reescribirse para otro.
El hábito que lo soluciona
Antes de agregar un párrafo a CLAUDE.md, pregúntese a qué uno de los tres categorías pertenece. Gran parte del material incluido en CLAUDE.md en realidad corresponde a una habilidad que nunca recibió su propia carpeta. Esta práctica constituye una forma de ingeniería de contexto mediante etiquetas diferentes: elegir qué ve el agente y en qué momento, en lugar de meter todo en el primer archivo abierto con la esperanza de que el modelo lo organice. Abra un CLAUDE.md y cuente cuántos párrafos en realidad corresponden a habilidades que tienen la extensión de archivo incorrecta. La cifra suele ser mayor de lo esperado.
Leer más
- Explicación de WebMCP: Proporcionar herramientas a los agentes de IA del navegador en lugar de conjeturas — WebMCP permite a una página web declarar herramientas para los agentes de IA. Cómo registrarlas, anotar el riesgo, probarlas en Chrome y gestionar la seguridad, además de cuál es el estado del soporte en los navegadores para 2026.
- Notas prácticas: Los tres niveles de RAG en Google Cloud: Búsqueda vectorial, motor RAG y recuperación por agentes — Guía paso a paso de las Notas prácticas: Los tres niveles de RAG en Google Cloud: Búsqueda vectorial, motor RAG y recuperación por agentes: contratos, verificaciones y espacios para código listo para usar.