12 min de lectura

De comando a plugin: los cuatro niveles de Claude Code

Claude Code tiene cuatro piezas: comandos, skills, agentes y plugins. Cada una añade poder y complejidad, y hay un momento claro para pasar a la siguiente.

Un proyecto que usa Claude Code suele tener varias de estas carpetas: .claude/commands/, .claude/skills/, .claude/agents/, a veces un .claude-plugin/. Todas guardan markdown con YAML al principio, todas amplían lo que Claude puede hacer, todas acaban en el menú de barra. La mayoría de la gente elige una según lo que vio primero en un tutorial, y ahí se queda.

Eso funciona a pequeña escala. Se rompe en cuanto necesitas un segundo modelo, un MCP concreto, un script de Python, un formato de salida reproducible, o una forma de enviarle el conjunto a un compañero. En ese momento, o reconstruyes desde cero en el nivel correcto, o sigues estirando el que tenías hasta que se rompe.

Lo vemos una y otra vez con clientes que arrancan en Claude Code. El primer comando funciona genial durante una semana, y luego alguien intenta meterle lógica que no le corresponde. Aquí va el mapa que solemos dar: un concepto por nivel, un mismo ejemplo de principio a fin, y una regla clara de cuándo subir.

Los cuatro niveles, en una frase cada uno

Cada extensión de Claude Code encaja en una de estas cuatro formas. Cada una añade capacidad y también coordinación, así que conviene saber en cuál estás antes de construir la siguiente.

  1. Comando: un fichero markdown corto en .claude/commands/<nombre>.md que disparas con /nombre. Claude decide el resto.
  2. Skill: una carpeta en .claude/skills/<nombre>/ con un orquestador (SKILL.md) más scripts, referencias, plantillas y ejemplos.
  3. Agente: un subagente especializado en .claude/agents/<nombre>.md que la skill despacha. Modelo fijado, herramientas permitidas, contexto aislado.
  4. Plugin: un repositorio con .claude-plugin/plugin.json que empaqueta comandos, skills y agentes para que se distribuyan y versionen como una unidad.

La progresión sigue dónde vive de verdad la complejidad. Un comando es un prompt. Una skill es un prompt más los ficheros que lo hacen determinista. Un agente es un paso de una skill con su propia configuración. Un plugin empaqueta comandos, skills y agentes para distribuirlos y versionarlos como una unidad.

Antes de construir nada, mira lo que ya tienes. Escribe / en una sesión y verás comandos, skills y subagentes de fábrica: /help, /init, /model, /agents, /skills, /plugin, entre otros. Claude también trae skills incorporadas (simplify, debug, batch, loop) y subagentes integrados (Explore, Plan, general-purpose) que se despachan solos. No reconstruyas lo que ya está: el trabajo a medida es para lo específico de tu dominio, tu equipo, tus datos.

Un ejemplo, subiendo los cuatro niveles

Para hacerlo concreto, seguimos el mismo caso en cada nivel: rastrear noticias de IA a diario. Empieza como un prompt de una línea y termina como un plugin versionado con trabajadores en paralelo.

La primera versión es un comando que se dispara una vez al día. A la segunda semana empieza a fallar: Claude resume publicaciones de marketing en vez de lanzamientos reales, el formato cambia de una ejecución a otra, y hace falta deduplicar historias que cubren a la vez Twitter y TechCrunch. Sube a skill. Luego la skill hace demasiado en una sola llamada al modelo, así que se divide en cuatro agentes. Después un compañero también lo quiere, así que se empaqueta en un plugin.

El objetivo del ejemplo no es el resumen de noticias en sí, sino aprender a notar el momento en que el nivel actual deja de bastar. Estirar un comando más allá de ese punto es donde la mayoría de los proyectos se enredan.

Nivel 1: comando, el prompt reutilizable

Un fichero markdown con un prompt corto que se repite día tras día. Se guarda una vez y se dispara con /nombre. No hace falta código ni carpeta, solo el fichero. Tú describes qué quieres, Claude decide cómo: qué herramienta llamar y en qué orden.

