Diferencias

Muestra las diferencias entre dos versiones de la página.

--- cursos:sdd:09-skills-agentes-subagentes [2026/11/06 08:37] – Renumerar el curso: Estructura de un skill pasa al 10 y los temas siguientes suben un número claude
+++ cursos:sdd:09-skills-agentes-subagentes [2026/11/06 09:13] (actual) – Sección 4: el inconveniente del modelo y la opinión sobre unificar agentes y skills claude
@@ Línea 1: / Línea 1: @@
 ====== 9. Skills, agentes y subagentes ======
-En [[cursos:sdd:08-skills-agentes|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 todo se escribe como //skill//, y hay **tres tipos**: las que saben, las que hacen y los subagentes que lanzan las que hacen. Cómo se organiza cada una por dentro (carpetas, secciones del ''SKILL.md'') está en [[cursos:sdd:10-creando-skills|Estructura de un skill]].
+En [[cursos:sdd:08-skills-agentes|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 [[cursos:sdd:10-creando-skills|Estructura de un skill]].
 Más información:
@@ Línea 26: / Línea 26: @@
 ===== 2. Lo que hacemos nosotros: tres tipos =====
-En este curso **todo se escribe como //skill//**. Lo que cambia es para qué sirve cada una, quién la lanza y dónde se carga:
+En este curso vamos a usar **tres palabras**, y conviene fijar desde ahora qué quiere decir cada una:
-^  ^ Skill de conocimiento ^ Skill de procedimiento ^ Subagente ^
+  * **Skill**: lo que todo el mundo entiende por //skill//: conocimiento que se carga en la conversación. Cómo son los servicios, cómo se escriben los tests.
-| 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 un procedimiento |
+  * **Agente**: lo que todo el mundo entiende por agente: le encargas un trabajo y lo hace. Pero **lo implementamos como //skill//**, por las razones de abajo. En Claude Code, con ''context: fork'' en el frontmatter, pasa a ser un agente de verdad: se ejecuta en su propio contexto.
-| Quién la lanza | Una //skill// de procedimiento, o el modelo cuando la necesita | **Tú**, con ''/'' | La //skill// de procedimiento, en una de sus fases |
+  * **Subagente**: un agente que lanza **nuestro agente** para partir su tarea en trozos más pequeños: comprobar el test, revisar el fichero generado. Es también un agente, con su contexto vacío y su respuesta cerrada; lo que cambia es quién lo lanza.
-| 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 |
+Y cada uno se escribe y se nombra de una forma:
-| Nombre | ''k-servicios'' | ''do-crear-servicio'' | ''verificador.md'' |
-| Dónde vive | ''.claude/skills/k-servicios/'' | ''.claude/skills/do-crear-servicio/'' | ''.claude/skills/do-crear-servicio/subagents/'' |
+  * **Las //skills// se llaman ''k-''**, de //knowledge//: ''k-servicios'', ''k-tests''. Detrás del prefijo, el tema.
+  * **Los agentes se llaman ''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.
+  * **Los subagentes son un fichero markdown con su prompt** en la carpeta ''subagents/'' del agente que los lanza: ''do-crear-servicio/subagents/verificador.md''. Sin prefijo: el nombre es su rol.
+Todo en //kebab-case//.
 <sxh text;gutter:false>
@@ Línea 46: / Línea 50: @@
 </sxh>
-==== Skill de conocimiento: k- ====
+^  ^ 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/'' |
-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 las //skills// de procedimiento («carga ''k-servicios''») o el modelo cuando ve en su ''description'' que la necesita.
+Ventajas del prefijo:
-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.
+  * **No chocan con los comandos de Claude Code**, que también se lanzan con ''/''. Una //skill// llamada ''init'' o ''context'' se confunde con ''/init'' o ''/context''; ''/do-revisar-pr'' no coincide con ningún comando.
+  * **Escribiendo ''/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.
-==== Skill de procedimiento: do- ====
+==== Skill: k- ====
-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.
+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 2 del tema 8, generar los tests: **el trabajo de un agente**. Pero lo escribimos como //skill//, no como agente, por dos razones:
+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.
-  * **Un agente no tiene carpeta propia.** Es un único fichero en ''.claude/agents/'', así que sus plantillas, scripts, ejemplos y subagentes no pueden ir junto a él. Una //skill// es una carpeta y lleva dentro todo lo que usa.
+==== Agente: do- ====
-  * **Lanzarla es más corto.** En Claude Code un agente se lanza con ''agent-'' delante del nombre; una //skill//, directamente:
-<sxh bash>
+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.
-@agent-crear-servicio R-12
-/do-crear-servicio R-12
-</sxh>
-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:
+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_que_los_agentes_son_skills|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:
 <sxh yaml;title:.claude/skills/do-crear-servicio/SKILL.md>
@@ Línea 79: / Línea 85: @@
 ==== Subagente ====
-Un subagente es un trabajo cerrado **dentro de una fase** de una //skill// de procedimiento: comprobar que el test cubre el requisito, revisar el fichero generado, juzgar si cumple el checklist. Lo lanza la //skill//, no tú, y su respuesta la lee la //skill// para decidir si sigue o corrige.
+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/'' de la //skill//. **Para la herramienta ese fichero no existe**: no está en ''.claude/agents/'' ni tiene frontmatter. Es la //skill// la que dice cuándo se lanza, qué fichero lee y qué le pasa, y Claude Code arranca un subagente genérico con ese prompt:
+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:
 <sxh markdown>
@@ Línea 91: / Línea 97: @@
   * **Empieza vacío**, así que todo lo que necesita le llega en ''Entradas''. «Revisa lo que hemos hecho» no funciona.
-  * **Lo que lee muere con él**: la clase, el test, la salida de ''mvn test''. A la //skill// solo le vuelve la respuesta.
+  * **Lo que lee muere con él**: la clase, el test, la salida de ''mvn test''. Al agente solo le vuelve la respuesta.
-  * **La respuesta es cerrada**, ''PASS'' o ''FAIL'' en la primera línea, para que la //skill// la compare tal cual.
+  * **La respuesta es cerrada**, ''PASS'' o ''FAIL'' en la primera línea, para que el agente la compare tal cual.
-¿Por qué un subagente y no otra //skill// ''do-''? Porque el resultado lo necesita **la //skill// que sigue trabajando**, no tú, y porque lo que lee no tiene que llenar tu contexto. Y es un trabajo demasiado pequeño para tener su propia carpeta: va con el procedimiento que lo usa.
+Por qué va dentro del agente y no en ''.claude/agents/'' ni en su propia carpeta ''do-'', en [[#por_que_los_subagentes_van_dentro_del_agente|la sección 4]].
 <note warning>**Nunca se lanza como ''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''.</note>
@@ Línea 100: / Línea 106: @@
 ----
-===== 3. El nombre =====
+===== 3. Cuál de los tres =====
-El nombre de la //skill// (su carpeta y su ''name'') empieza por un prefijo que dice de qué tipo es:
+Tres preguntas, en este orden:
-  * **''k-''**, de //knowledge//, conocimiento en inglés: las que **saben** cosas: ''k-servicios'', ''k-tests''. Detrás del prefijo, el tema.
+  - **¿Son reglas o es una tarea?** Si son reglas (cómo se hace algo), //skill// ''k-''. Si es una tarea, sigue.
-  * **''do-''**, «hacer» en inglés: las que **hacen** cosas: ''do-crear-servicio'', ''do-revisar-pr''. Detrás del prefijo, un verbo.
+  - **¿La lanzas tú?** Si la pides tú y quieres ver cómo avanza, agente ''do-''. Si la lanza un agente en medio de su proceso, sigue.
+  - **¿El resultado es una comprobación cerrada que el agente compara?** Entonces subagente. Si el agente necesita que lo que se ha leído siga en el contexto, no es un subagente: es una fase más del ''do-''.
-Todo en //kebab-case//. Los subagentes no llevan prefijo: el fichero se llama por su rol, ''verificador.md'', ''revisor.md'', porque ya están dentro de la ''do-'' que los lanza.
+Con el ejemplo del curso:
-Ventajas del prefijo:
+  * Cómo son los servicios → ''k-servicios''.
+  * Crear un servicio a partir de un requisito → ''do-crear-servicio''.
-  * **No chocan con los comandos de Claude Code**, que también se lanzan con ''/''. Una //skill// llamada ''init'' o ''context'' se confunde con ''/init'' o ''/context''; ''/do-revisar-pr'' no coincide con ningún comando.
+  * Comprobar que el test del servicio cubre el requisito, dentro de ''do-crear-servicio'' → ''subagents/verificador.md''.
-  * **Escribiendo ''/do-'' sale todo lo que se puede lanzar**: el autocompletado enseña solo las //skills// que hacen cosas, sin las de conocimiento, que no se lanzan a mano.
 ----
-===== 4. Cuál de los tres =====
+===== 4. Por qué esta separación =====
-Tres preguntas, en este orden:
+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.
-  - **¿Son reglas o es una tarea?** Si son reglas (cómo se hace algo), ''k-''. Si es una tarea, sigue.
+==== Por qué los agentes son skills ====
-  - **¿La lanzas tú?** Si la pides tú y quieres ver cómo avanza, ''do-''. Si la lanza otra //skill// en medio de su proceso, sigue.
-  - **¿El resultado es una comprobación cerrada que la //skill// compara?** Entonces subagente. Si la //skill// necesita que lo que se ha leído siga en el contexto, no es un subagente: es una fase más de la ''do-''.
-Con el ejemplo del curso:
+  * **Un agente de la herramienta no tiene carpeta propia.** Es un único fichero en ''.claude/agents/''. Nuestros agentes llevan plantillas, scripts, ejemplos, subagentes y //evals// ([[cursos:sdd:10-creando-skills#estructura_de_carpetas_y_ficheros|la estructura]]), y todo eso tiene que ir junto para poder mantenerlo. Una //skill// es una carpeta.
+  * **Lanzarlo cuesta más.** En Claude Code un agente se lanza con ''agent-'' delante del nombre y una //skill// directamente, y ''/do-'' autocompleta solo lo que se puede lanzar:
-  * Cómo son los servicios → ''k-servicios''.
+<sxh bash>
-  * Crear un servicio a partir de un requisito → ''do-crear-servicio''.
+@agent-crear-servicio R-12
-  * Comprobar que el test del servicio cubre el requisito, dentro de ''do-crear-servicio'' → ''subagents/verificador.md''.
+/do-crear-servicio R-12
+</sxh>
+  * **Un agente se lanza solo en su conversación.** Lo normal con un trabajo cerrado es abrir una conversación, lanzar ''/do-crear-servicio R-12'', mirar el resultado y cerrarla. Eso ya es un agente ([[cursos:sdd:08-skills-agentes#un_caso_especial|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.
+  * **Vale para las dos herramientas.** OpenCode lee ''.claude/skills/'' pero no ''.claude/agents/'', y su frontmatter de agente es otro ([[cursos:sdd:03-opencode#donde_se_guardan|tema 3]]). Un agente escrito como //skill// funciona igual en Claude Code y en OpenCode; escrito como agente, hay que mantener dos ficheros.
+  * **Un solo formato que aprender.** Skill y agente tienen el mismo ''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:
+<sxh yaml;title:.claude/skills/do-revisar-pr/SKILL.md>
+---
+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
+---
+</sxh>
+<note tip>Opinión personal: que Claude Code haya ido añadiendo al frontmatter de las //skills// lo que antes era solo de los agentes, ''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.</note>
+==== Por qué los subagentes van dentro del agente ====
+  * **No son reutilizables.** El verificador de ''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.
+  * **En ''.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.
+  * **Se mantiene con el agente.** Si cambia la fase que lo lanza, cambian sus ''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.
+  * **Sí tiene que ser un agente de verdad**, con contexto vacío, porque el resultado lo necesita **el agente que sigue trabajando**, no tú, y porque lo que lee (la clase, el test, la salida de ''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í.
 ----
@@ Línea 136: / Línea 168: @@
 ==== Ejercicio 1 ====
-Di si cada cosa es una //skill// de conocimiento, una de procedimiento o un subagente, y por qué:
+Di si cada cosa es una //skill//, un agente o un subagente, y por qué:
 ^ Tarea ^ Tipo ^ Por qué ^
@@ Línea 148: / Línea 180: @@
 ==== Ejercicio 2 ====
-''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, qué fases se hacen con un subagente y qué le pasa a cada uno en ''Entradas''.
+''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''.