En Skills y agentes vimos lo que dan las herramientas: la skill, que se carga en tu conversación, y el agente, que trabaja en un contexto vacío y devuelve un resultado. Aquí vamos a ver qué hacemos nosotros con eso: en este curso hablaremos de skills, agentes y subagentes, y los tres se escriben como skill. Cómo se organiza cada una por dentro (carpetas, secciones del SKILL.md) está en Estructura de un skill.
Más información:
SKILL.md y los ficheros que use.Dos ficheros con instrucciones, que se distinguen solo en dónde se carga su contenido (Skill o agente):
Y la frontera es más fina de lo que parece: una skill lanzada en una conversación recién abierta que cierras al terminar es un agente (el caso especial del tema 8). Claude Code lo hace explícito: una skill con context: fork en el frontmatter se ejecuta como agente, en un contexto aparte, sin cambiar nada más del fichero.
context: fork en las skills que lo necesiten, que es lo que ha acabado haciendo Claude Code.
En este curso vamos a usar tres palabras, y conviene fijar desde ahora qué quiere decir cada una:
context: fork en el frontmatter, pasa a ser un agente de verdad: se ejecuta en su propio contexto.Y cada uno se escribe y se nombra de una forma:
k-, de knowledge: k-servicios, k-tests. Detrás del prefijo, el tema.do-, «hacer» en inglés: do-crear-servicio, do-revisar-pr. Detrás del prefijo, un verbo. Son skills para la herramienta, así que viven en .claude/skills/ con las demás.subagents/ del agente que los lanza: do-crear-servicio/subagents/verificador.md. Sin prefijo: el nombre es su rol.Todo en kebab-case.
.claude/skills/
├── k-servicios/
│ └── SKILL.md
└── do-crear-servicio/
├── SKILL.md
└── subagents/
└── verificador.md
Skill (k-) | Agente (do-) | Subagente | |
|---|---|---|---|
| Qué es | Lo que hay que saber: las convenciones del proyecto | Lo que hay que hacer: un proceso por fases | Una comprobación cerrada dentro de una fase del agente |
| Quién lo lanza | Un agente, o el modelo cuando la necesita | Tú, con / | El agente, en una de sus fases |
| Dónde se carga | En tu conversación | En tu conversación (o en una nueva con context: fork) | En un contexto nuevo y vacío |
| Qué devuelve | Nada: se queda cargada | El trabajo hecho y un mensaje final | Una respuesta cerrada: PASS o FAIL y una línea por problema |
| Dónde vive | .claude/skills/k-servicios/ | .claude/skills/do-crear-servicio/ | .claude/skills/do-crear-servicio/subagents/ |
Ventajas del prefijo:
/. Una skill llamada init o context se confunde con /init o /context; /do-revisar-pr no coincide con ningún comando./do- sale todo lo que se puede lanzar: el autocompletado enseña solo los agentes, sin las skills de conocimiento, que no se lanzan a mano.
Describe cómo se hace algo en el proyecto: cómo son los servicios, cómo se escriben los tests, cómo se nombran los commits. No hace nada sola: la cargan los agentes («carga k-servicios») o el modelo cuando ve en su description que la necesita.
Es el ejemplo 1 del tema 8, el repository JPA: conocimiento que tiene que quedarse en la conversación para que valga en el siguiente mensaje. Por eso es una skill y nunca un agente.
Ejecuta un proceso por fases: crear un servicio, revisar un PR, generar los tests. La lanzas tú con /do-crear-servicio R-12 y al terminar te dice qué ha hecho.
Es el ejemplo 2 del tema 8, generar los tests: el trabajo de un agente. Pero lo escribimos como skill, no como agente de la herramienta (por qué). Lo que aporta el agente, empezar con el contexto vacío, se consigue lanzando la skill en una conversación limpia, con /clear antes. Y si quieres que se ejecute como agente de verdad, mientras tú sigues en tu conversación, en Claude Code basta con context: fork en el frontmatter:
--- name: do-crear-servicio description: Crea un servicio de Pedidos con su test a partir de un requisito de specs/. Usar cuando se pida crear, añadir o generar un servicio o una clase *Service. context: fork ---
Un subagente es un trabajo cerrado dentro de una fase de un agente: comprobar que el test cubre el requisito, revisar el fichero generado, juzgar si cumple el checklist. Lo lanza el agente, no tú, y su respuesta la lee el agente para decidir si sigue o corrige.
Su prompt es un fichero .md en la carpeta subagents/ del agente. Para la herramienta ese fichero no existe: no está en .claude/agents/ ni tiene frontmatter. Es el SKILL.md del agente el que dice cuándo se lanza, qué fichero lee y qué le pasa, y Claude Code arranca un subagente genérico con ese prompt:
✅ Lanza un subagente con model: haiku que lea `subagents/verificador.md` y pásale `requisito` y `ruta_test`. ❌ Lanza un subagente que lea `subagents/verificador.md`. (no dice qué le pasa ni con qué modelo)
Es el agente del tema 8 (El fichero del agente), con las mismas tres secciones, Entradas, Proceso y Salida, y las mismas razones:
Entradas. «Revisa lo que hemos hecho» no funciona.mvn test. Al agente solo le vuelve la respuesta.PASS o FAIL en la primera línea, para que el agente la compare tal cual.
Por qué va dentro del agente y no en .claude/agents/ ni en su propia carpeta do-, en la sección 4.
fork. El fork hereda toda la conversación: el verificador ve razonar al que escribió el código y le da la razón. Además ignora el model.
Tres preguntas, en este orden:
k-. Si es una tarea, sigue.do-. Si la lanza un agente en medio de su proceso, sigue.do-.Con el ejemplo del curso:
k-servicios.do-crear-servicio.do-crear-servicio → subagents/verificador.md.La herramienta ya trae skills y agentes. Tenerlos de otra manera, los agentes como skill y los subagentes como un fichero dentro del agente, es una decisión, y estas son las razones.
.claude/agents/. Nuestros agentes llevan plantillas, scripts, ejemplos, subagentes y evals (la estructura), y todo eso tiene que ir junto para poder mantenerlo. Una skill es una carpeta.agent- delante del nombre y una skill directamente, y /do- autocompleta solo lo que se puede lanzar:
@agent-crear-servicio R-12 /do-crear-servicio R-12
/do-crear-servicio R-12, mirar el resultado y cerrarla. Eso ya es un agente (el caso especial del tema 8): el contexto vacío lo da /clear, no hace falta otro proceso. Y el día que quieras seguir hablando mientras trabaja, context: fork lo convierte en agente de la herramienta sin tocar el resto del fichero..claude/skills/ pero no .claude/agents/, y su frontmatter de agente es otro (tema 3). Un agente escrito como skill funciona igual en Claude Code y en OpenCode; escrito como agente, hay que mantener dos ficheros.SKILL.md, el mismo frontmatter y la misma forma de organizar la carpeta. Lo que cambia entre uno y otro es el cuerpo, no la mecánica.
El único inconveniente: el modelo. Un agente de la herramienta elige su modelo en el frontmatter (model: haiku para un revisor mecánico, el modelo grande para el que diseña). Una skill no: se ejecuta con el modelo de la conversación en la que se carga. La excepción es Claude Code, cuyo frontmatter de skill también admite model, así que ahí el inconveniente desaparece:
--- name: do-revisar-pr description: Revisa un PR y deja la lista de problemas. Usar cuando se pida revisar un PR o una rama. context: fork model: haiku ---
context: fork y model, dice por dónde va el camino: unificar agentes y skills en una sola carpeta y un solo formato. Es lo que hacemos en este curso.
do-crear-servicio comprueba lo que genera ese agente, con las entradas que ese agente le pasa. Fuera de él nadie lo lanza, así que no tiene sentido que esté donde se buscan las cosas que se lanzan. Lo que solo usa uno va con ese uno..claude/agents/ estorbaría. Aparecería en la lista de agentes de la herramienta y en el autocompletado de @, como si fuera para lanzarlo tú. Y en OpenCode, además, no existiría.Entradas y su Salida: están en la misma carpeta y se cambian a la vez. Quien lee do-crear-servicio lo ve entero sin salir de su carpeta.mvn test) no tiene que llenar el contexto del agente. Un fichero de subagents/ da justo eso: un prompt que se lanza en un contexto nuevo y devuelve una línea.
Y la señal de que algo está mal clasificado: si un fichero de subagents/ acaba lanzándose desde dos agentes, es que es un agente. Pasa a su propia carpeta do- y los dos lo cargan desde allí.
Di si cada cosa es una skill, un agente o un subagente, y por qué:
| Tarea | Tipo | Por qué |
|---|---|---|
| Las convenciones de los controladores REST del proyecto | ||
| Crear el controlador de un agregado a partir de su especificación | ||
| Comprobar que ningún controlador devuelve una entidad JPA, al final de crear uno | ||
| Cómo se escribe un mensaje de commit en el equipo | ||
| Revisar un PR entero y dejar la lista de problemas | ||
Contar cuántos requisitos de specs/ no tienen test, dentro de la revisión del PR |
do-revisar-pr tiene estas fases: leer el PR, comprobar las convenciones de los servicios, comprobar que cada requisito tiene test, comprobar la cobertura y escribir el informe. Di qué skills k- carga el agente, qué fases se hacen con un subagente y qué le pasa a cada uno en Entradas.