Úsalo cuando la tarea cabe en un párrafo y confías en que Claude elija las herramientas. Deja de usarlo en cuanto empieces a copiar workarounds, el resultado cambie de ejecución a ejecución, o necesites un MCP concreto o un formato fijo cada vez. Esa es la señal para subir a skill.

.claude/
└── commands/
    └── ai-news.md
---
description: Trae las principales noticias de IA de hoy
---

# /ai-news

Busca en la web las noticias de IA más importantes
de las últimas 24 horas. Cubre lanzamientos de modelos,
rondas de financiación, cambios regulatorios y
papers de investigación relevantes.

Devuelve una lista corta con viñetas, una conclusión
de una línea por elemento y la URL de la fuente.

Claude decide qué herramienta usar (WebSearch en este caso) solo con el prompt, sin conectar un MCP ni especificar permisos. Ese es el punto de quedarte en el nivel 1.

Se instala con mkdir -p .claude/commands && mv ai-news.md .claude/commands/ para el proyecto, o en ~/.claude/commands/ para todos tus proyectos. Se ejecuta escribiendo /ai-news, con argumentos vía /ai-news for today referenciados como $ARGUMENTS o $0, $1…

La documentación oficial señala que los comandos se han fusionado con las skills: un fichero en commands/deploy.md y una skill en skills/deploy/SKILL.md crean ambos /deploy y se comportan igual.

Nivel 2: skill, el comando con andamiaje

Cuando un comando crece más allá de un párrafo, conviértelo en skill: una carpeta con un fichero obligatorio (SKILL.md) y cualquier script, referencia, plantilla o ejemplo que necesite. SKILL.md es el orquestador: le dice a Claude qué hace la skill, cuándo usarla, qué scripts ejecutar, qué referencias leer y qué salida producir. Cualquier otro fichero es apoyo pasivo, Claude solo lo carga cuando SKILL.md lo pide.

No hay nombres de subcarpeta obligatorios, pero se han asentado convenciones. scripts/ guarda Python o bash para lógica determinista. references/ guarda documentos que Claude lee cuando SKILL.md se lo pide. templates/ son ficheros que Claude rellena. examples/ marcan el tono y la estructura a seguir. assets/ es para binarios estáticos.

Así quedó repartido /ai-news en carpetas una vez dejó de bastar como comando suelto:

.claude/skills/
└── ai-news/
    ├── SKILL.md               ← orquestador: cuándo correr, qué llamar, formato de salida
    ├── scripts/
    │   ├── dedupe.py           ← agrupa artículos de la misma historia entre fuentes
    │   └── classify.py         ← etiqueta cada historia por categoría
    ├── references/
    │   ├── trusted-sources.md  ← lista blanca de feeds
    │   └── taxonomy.md         ← definiciones de categoría
    ├── templates/
    │   └── brief.md            ← forma exacta de la salida
    └── examples/
        └── 2026-04-12-brief.md ← ejecución previa de referencia

SKILL.md cose todo: lee primero trusted-sources.md, lanza búsquedas por fuente, corre dedupe.py, corre classify.py, y rellena templates/brief.md siguiendo el ejemplo. Se dispara igual que un comando, con /ai-news o dejando que Claude la elija sola por su description.

De los campos de frontmatter, los más útiles son: description (cuándo auto-invocar, pon primero el caso de uso principal), disable-model-invocation: true (skill solo manual, bien para algo con efectos secundarios como /deploy), allowed-tools (preaprueba herramientas), model y effort (modelo y presupuesto de razonamiento del turno), y context: fork (corre en un subagente aislado sin contaminar el contexto principal).

Las skills son carpetas: van en .claude/skills/<nombre>/ (proyecto) o ~/.claude/skills/<nombre>/ (usuario), y se recargan en caliente durante la sesión, sin reiniciar. Eso sí, SKILL.md se queda en contexto el resto de la sesión, así que conviene mantenerlo corto (la documentación recomienda menos de 500 líneas) y empujar las referencias largas a ficheros separados que solo cargan cuando hacen falta.

Nivel 3: agente, el trabajador especializado

