Diferencias

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

--- cursos:sdd:08-skills-agentes [2026/11/06 00:03] – [3. Skill o agente] Lorenzo
+++ cursos:sdd:08-skills-agentes [2026/11/06 00:11] (actual) – Ejercicios: nuevo ejercicio 2 (crear una skill y usarla en otra conversación) y ejercicio 3 (crear un agente y lanzarlo en otra conversación) claude
@@ Línea 1: / Línea 1: @@
 ====== 8. Skills y agentes ======
-Las //skills// y los agentes son los dos ficheros markdown con instrucciones, pero sirven para cosas distintas y por eso se escriben distinto. Vamos a ver qué es cada uno, cuándo se usa cada uno, dónde se guardan en OpenCode y qué partes lleva cada fichero.
+Las //skills// y los agentes son los dos ficheros markdown con instrucciones, pero sirven para cosas distintas y por eso se escriben distinto. Vamos a ver qué es cada uno, dónde se guardan en OpenCode, qué lleva su frontmatter, cuándo se usa cada uno y qué partes lleva el cuerpo de cada fichero.
 Más información:
@@ Línea 23: / Línea 23: @@
 El subagente **empieza con el contexto vacío**: solo tiene su fichero y el prompt que le escribe el principal. Al terminar, al principal solo le vuelve su respuesta.
