Referencia · Intermedio · 12 min
Claude Code skills vs hooks, MCP, subagentes y plugins: cuál usar
CLAUDE.md, skills, comandos, subagentes, hooks, MCP y plugins de Claude Code: para qué sirve cada uno, cuándo usarlo, dónde va y cuánto contexto gasta.
Probado con Claude Code 2.1.316 · revisado
Ver los archivos en GitHub Gratis · licencia MIT
Resumen
Claude Code se extiende con varias piezas que parecen solaparse: CLAUDE.md, skills (que ya incluyen los antiguos comandos), subagentes, hooks, servidores MCP y plugins, más las output styles y los nuevos mods. Esta referencia explica en una frase para qué sirve cada una, cuándo aparece la necesidad, cuánto contexto consume, un ejemplo mínimo y la receta de Ctrl+IA donde se desarrolla.
La regla corta: CLAUDE.md para lo que Claude debe saber siempre, skill para procedimientos, subagente para aislar trabajo, hook para lo que debe pasar siempre, MCP para conectar servicios y plugin para empaquetar y compartir.
Cada pieza en una frase
| Pieza | Para qué sirve | Ejemplo |
|---|---|---|
| CLAUDE.md | Contexto que se carga en cada sesión: convenciones y comandos | «usa pnpm, no npm» |
| Skill | Instrucciones, conocimiento o un flujo que invocas con /nombre o que Claude carga cuando encaja con la tarea | /deploy ejecuta tu checklist |
| Comando | Desde que se fusionaron con las skills, .claude/commands/deploy.md y .claude/skills/deploy/SKILL.md crean el mismo /deploy y funcionan igual | Siguen funcionando, pero para lo nuevo usa skills |
| Subagente | Un trabajador con su propio contexto que hace una tarea y devuelve solo un resumen | Un revisor de solo lectura |
| Hook | Un script, petición HTTP, herramienta MCP, prompt o subagente que Claude Code ejecuta al llegar un evento (antes o después de usar una herramienta, al iniciar sesión…), sin que Claude lo decida | Bloquear rm -rf |
| MCP | Conecta Claude con servicios externos | Base de datos, Slack, navegador |
| Plugin | La capa de empaquetado que junta skills, hooks, subagentes y servidores MCP en una unidad instalable | Tu kit para varios repos |
Además, las output styles fijan tono y formato, y los mods (2.1.287) son plugins en JavaScript o TypeScript que cambian la interfaz o intervienen en llamadas a herramientas.
Si te pasa esto, usa esto
La doc oficial propone añadir piezas según aparecen los disparadores, en este orden aproximado:
| Si te pasa esto | Usa esto |
|---|---|
| Claude se equivoca dos veces con una convención o un comando | Añádelo a CLAUDE.md |
| Le pides siempre que sea más breve o que explique más | Una output style |
| Escribes el mismo prompt para empezar una tarea | Guárdalo como skill invocable |
| Pegas por tercera vez el mismo procedimiento de varios pasos | Conviértelo en skill |
| Copias datos de una pestaña del navegador que Claude no ve | Conecta ese sistema por MCP |
| Claude lee muchos archivos para encontrar dónde se define un símbolo | Instala un plugin de inteligencia de código para tu lenguaje |
| Una tarea secundaria inunda la conversación con salida que no volverás a mirar | Pásala por un subagente |
| Quieres que algo pase siempre sin pedirlo | Escribe un hook |
| Un segundo repositorio necesita la misma configuración | Empaquétala como plugin |
Los mismos disparadores sirven para mantener lo que ya tienes: un error repetido es una edición de CLAUDE.md, no una corrección en el chat.
Dónde vive cada pieza
mi-proyecto/
├── CLAUDE.md # siempre cargado: comandos, convenciones («usa pnpm»)
├── .mcp.json # MCP del proyecto (compartido): bases de datos, APIs, navegador
└── .claude/
├── settings.json # hooks, permisos y statusLine del equipo
├── rules/api.md # reglas que solo entran al tocar ciertas rutas (paths:)
├── skills/release/SKILL.md # /release: procedimiento que tú o Claude invocan
├── commands/deploy.md # formato antiguo: también crea /deploy (hoy es una skill)
└── agents/revisor.md # subagente: trabajador con su propio contexto
~/.claude/ # lo mismo, pero tuyo y para todos tus proyectos
├── CLAUDE.md
├── settings.json
├── skills/ agents/
└── skills/mi-kit/.claude-plugin/plugin.json # plugin creado con «claude plugin init mi-kit»En settings.json también va la barra de estado: la desarrollamos en la receta de la statusline.
Skill o subagente
Una skill es contenido reutilizable que se carga en el contexto donde se use; un subagente es un trabajador aislado que corre aparte. La skill añade su texto a tu ventana de contexto principal; el subagente usa una ventana propia y a tu conversación solo vuelve el resumen.
Usa skill para material de referencia (tu guía de estilo de la API) o flujos que invocas (/release). Usa subagente cuando la tarea lee decenas de archivos o hace búsquedas largas cuyo detalle no necesitas, para tareas en paralelo o cuando tu contexto se está llenando. Se combinan: un subagente puede precargar skills con el campo skills: de su definición, y una skill puede ejecutarse en un contexto aislado con context: fork.
Una skill que solo invocas tú, en .claude/skills/release/SKILL.md:
---
name: release
description: Prepara las notas de versión desde el último tag. Úsala cuando pidan notas de versión o changelog.
disable-model-invocation: true
---
1. Lista los commits desde el último tag con `git log $(git describe --tags --abbrev=0)..HEAD --oneline`.
2. Agrúpalos en Novedades, Correcciones y Documentación.
3. Escribe el resultado en CHANGELOG.md sin borrar lo anterior.Los subagentes se guardan como Markdown con frontmatter en .claude/agents/ (proyecto) o ~/.claude/agents/ (todos tus proyectos); el cuerpo es su prompt de sistema. El ejemplo oficial, .claude/agents/code-reviewer.md, es un revisor de solo lectura:
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.Lo desarrollamos en la receta de subagentes.
Hook o instrucción (CLAUDE.md o skill)
La diferencia es el determinismo. Un hook se dispara en su evento sin que Claude decida; una instrucción en CLAUDE.md o en una skill es algo que Claude interpreta y puede no cumplir. La doc oficial lo dice claro: «nunca edites .env» en CLAUDE.md es una petición, no una garantía; un hook PreToolUse que bloquea la edición es una barrera. Si una regla debe cumplirse siempre, que sea un hook (o una regla deny de permisos), no una frase.
Usa hook para formatear tras cada edición, bloquear comandos peligrosos, registrar o notificar. Usa skill cuando Claude deba decidir cómo aplicar los pasos o el contenido sea conocimiento: un checklist de release, una guía de estilo, un manual de depuración (como el de depurar un bug).
Coste de contexto: el hook no gasta nada salvo que devuelva texto; la salida de un PostToolUse que ejecuta tu linter sí entra en el contexto, y una skill /fix-lint le explica a Claude cómo resolverla. Los hooks de todos los orígenes se suman: todos los que coinciden con el evento se ejecutan.
Ejemplo oficial: formatear con Prettier tras cada edición, en .claude/settings.json (requiere jq):
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}Este hook no lo ejecutamos: jq no está instalado en nuestro PC de pruebas. La receta de hooks de seguridad usa Python para no depender de jq.
MCP o skill
MCP conecta Claude con un sistema externo y le da herramientas y datos: consultar tu base de datos, publicar en Slack, controlar un navegador. Una skill le da conocimiento sobre cómo usar bien esas herramientas, más flujos invocables. No compiten, se complementan: el servidor MCP pone la conexión y la autenticación, y una skill documenta tu esquema de base de datos y tus patrones de consulta, o define un /post-to-slack con el formato de mensajes de tu equipo.
Se añaden con claude mcp add (por ejemplo, --transport http para un servidor remoto) y se revisan dentro de la sesión con /mcp:
# Conectar un servicio externo por HTTP (ejemplo oficial)
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Dentro de la sesión: estado y autenticación
/mcpCoste: al iniciar solo se cargan los nombres de las herramientas; los esquemas completos se cargan cuando se usan, porque la búsqueda de herramientas viene activada por defecto. Si un mismo nombre de servidor existe en varios ámbitos, gana local sobre proyecto y proyecto sobre usuario. Lo desarrollamos con Playwright, GitHub y bases de datos en la receta de MCP.
Plugin: cuándo empaquetar (y qué son los mods)
Un plugin no es una pieza nueva, es una caja. Junta skills, hooks, subagentes y servidores MCP para reutilizarlos en varios repositorios o distribuirlos en un marketplace. Las skills de un plugin llevan su espacio de nombres (/mi-plugin:review) para que varios plugins convivan. La estructura mínima es un manifiesto .claude-plugin/plugin.json con el nombre y los componentes.
Desde la 2.1.157, claude plugin init <nombre> lo genera por ti. En nuestro PC creó ~/.claude/skills/mi-kit/ (en la carpeta del usuario, aunque el CHANGELOG habla de .claude/skills) con SKILL.md y .claude-plugin/plugin.json:
# Empaquetar tu configuración como plugin (desde la 2.1.157)
claude plugin init mi-kit
# ✔ Created plugin "mi-kit" at ~/.claude/skills/mi-kit
# It will auto-load next session as mi-kit@skills-dir. Run /reload-plugins to load it now.
# Crea dos archivos: SKILL.md y .claude-plugin/plugin.json
# Ver qué trae un plugin y cuánto contexto cuesta
claude plugin details mi-kit@skills-dir
# Desactivarlo o quitarlo
claude plugin disable mi-kit@skills-dir # o borra la carpetaMientras lo desarrollas no necesitas marketplace: cárgalo desde su carpeta con --plugin-dir.
Los mods (2.1.287) son plugins con manejadores en JavaScript o TypeScript que corren dentro de Claude Code: pueden dibujar un panel, cambiar partes de la interfaz o intervenir en una llamada a herramienta. Si un hook, una skill o un MCP ya hace lo que necesitas, no escribas un mod. No hemos escrito ninguno para esta referencia.
Cuánto contexto gasta cada pieza y quién gana si se repiten
| Pieza | Coste de contexto | Si existe en varios niveles |
|---|---|---|
| CLAUDE.md | Se carga entero al iniciar y cuesta en cada petición; mantenlo por debajo de 200 líneas | Se suman: todos aportan |
| Output style | En cada petición (nada para la de por defecto) | — |
| Skills | Solo nombre y descripción en cada petición; el contenido completo cuando se usa. Con disable-model-invocation: true, nada hasta que la invocas | Se sustituyen por nombre: gestionado > usuario > proyecto. Si una skill y un comando se llaman igual, gana la skill |
| MCP | Nombres de herramientas al inicio y esquemas bajo demanda | Se sustituye por nombre: local > proyecto > usuario |
| Subagentes | Contexto aislado del principal | Se sustituyen por nombre: gestionado > opción de CLI > proyecto > usuario > plugin |
| Hooks | Cero, salvo que devuelvan texto | Se suman y se ejecutan todos |
disable-model-invocation: true es lo recomendado para skills con efectos secundarios. Para revisar el coste real, /context muestra qué llena la ventana y /skill-doctor qué cuesta cada skill y cuánto se usa.
Qué comprobamos
En Linux con Claude Code 2.1.316 comprobamos claude plugin --help y claude plugin init mi-kit (la carpeta creada se borró al momento). Los ejemplos de subagente, hook y MCP son literales de la doc oficial; el de skill sigue el formato de la receta primera skill. No ejecutamos el hook de Prettier ni escribimos un mod. Fuentes: funciones, skills, subagentes, hooks, MCP, plugins, mods y el CHANGELOG.
Preguntas frecuentes
¿Cuál es la diferencia entre una skill y un comando de .claude/commands?
Hoy ninguna en la práctica: los comandos se fusionaron con las skills y ambos crean /nombre. La skill añade una carpeta para archivos de apoyo, más campos de frontmatter y que Claude la pueda cargar sola. Si existen los dos con el mismo nombre, gana la skill.
¿Puedo poner una regla de seguridad en CLAUDE.md?
Puedes, pero es una petición, no una garantía. Para lo que debe cumplirse siempre usa un hook PreToolUse o una regla deny en los permisos (ver hooks de seguridad y permisos).
¿Un subagente gasta menos tokens?
No necesariamente en total: usa su propia ventana con sus tokens de entrada y salida. Lo que ahorra es contexto de tu conversación principal, que solo recibe el resumen.
¿Necesito un plugin para usar mis skills?
No. Las skills en .claude/skills/ o ~/.claude/skills/ funcionan solas. El plugin sirve para empaquetar varias piezas y llevarlas a otros repositorios o a otras personas.
¿Qué es un mod y en qué se diferencia de un hook?
Un hook de configuración ejecuta un comando, una petición HTTP o un prompt fuera de Claude Code. Un mod es un plugin con funciones en JavaScript o TypeScript que corren dentro de Claude Code y pueden dibujar interfaz o intervenir en llamadas a herramientas. Disponible desde la 2.1.287.
¿Por dónde empiezo si no tengo nada?
Por CLAUDE.md con los comandos y convenciones del proyecto. Si tu equipo ya usa AGENTS.md, mira AGENTS.md vs CLAUDE.md. Luego añade cada pieza cuando aparezca su disparador (ver la sección «Si te pasa esto, usa esto»).