El orquestador de una skill sigue siendo una sola llamada grande al modelo. Cuando hace falta control por paso (fijar un modelo, restringir herramientas, limitar el esfuerzo de razonamiento, contexto aislado), el trabajo se divide en subagentes: la skill despacha, y cada agente tiene su propio prompt de sistema, modelo, herramientas y ventana de contexto limpia.

Recurre a agentes cuando distintos pasos quieren distintos modelos (opus para trabajo creativo, haiku para operaciones), cuando quieres fijar herramientas por paso, o cuando quieres reparto en paralelo. Sáltatelos cuando todo corre bien en un solo contexto con un solo modelo.

Un fichero de agente es un markdown en .claude/agents/<nombre>.md con frontmatter: name y description son obligatorios (la descripción es la frase de “usar cuando…” que decide el despacho), model fija opus / sonnet / haiku, tools es la lista de permisos, effort el presupuesto de razonamiento, maxTurns limita el bucle agéntico, e isolation: worktree corre el agente en un worktree de git temporal.

La versión de skill acertó con el formato, pero cada ejecución seguía siendo una sola llamada grande haciendo trabajos muy distintos: scraping ruidoso, deduplicado con lógica difusa, redacción. Se dividió en cuatro agentes, despachados en paralelo desde SKILL.md:

  • ai-news-scraper en haiku, esfuerzo bajo, solo WebFetch y WebSearch: trae artículos de una fuente, corre × 8 en paralelo.
  • ai-news-dedupe en haiku, esfuerzo bajo, Read y Bash: ejecuta dedupe.py.
  • ai-news-categorize en sonnet, esfuerzo medio: etiqueta cada historia contra la taxonomía.
  • ai-news-editor en opus, esfuerzo alto: escribe el resumen final con una conclusión por historia.

El orquestador despacha los 8 scrapers en paralelo, espera, entrega el feed combinado a dedupe, luego a categorize, luego al editor. El tiempo total baja de unos 3 minutos a unos 40 segundos, y la redacción sale más afinada al correr en opus en vez de heredar una sesión inclinada a haiku.

Se instala igual que un comando pero en agents/, aunque a diferencia de las skills, los cambios en un fichero de subagente requieren reiniciar la sesión (los creados desde la interfaz de /agents se aplican al momento). No “ejecutas” un agente, lo despachas: automáticamente cuando su description coincide con la tarea, con @ai-news-editor para forzarlo, o con claude --agent ai-news-editor para una sesión entera bajo su configuración. Y una restricción importante: los subagentes no pueden lanzar otros subagentes, cualquier reparto en paralelo tiene que salir de la sesión principal.

Nivel 4: plugin, el paquete distribuible

Ahora tienes comandos en una carpeta, una skill en otra y agentes en una tercera. Pertenecen juntos, pero por defecto cualquier cosa en .claude/agents/ es visible para cualquier tarea del proyecto, incluso cuando la skill que la usa no está corriendo.

Un plugin resuelve el empaquetado: agrupa comandos, skills y agentes en una unidad instalable. Los agentes solo existen dentro del alcance del plugin, el comando y la skill se descubren cuando está activo y se ocultan cuando no. Empaqueta como plugin cuando las piezas están acopladas o quieres versionar el conjunto como una unidad. Quédate suelto mientras sigas iterando rápido o los agentes se puedan reutilizar en otro sitio.

plugin-root/
├── .claude-plugin/
│   └── plugin.json     ← manifiesto
├── commands/            ← nivel 1
├── skills/<nombre>/     ← nivel 2
└── agents/              ← nivel 3

Con los cuatro agentes ai-news-* visibles en todo el proyecto y un compañero que quiere el mismo setup, toca empaquetar. De paso se añaden más entradas: un resumen semanal y un comando de inmersión profunda por tema, los tres respaldados por la misma skill y los mismos agentes.

ai-news-radar/                        ← raíz del plugin
├── .claude-plugin/
│   └── plugin.json              ← nombre, versión, descripción
├── commands/                     ← tres entradas (namespaced al instalar)
│   ├── ai-news.md               ← resumen diario
│   ├── ai-news-weekly.md        ← recopilación semanal
│   └── ai-news-deep.md          ← inmersión profunda
├── skills/ai-news/SKILL.md      ← orquestador (namespaced)
├── agents/                       ← 4 especialistas, solo dentro del plugin
│   ├── ai-news-scraper.md
│   ├── ai-news-dedupe.md
│   ├── ai-news-categorize.md
│   └── ai-news-editor.md
├── scripts/
├── references/
└── templates/