-===== 3. Skill o agente =====
+===== 3. Dónde se guardan =====
+En OpenCode, dentro de ''.opencode/'' del proyecto (y en ''~/.config/opencode/'' para todos los proyectos: [[cursos:sdd:03-opencode#donde_se_guardan1|skills]] y [[cursos:sdd:03-opencode#donde_se_guardan|agentes]] en el tema 3):
+<sxh text;gutter:false>
+.opencode
+├── skills
+│   ├── servicios
+│   │   └── SKILL.md
+│   └── revisar-pr
+│       ├── SKILL.md
+│       └── checklist.md
+└── agents
+    ├── revisor-tests.md
+    └── verificador-spec.md
+</sxh>
+  * **Cada //skill// va en su propia carpeta**, con el nombre de la //skill//, y dentro el fichero se llama siempre ''SKILL.md''. La carpeta es suya: puede llevar al lado los ficheros que use (''checklist.md'').
+  * **Todos los agentes van en una única carpeta**, ''.opencode/agents/'', un fichero ''.md'' por agente. **El nombre del agente es el del fichero**: ''revisor-tests.md'' es el agente ''revisor-tests''.
+<note warning>**En ''.opencode/agents/'' no se deja ningún otro ''.md''.** OpenCode convierte en agente todo ''.md'' que haya ahí, también en subcarpetas: una plantilla ''agents/plantillas/informe.md'' aparece como el agente ''plantillas/informe''.</note>
+----
+===== 4. El frontmatter =====
+Los dos ficheros empiezan con una **cabecera en YAML entre dos líneas ''%%---%%''**, el //frontmatter//. Detrás va el cuerpo en markdown.
+<sxh yaml;title:.opencode/skills/servicios/SKILL.md>
+---
+name: servicios
+description: Convenciones de los servicios de Pedidos (transacciones, validación,
+  errores de negocio). Usar al escribir, revisar o probar una clase *Service.
+---
+</sxh>
+<sxh yaml;title:.opencode/agents/revisor-tests.md>
+---
+description: Revisa los tests de una clase de servicio y dice qué falta o está mal.
+  Usar después de escribir o cambiar los tests de una clase *Service, antes del commit.
+mode: subagent
+permission:
+  edit: deny
+---
+</sxh>
+En la //skill//:
+  * ''name'': obligatorio, el mismo que el nombre de la carpeta.
+  * ''description'': obligatoria.
+En el agente no hay ''name'', porque lo da el fichero:
+  * ''description'': obligatoria.
+  * ''mode'': ''subagent'' para que solo lo lance otro agente. Si no se pone, también aparece entre los principales al pulsar ''Tab''.
+  * ''permission'': lo que no puede hacer. Un revisor con ''edit: deny'', porque si puede editar acaba arreglando en vez de revisar.
+==== La descripción ====
+**La ''description'' es lo único que el LLM lee siempre.** De todas las //skills// y agentes tiene en contexto solo el nombre y la descripción; el cuerpo no lo ve hasta que decide usarlo. Así que, si la descripción no dice **cuándo** usarlo, no lo usa nunca.
+Tiene que decir **qué hace y cuándo usarlo**, con las palabras con las que se pedirá la tarea:
+<sxh yaml>
+# ✅ qué cubre, cuándo usarla y con qué palabras se pide
+description: Convenciones de los servicios de Pedidos (transacciones, validación,
+  errores de negocio). Usar al escribir, revisar o probar una clase *Service.
+# ❌ no dice cuándo: no se carga nunca
+description: Utilidades para servicios.
+# ❌ cuenta el proceso, que va en el cuerpo, y no dice cuándo
+description: Primero lee el servicio, luego revisa las transacciones y lanza los tests.
+</sxh>
+----
+===== 5. Skill o agente =====
 ^  ^ Skill ^ Agente ^
@@ Línea 153: / Línea 230: @@
 Piensa qué tienes: un contexto vacío al que se le añade el fichero y tu mensaje, trabaja, y lo que haya acumulado desaparece al cerrar porque nadie sigue hablando ahí. **Es exactamente un agente**, con la diferencia de que el resultado se lo has dado tú al principal en vez de leerlo él. La //skill// no ha llenado nada que vayas a pagar después. Así que la pregunta de fondo no es «¿esto es una skill o un agente?», sino «**¿voy a seguir trabajando en esta conversación con lo que quede en el contexto?**». Si no, da igual cuál de los dos uses.
-----
-===== 4. Dónde se guardan =====
-En OpenCode, dentro de ''.opencode/'' del proyecto (y en ''~/.config/opencode/'' para todos los proyectos: [[cursos:sdd:03-opencode#donde_se_guardan1|skills]] y [[cursos:sdd:03-opencode#donde_se_guardan|agentes]] en el tema 3):
-<sxh text;gutter:false>
-.opencode
-├── skills
-│   ├── servicios
-│   │   └── SKILL.md
-│   └── revisar-pr
-│       ├── SKILL.md
-│       └── checklist.md
-└── agents
-    ├── revisor-tests.md
-    └── verificador-spec.md
-</sxh>
-  * **Cada //skill// va en su propia carpeta**, con el nombre de la //skill//, y dentro el fichero se llama siempre ''SKILL.md''. La carpeta es suya: puede llevar al lado los ficheros que use (''checklist.md'').
-  * **Todos los agentes van en una única carpeta**, ''.opencode/agents/'', un fichero ''.md'' por agente. **El nombre del agente es el del fichero**: ''revisor-tests.md'' es el agente ''revisor-tests''.
-<note warning>**En ''.opencode/agents/'' no se deja ningún otro ''.md''.** OpenCode convierte en agente todo ''.md'' que haya ahí, también en subcarpetas: una plantilla ''agents/plantillas/informe.md'' aparece como el agente ''plantillas/informe''.</note>
-----
-===== 5. El frontmatter =====
-Los dos ficheros empiezan con una **cabecera en YAML entre dos líneas ''%%---%%''**, el //frontmatter//. Detrás va el cuerpo en markdown.
-<sxh yaml;title:.opencode/skills/servicios/SKILL.md>
----
-name: servicios
-description: Convenciones de los servicios de Pedidos (transacciones, validación,
-  errores de negocio). Usar al escribir, revisar o probar una clase *Service.
----
-</sxh>
-<sxh yaml;title:.opencode/agents/revisor-tests.md>
----
-description: Revisa los tests de una clase de servicio y dice qué falta o está mal.
-  Usar después de escribir o cambiar los tests de una clase *Service, antes del commit.
-mode: subagent
-permission:
-  edit: deny
----
-</sxh>
-En la //skill//:
-  * ''name'': obligatorio, el mismo que el nombre de la carpeta.
-  * ''description'': obligatoria.
-En el agente no hay ''name'', porque lo da el fichero:
-  * ''description'': obligatoria.
-  * ''mode'': ''subagent'' para que solo lo lance otro agente. Si no se pone, también aparece entre los principales al pulsar ''Tab''.
-  * ''permission'': lo que no puede hacer. Un revisor con ''edit: deny'', porque si puede editar acaba arreglando en vez de revisar.
-==== La descripción ====
-**La ''description'' es lo único que el LLM lee siempre.** De todas las //skills// y agentes tiene en contexto solo el nombre y la descripción; el cuerpo no lo ve hasta que decide usarlo. Así que, si la descripción no dice **cuándo** usarlo, no lo usa nunca.
-Tiene que decir **qué hace y cuándo usarlo**, con las palabras con las que se pedirá la tarea:
-<sxh yaml>
-# ✅ qué cubre, cuándo usarla y con qué palabras se pide
-description: Convenciones de los servicios de Pedidos (transacciones, validación,
-  errores de negocio). Usar al escribir, revisar o probar una clase *Service.
-# ❌ no dice cuándo: no se carga nunca
-description: Utilidades para servicios.
-# ❌ cuenta el proceso, que va en el cuerpo, y no dice cuándo
-description: Primero lee el servicio, luego revisa las transacciones y lanza los tests.
-</sxh>
 ----
@@ Línea 339: / Línea 339: @@
 | Comprobar que cada requisito de ''specs/pedidos.md'' tiene un test | | |
 | Cómo se escribe un mensaje de commit en el equipo | | |
-| Revisar el servicio que acaba de escribir Build | | |
+| Revisar el servicio que se acaba de escribir | | |
 ==== Ejercicio 2 ====
-Escribe el agente ''.opencode/agents/revisor-dtos.md'', que comprueba que ningún controlador devuelve una entidad JPA. Tiene que tener el frontmatter con ''description'', ''mode'' y ''permission'', y las secciones ''Entradas'', ''Proceso'' y ''Salida'' con ''PASS''/''FAIL'' y el formato ''fichero:inicio-fin:descripcion''. Lánzalo desde Build con ''@revisor-dtos'' sobre un controlador que devuelva una entidad y comprueba que responde ''FAIL'' con la línea correcta.
+Escribe la //skill// ''.opencode/skills/controladores-rest/SKILL.md'' con las convenciones de los controladores REST del proyecto: un controlador por agregado, rutas en plural (''/pedidos''), nunca devuelve una entidad JPA sino un DTO, y los errores de negocio se devuelven con ''409'' y el código del requisito. Pon una ''description'' que diga cuándo usarla.
+Abre **una conversación nueva** y pide «crea el controlador de ''Cliente''», sin nombrar la //skill//. Comprueba que la ha cargado y que el controlador cumple las cuatro reglas.
+==== Ejercicio 3 ====
+Escribe el agente ''.opencode/agents/revisor-dtos.md'', que comprueba que ningún controlador devuelve una entidad JPA. Tiene que tener el frontmatter con ''description'', ''mode'' y ''permission'', y las secciones ''Entradas'', ''Proceso'' y ''Salida'' con ''PASS''/''FAIL'' y el formato ''fichero:inicio-fin:descripcion''.
+Abre **una conversación nueva** y lánzalo con ''@revisor-dtos'' sobre un controlador que devuelva una entidad. Comprueba que responde ''FAIL'' con la línea correcta y que en tu conversación solo ha quedado esa respuesta, no el controlador que ha leído.