agents/, commands/ y skills/ en la raíz se descubren automáticamente al instalar, no hace falta listarlos en el manifiesto: solo plugin.json va dentro de .claude-plugin/.

Para desarrollo local, claude --plugin-dir ./ai-news-radar carga el plugin desde disco sin instalación ni marketplace, y /reload-plugins aplica los cambios en sesión. Para un plugin de un compañero, se añade la fuente como marketplace y se instala por nombre:

/plugin marketplace add webprofits/wp-skills
/plugin install ai-news-radar@wp-skills
/plugin enable ai-news-radar@wp-skills

Las actualizaciones se traen al refrescar el marketplace, no hay un /plugin update independiente. El selector de /plugin pregunta el alcance: usuario (todos tus proyectos, por defecto), proyecto (.claude/settings.json, versionado y compartido con el equipo) o local (.claude/settings.local.json, solo tuyo en ese repo).

Un plugin no se ejecuta como tal, lo que corre es lo que contiene. Sus comandos y skills aparecen namespaced con el nombre del plugin, así que dos plugins pueden tener un comando llamado commit sin chocar: /ai-news-radar:ai-news, @ai-news-radar:ai-news-editor. Usa .claude/ mientras iteras, promueve a plugin cuando se estabilice y quieras enviarlo.

Seis errores habituales al empezar

  1. Los componentes del plugin van en la raíz, no dentro de .claude-plugin/. Pon agents/, commands/, skills/ y hooks/ al mismo nivel que .claude-plugin/. Solo plugin.json va dentro.
  2. Las skills de un plugin llevan espacio de nombres. Una skill en my-plugin/skills/hello/SKILL.md se convierte en /my-plugin:hello, no en /hello. Evita que dos plugins choquen con el mismo nombre.
  3. Reinicio para agentes nuevos, recarga en caliente para skills. Un .md de subagente editado en disco necesita reiniciar la sesión; SKILL.md se recarga solo en la siguiente invocación; los plugins usan /reload-plugins.
  4. Los subagentes heredan modos de permiso peligrosos. Si la sesión principal está en bypassPermissions o acceptEdits, eso pesa más que el permissionMode propio del subagente, aunque diga default.
  5. Los subagentes de un plugin ignoran tres campos. Por seguridad, hooks, mcpServers y permissionMode se ignoran dentro de un plugin. Si los necesitas, el fichero tiene que vivir en .claude/agents/ independiente.
  6. Las rutas de instalación de un plugin son efímeras. Al actualizarse, cambia su ${CLAUDE_PLUGIN_ROOT} y la versión anterior se limpia a los pocos días. Para estado persistente, usa ${CLAUDE_PLUGIN_DATA}.

La matriz de decisión

El error habitual es empezar demasiado arriba. Lo correcto es arrancar en el nivel más bajo que resuelva el problema que tienes delante, y subir solo cuando algo concreto deja de funcionar.

Si notas… Ve a Salvo cuando…
Reescribes el mismo prompt cada día comando el prompt cambia de ejecución a ejecución: sube a skill
El resultado cambia de forma, necesitas un MCP o un formato fijo cada vez skill (sin excepción)
Necesitas un script o referencias que se carguen antes skill el script es puntual: déjalo junto al comando
Distintos pasos quieren modelos o herramientas distintas agentes un solo modelo vale para todo: quédate en skill
Quieres reparto en paralelo desde el orquestador agentes los pasos son secuenciales de todas formas
Varios comandos comparten skill y agentes acoplados plugin sigues iterando rápido: aplaza el manifiesto
Tu compañero necesita la misma configuración, versionada plugin es algo puntual que no vas a mantener

Si dudas entre dos niveles, arranca por el de abajo. Cuesta mucho menos deshacer un comando de una línea que desarmar un plugin a medio construir.