logongas

Herramientas de usuario

Herramientas del sitio

Ocultar Menú
Traza: • 8. Skills y agentes
cursos:sdd:08-skills-agentes

Diferencias

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

Enlace a la vista de comparación

Ambos lados, revisión anteriorRevisión previa
Próxima revisión		Revisión previa
cursos:sdd:08-skills-agentes [2026/11/05 22:23] – Renumera el tema y sus referencias tras añadir el tema 7 (AGENTS.md) claudecursos:sdd:08-skills-agentes [2026/11/06 08:37] (actual) – Renumerar el curso: Estructura de un skill pasa al 10 y los temas siguientes suben un número claude
Línea 1: Línea 1:
 ====== 8. Skills y agentes ====== ====== 8. Skills y agentes ======
  
-Qué es una //skill// y qué es un subagente en dos líneas está en Conceptos básicos ([[cursos:sdd:02-conceptos-basicos#skills|skills]], [[cursos:sdd:02-conceptos-basicos#subagentes|subagentes]]); cómo se lanzan y dónde se guardan, en [[cursos:sdd:03-opencode#skills|OpenCode]] y [[cursos:sdd:04-claude-code#skills|Claude Code]]. Aquí, cómo se escriben las dos, qué va en una //skill// y qué en un agente, y cómo se reparte el conocimiento del proyecto entre ''AGENTS.md'' y las //skills//.+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:
- +
-===== 1. Qué es una skill ===== +
- +
-Una //skill// es una carpeta con un fichero de instrucciones que le dice al agente **cómo se hace** una tarea concreta en tu equipo. No es código: es contexto empaquetado y versionado. +
- +
-<sxh text;gutter:false> +
-.opencode +
-└── skills +
-    └── revisar-pr +
-        ├── SKILL.md          <- las instrucciones +
-        └── checklist.md      <- material de apoyo, se carga solo si hace falta +
-</sxh> +
- +
-<sxh markdown;title:.claude/skills/revisar-pr/SKILL.md> +
---- +
-name: revisar-pr +
-description: Revisa un pull request con el checklist del equipo. Usar cuando se pida revisar un PR, unos cambios o un diff. +
---- +
- +
-# Revisión de pull request +
- +
-1. Leer la descripción del PR y comprobar que hay una issue enlazada. +
-2. Revisar contra checklist.md, en ese orden. +
-3. Clasificar cada hallazgo: bloqueante, recomendable o nota. +
-4. No comentar estilo: de eso ya se encarga el formateador. +
-</sxh> +
- +
-Lo que hace que esto escale es **cómo se cargan**: de todas las //skills// instaladas, el agente lleva siempre en contexto solo el nombre y la descripción —dos líneas—, y el cuerpo entra únicamente cuando la tarea encaja. Por eso se pueden tener veinte sin llenar la ventana de contexto. +
- +
-La **descripción** es lo único que el modelo lee para decidir si la usa: [[#el_frontmatter|cómo se escribe]]. +
- +
-Dónde viven: +
- +
-  * ''.claude/skills/'' **en el proyecto**: viajan en el repositorio, se revisan en el PR y valen para todo el equipo. Es el caso normal. OpenCode también lee esta carpeta, así que una sola vale para las dos herramientas. +
-  * ''~/.claude/skills/'' **en tu casa**: tus manías, en todos los proyectos. +
- +
-Los comandos ''/kiro-*'' de [[cursos:sdd:19-kiro|Kiro]] son exactamente esto: cc-sdd instala el flujo SDD completo como //skills// dentro del proyecto.+
  
-**Cuándo escribir una**: cuando algo se repite y sale distinto cada vez, cuando hay un procedimiento del equipo que hoy solo está en la cabeza de alguien, o para el detalle del proyecto que solo hace falta en algunas tareas ([[#pequenoel_detalle_va_en_skills|AGENTS.md pequeño]]). Lo que no puede hacer una //skill// es **actuar**: solo guía cómo se actúa.+  * [[https://opencode.ai/docs/skills/|OpenCode: skills]]: dónde busca las //skills// y qué campos lleva su frontmatter. 
 +  * [[https://opencode.ai/docs/agents/|OpenCode: agents]]: agentes principales y subagentes, y todos los campos del frontmatter. 
 +  * [[https://agentskills.io/specification|Specification - Agent Skills]]: el estándar de las //skills//.
  
 ---- ----
  
-===== 2. Cómo se escribe una skill =====+===== 1. Qué es una skill =====
  
-==== El frontmatter ====+Una //skill// es un fichero ''SKILL.md'' con lo que el agente tiene que **saber** o **hacer** para una tarea concreta: cómo son los servicios, cómo se revisa un PR, cómo se crea un endpoint o como se hacen los test.
  
-Dos campos, los dos obligatorios:+Se carga **dentro de tu conversación**: el agente lee el skill y sigue trabajando con esas instrucciones. Es decir, llamar a un skill añade más prompt a tu conversación (contexto).,
  
-  * ''name'': el mismo que el nombre de la carpeta. +===== 2. Agente principal y subagentes =====
-  * ''description'': **qué hace y cuándo usarla**, en tercera persona y con las palabras con las que se pedirá la tarea. Es lo único que el modelo lee siempre: con ella decide si la carga. El proceso no va aquí, va en el cuerpo. Máximo 1.024 caracteres.+
  
-<sxh yaml> +Un agente es un fichero con las instrucciones para **hacer un trabajo cerrado y devolver un resultado**. En OpenCode, Plan y Build son los agentes //principales//, los que hablan contigo; los que escribimos nosotros son casi siempre **subagentes**: los lanza el principal ([[cursos:sdd:02-conceptos-basicos#subagentes|qué es un subagente]]).
-# ✅ 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 +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.
-description: Utilidades para servicios.+
  
-# ❌ cuenta el proceso, que va en el cuerpo, y no dice cuándo +===== 3. Dónde se guardan =====
-description: Primero lee el servicio, luego revisa las transacciones y lanza los tests. +
-</sxh>+
  
-==== La carpeta ==== +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):
- +
-Solo el ''SKILL.md'' es obligatorio; cada carpeta aparece únicamente si la //skill// tiene ese tipo de contenido.+
  
 <sxh text;gutter:false> <sxh text;gutter:false>
 .opencode .opencode
-└── skills +├── skills 
-    └── servicios +│   ├── servicios 
-        ├── SKILL.md          <- obligatorio: las reglas y el índice de los demás ficheros +│   │   └── SKILL.md 
-        ├── transacciones.md  <- un tema que solo hace falta a veces +│   └── revisar-pr 
-        ├── templates/        <- texto literal para copiar y rellenar +│       ├── SKILL.md 
-        ├── examples/         <- casos resueltos, para ver el resultado +│       └── checklist.md 
-        ├── references/       <- documentación de terceros copiada tal cual +└── agents 
-        └── scripts/          <- código que se ejecuta, no se lee+    ├── revisor-tests.md 
 +    └── verificador-spec.md
 </sxh> </sxh>
  
-  * **''<tema>.md''**: lo que solo hace falta en algunas tareas sale del ''SKILL.md'' a su fichero, que se carga solo cuando la tarea toca ese tema. +  * **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''). 
-  * **''templates/''**: un fichero con estructura fija se da como plantilla literal; descrito en prosa, el modelo se inventa el formato. +  * **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''. 
-  * **''examples/''**: un caso resuelto entero. No es normativo: una regla que solo está en un ejemplo no es una regla. + 
-  * **''references/''**: la documentación de una librería sin adaptar. La regla del proyecto va en la raíz y apunta aquí. +<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> 
-  * **''scripts/''**: ver [[#scripts|scripts]].+ 
 +----
  
-==== El SKILL.md ====+===== 4. El frontmatter =====
  
-Detrás del frontmatter, una frase de qué cubre y, si hay más ficheros, **la tabla índice**: cada fichero con **qué contiene**. Un fichero que no está en la tabla no lo lee nadie.+Los dos ficheros empiezan con una **cabecera en YAML entre dos líneas ''%%---%%''**, el //frontmatter//. Detrás va el cuerpo en markdown.
  
-<sxh markdown;title:.claude/skills/servicios/SKILL.md>+<sxh yaml;title:.opencode/skills/servicios/SKILL.md>
 --- ---
 name: servicios name: servicios
Línea 99: Línea 57:
   errores de negocio). Usar al escribir, revisar o probar una clase *Service.   errores de negocio). Usar al escribir, revisar o probar una clase *Service.
 --- ---
 +</sxh>
  
-# servicios+<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>
  
-Reglas de las clases `*Service` del servidor.+En la //skill//:
  
-## Índice+  * ''name'': obligatorio, el mismo que el nombre de la carpeta. 
 +  * ''description'': obligatoria.
  
-| Fichero | Qué contiene | +En el agente no hay ''name'', porque lo da el fichero:
-|---|---| +
-| `transacciones.md` | Qué métodos son transaccionales y cómo | +
-| `templates/service.java` | Esqueleto de un servicio nuevo |+
  
-## Convenciones+  * ''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.
  
-- Un servicio por agregado: `PedidoService`, no `PedidoLineaService`. +==== La descripción ====
-- Valida al entrar y lanza `ErrorDeNegocio` con el código de `specs/`. +
-- No devuelve entidades: devuelve DTOs.+
  
-## Ejemplos+**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.
  
-- ✅ `throw new ErrorDeNegocio("R-12", "El pedido ya está enviado")` +Tiene que decir **qué hace y cuándo usarlo**, con las palabras con las que se pedirá la tarea:
-- ❌ `throw new IllegalStateException("No se puede")` (no dice qué requisito incumple)+
  
-## Nunca+<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.
  
-- Llamar a un repositorio de otro agregado: se pasa por su servicio. +# ❌ no dice cuándo: no se carga nunca 
-</sxh>+description: Utilidades para servicios.
  
-==== Cómo se redacta ==== +# ❌ 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.
-Una //skill// se lee **para el modelo**, no para una persona, y cada línea cuesta tokens cada vez que se carga. +
- +
-  * **La prueba de cada línea**: ¿cambiaría lo que hace el modelo si la quito? Si no, sobra. +
-  * **Nada que ya sepa**: qué es JPA o cómo funciona git. Solo lo propio del proyecto. +
-  * **Nada que se deduzca del código**: la lista de clases o de paquetes se queda vieja; se dice dónde mirarla. +
-  * **Listas, no párrafos**: una regla o un paso por punto. +
-  * **Ejemplos ✅/❌**, y cada ❌ con su porqué entre paréntesis. Si una regla cabe en un ejemplo, va como ejemplo. +
-  * **Números, no adjetivos**: «máximo 3 intentos», no «unos pocos». +
-  * **''MUST'' y ''MUST NOT'' solo en lo que de verdad no puede fallar**: si están por todas partes, dejan de pesar. +
-  * **Cada regla en un solo fichero**: los demás la citan con un puntero, no la repiten. +
-  * **Máximo unas 2.500 palabras por fichero**: si pasa, se parte por temas. +
- +
-==== Scripts ==== +
- +
-Lo que es determinista (validar un fichero, calcular una tabla, contar) va en un script de ''scripts/'': es más fiable que pedírselo al modelo y no gasta contexto, porque solo entra su salida. Lo pueden ejecutar la //skill// y un [[#agente_principal_y_subagentes|agente]]. +
- +
-  * Se cita con **el comando exacto** y la palabra «ejecuta». +
-<sxh markdown> +
-✅ Ejecuta `python3 .claude/skills/servicios/scripts/sin-transaccion.py src/main/java`. +
-❌ Lee scripts/sin-transaccion.py y haz lo que dice. (un script se ejecuta, no se lee) +
-❌ Usa el script de transacciones. (sin el comando, el modelo se inventa los argumentos)+
 </sxh> </sxh>
-  * **Los errores dicen cómo arreglarlo**: el modelo corrige a partir de ese texto. 
-  * **Lo que necesita** (intérprete, librerías) se dice en el ''SKILL.md''. 
  
 ---- ----
  
-===== 3. AGENTS.md =====+===== 5. Skill o agente ===== 
 + 
 +^  ^ Skill ^ Agente ^ 
 +| Dónde trabaja | En tu conversación | En un contexto nuevo, vacío | 
 +| Qué ve | Todo lo que habéis hablado | Solo su fichero y el prompt que le pasan | 
 +| Qué queda en tu contexto | Todo lo que lee y hace | Solo su respuesta | 
 +| Para qué | Saber cómo se hace algo en el proyecto o seguir un procedimiento contigo | Encargar un trabajo y recibir un resultado |
  
-''AGENTS.md'' es un markdown en la raíz del repositorio con las instrucciones fijas del proyecto: lo que le contarías a un compañero nuevo el primer día. **Se carga entero en todas las sesiones**, encaje o no con la tarea. Es un [[https://agents.md/|estándar abierto]]: el mismo fichero lo leen Claude Code, OpenCode, Codex, Cursor, Copilot o Gemini CLI.+Como ya hemos visto en ambos casos hay unas instrucciones que son lo que llevan en su fichero.
  
-==== Pequeño: el detalle va en skills ====+<note tip> 
 +La única diferencia real entre skill y agente es que el agente lanza un nuevo "proceso" con un nuevo contexto que está vacio al que se le añade el contenido de su fichero mientras que en un skill el contenido de su fichero se añade a la conversación actual (al agente actual). 
 +</note>
  
-Como se paga en cada petición, ''AGENTS.md'' tiene que ser **pequeño**: solo lo imprescindible y un índice. El detalle se reparte en [[#que_es_una_skill|skills]], una por tema, y el agente carga solo la que necesita para la tarea.+Y ahora viene lo más interesante: en una //skill// y en un agente se puede poner **exactamente lo mismo** en el fichero, pero como cambia dónde se carga, el resultado no es el mismo. Para verlo vamos a coger dos ejemplos, uno que debería ser //skill// y otro que debería ser agente, y a escribir cada uno de las dos formas. Son cuatro ficheros:
  
 <sxh text;gutter:false> <sxh text;gutter:false>
-AGENTS.md 
 .opencode .opencode
-└── skills +├── skills 
-    ├── producto +│   ├── repository-jpa 
-    │   └── SKILL.md +│   │   └── SKILL.md 
-    ├── tecnologia +│   └── generar-tests 
-    │   └── SKILL.md +│       └── SKILL.md 
-    ├── arquitectura +└── agents 
-    │   ├── SKILL.md +    ├── repository-jpa.md 
-    │   ├── cliente.md +    └── generar-tests.md
-    │   └── servidor.md +
-    └── despliegue +
-        ├── SKILL.md +
-        ├── desarrollo.md +
-        └── produccion.md+
 </sxh> </sxh>
  
-Las que tiene que haber como mínimo:+**Ejemplo 1: cómo se hace un ''Repository'' con JPA.** El fichero dice **cómo se hace algo** en el proyecto. Es conocimiento que se usa mientras se programa. La //skill// y el agente llevan el mismo cuerpo; solo cambia el frontmatter:
  
-  * ''producto'': para qué sirve el producto, qué valor aporta y sus capacidades principales. +<sxh yaml;title:.opencode/skills/repository-jpa/SKILL.md>
-  * ''tecnologia'': el stack, los frameworks, las decisiones técnicas y las restricciones del sistema completo. +
-  * ''arquitectura'': organización de directorios, patrones de arquitectura y convenciones de nombres. +
-  * ''despliegue'': cómo se despliega la aplicación, lo común a todos los entornos. +
- +
-Si hay varias arquitecturas, el ''SKILL.md'' se queda con lo común y cada una va en un fichero de apoyo dentro de la //skill//: ''cliente.md'', ''servidor.md'', ''movil.md''. Con el despliegue igual: ''desarrollo.md'' y ''produccion.md'' con lo propio de cada entorno. +
- +
-<sxh markdown;title:.claude/skills/arquitectura/SKILL.md>+
 --- ---
-name: arquitectura +name: repository-jpa 
-description: Carpetas, patrones y nombres del proyecto. Usar antes de crear +description: Cómo se escriben los repositorios JPA de este proyecto. Usar al crear 
-  cualquier clase o fichero.+  o modificar una interfaz *Repository.
 --- ---
  
-# Arquitectura+# Repositorios JPA
  
-- Un paquete por funcionalidad (`pedidos`, `clientes`), no por capa. +- La interfaz extiende `JpaRepository<Entidad, Long>` y se llama `<Entidad>Repository`. 
-- Los controladores solo validan y delegan: la lógica va en los servicios. +- Los métodos derivados se llaman `findBy...`; si la consulta no sale con el nombre, 
- +  se escribe con `@Query` en JPQL. Nunca SQL nativo. 
-Lee además `servidor.md` si tocas `servidor/` y `cliente.md` si tocas `cliente/`.+- Las búsquedas que pueden devolver muchas filas reciben `Pageable` y devuelven `Page<Entidad>`. 
 +- Las consultas usan `JOIN FETCH` para las relaciones que se van a leer.
 </sxh> </sxh>
  
-''AGENTS.md'' dice **cuándo** usar cada una:+<sxh yaml;title:.opencode/agents/repository-jpa.md> 
 +--- 
 +description: Cómo se escriben los repositorios JPA de este proyecto. Usar al crear 
 +  o modificar una interfaz *Repository. 
 +mode: subagent 
 +---
  
-<sxh markdown;title:AGENTS.md> +# Repositorios JPA
-# Pedidos+
  
-API REST de pedidos con cliente web. Compilar y probar: `./mvnw verify`. +- La interfaz extiende `JpaRepository<Entidad, Long>` y se llama `<Entidad>Repository`. 
- +- Los métodos derivados se llaman `findBy...`; si la consulta no sale con el nombre, 
-## Skills del proyecto +  se escribe con `@Query` en JPQL. Nunca SQL nativo. 
- +- Las búsquedas que pueden devolver muchas filas reciben `Pageable` y devuelven `Page<Entidad>`. 
-Antes de empezar, lee la skill que necesite la tarea: +- Las consultas usan `JOIN FETCH` para las relaciones que se van a leer.
- +
-- `.claude/skills/producto/SKILL.md`: antes de escribir o revisar una especificación. +
-- `.claude/skills/tecnologia/SKILL.md`: antes de añadir una dependencia. +
-- `.claude/skills/arquitectura/SKILL.md`: antes de crear cualquier clase o fichero. +
-- `.claude/skills/despliegue/SKILL.md`: antes de tocar el despliegue.+
 </sxh> </sxh>
  
-<note important>**La //skill// sola no basta.** El agente la carga solo si decide que encaja con la tarea, y muchas veces no lo decide: en las [[https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals|pruebas de Vercel]] no llegó a usarse en más de la mitad de los casos. El índice de ''AGENTS.md'' está siempre en contexto, así que convierte esa decisión en una instrucción. Y como da la ruta del fichero, funciona también en un agente que no sepa de //skills//.</note>+**Ejemplo 2: generar los tests de una clase.** El fichero dice **cómo hacer un trabajo cerrado** del que interesa el resultado: el test terminado y si pasa. Otra vez el mismo cuerpo en los dos:
  
-Cómo generar un primer ''AGENTS.md'' con ''/init'' y cómo mantenerlo: [[cursos:sdd:03-opencode#init|/init en OpenCode]].+<sxh yaml;title:.opencode/skills/generar-tests/SKILL.md> 
 +--- 
 +name: generar-tests 
 +description: Genera la clase de test de una clase de servicio con JUnit 5 y Mockito 
 +  y la deja pasando. Usar cuando se pida crear los tests de una clase. 
 +---
  
-==== CLAUDE.md: no usarlo ====+# Generar tests
  
-<note important>Existe también ''CLAUDE.md'', el fichero propio de Claude Code. **No lo uses**: si en una carpeta hay ''CLAUDE.md'', Claude Code lee solo ese y **deja de leer el ''AGENTS.md''** de esa misma carpeta, sin avisar. El equipo que usa otra herramienta ve unas normas y el que usa Claude Code ve otras.</note>+1. Lee la clase y apunta sus métodos públicos. 
 +2. Escribe `<Clase>Test` en `src/test/java`, con JUnit 5 y Mockito para las dependencias: 
 +   al menos un test por método público y uno por cada `ErrorDeNegocio` que lance. 
 +3. Ejecuta `mvn test -Dtest=<Clase>Test`. 
 +4. Si algún test falla, corrígelo y vuelve a ejecutar hasta que pasen todos. 
 +5. Termina diciendo el fichero creado, cuántos tests tiene y si pasan. 
 +</sxh>
  
-Como basta con que alguien cree un ''CLAUDE.md'' para que el ''AGENTS.md'' deje de valer, se añade una **regla de arquitectura** que lo impida: un test que falla si aparece alguno en el repositorio.+<sxh yaml;title:.opencode/agents/generar-tests.md> 
 +--- 
 +description: Genera la clase de test de una clase de servicio con JUnit 5 y Mockito 
 +  y la deja pasando. Usar cuando se pida crear los tests de una clase. 
 +mode: subagent 
 +---
  
-<sxh java;title:src/test/java/es/logongas/pedidos/arquitectura/SinClaudeMdTest.java> +# Generar tests
-class SinClaudeMdTest {+
  
-    @Test +1. Lee la clase y apunta sus métodos públicos. 
-    void noHayNingunClaudeMd() throws IOException { +2. Escribe `<Clase>Test` en `src/test/java`, con JUnit 5 y Mockito para las dependencias: 
-        try (Stream<Path> ficheros = Files.walk(Path.of("."))) { +   al menos un test por método público y uno por cada `ErrorDeNegocio` que lance. 
-            List<Path> claudeMd = ficheros +3. Ejecuta `mvn test -Dtest=<Clase>Test`. 
-                    .filter(f -> !f.startsWith("./target") && !f.startsWith("./.git")) +4. Si algún test falla, corrígelo y vuelve a ejecutar hasta que pasen todos. 
-                    .filter(f -> f.getFileName().toString().equalsIgnoreCase("CLAUDE.md")) +5. Termina diciendo el fichero creado, cuántos tests tiene y si pasan.
-                    .toList(); +
- +
-            assertThat(claudeMd) +
-                    .as("Las instrucciones van en AGENTS.md, no en CLAUDE.md") +
-                    .isEmpty(); +
-        } +
-    } +
-}+
 </sxh> </sxh>
  
-----+El cuerpo del fichero es el **prompt** que se carga, igual en la //skill// que en el agente: en la //skill// se añade a tu conversación y en el agente va a un contexto nuevo. Lo que escribes tú para que arranque también es lo mismo en los dos casos: para el ejemplo 1, «Crea el repository de ''Pedido'' con una consulta que busque por cliente y estado»; para el ejemplo 2, «Genera los tests de ''PedidoService''». Veamos qué pasa en cada uno de los cuatro casos.
  
-===== 4. Cómo se organiza AGENTS.md =====+==== Ejemplo 1 como skill ====
  
-La [[#agentsmd|sección 3]] dice que ''AGENTS.md'' es un índice pequeño. Aquí va qué entra en él, dónde va todo lo demás y cómo se escriben las referencias para que funcionen igual en Claude Code y en OpenCode.+Es lo que debería ser. El fichero se carga en tu conversación y el agente principal escribe ''PedidoRepository'' siguiendo esas reglas. Y las reglas **se quedan en el contexto**: cuando dos mensajes después pidas el repository de ''Cliente'' saldrá igual, sin volver a cargar nada. Es conocimiento, y el conocimiento sirve mientras se sigue trabajando.
  
-==== Qué entra ====+==== Ejemplo 1 como agente ====
  
-El agente **obedece** lo que pone el fichero: en el [[https://arxiv.org/abs/2602.11988|estudio de ETH Zurich]], cuando ''AGENTS.md'' nombra una herramienta, el agente la usa en casi todas las tareas, y si no la nombra, casi nunca. Pero el fichero encarece cada tarea más de un 20 %, y solo mejora el resultado cuando cuenta lo que no es estándar. Así que entra solo lo que vale **para todas las tareas** y **no se deduce del código**:+No pasa absolutamente nada. El principal lanza el agente, que arranca con el contexto vacío y lee su fichero. Y en ese fichero **no se le dice que haga nada**: son cuatro reglas sobre cómo son los repositorios, ni una tarea. El agente no puede crear ''PedidoRepository'' ni devolver código, porque nadie se lo ha pedido a él; lo único que puede hacer es contestar con lo que sabe, es decir, repetir sus reglas, o decir que no tiene nada que hacer. Y al terminar, las reglas **mueren con él**: a tu conversación no ha llegado nada, y tu agente principal sigue sin saber cómo se hace un repository en este proyecto.
  
-  * **Una frase** con qué es el proyecto. +En el mejor de los casos, el agente devuelve las reglas en su respuesta y el principal las usa: has pagado un proceso aparte para traer al contexto el mismo texto que la //skill// habría puesto directamente. En el peor, cada vez que el principal necesite saber cómo va un repository tendrá que lanzarlo otra vez para que vuelva a leer el mismo fichero. Conocimiento en un agente es conocimiento que nadie conserva.
-  * **Órdenes** para compilar, probar y comprobar, si no son las habituales. +
-  * **Convenciones que se apartan de lo normal**: las que el agente no adivinaría leyendo el código. +
-  * **Límites**: lo que no se hace nunca y lo que se pregunta antes. +
-  * **El índice de //skills//**, con cuándo leer cada una. +
- +
-Fuera: la descripción general del proyecto, el árbol de carpetas, la lista de dependencias y las reglas de estilo. Las tres primeras el agente las saca del propio código, y en el estudio no le ayudaron a encontrar antes los ficheros que tenía que tocar. El estilo lo impone el formateador, no un párrafo. +
- +
-<note important>**No dejes tal cual el ''AGENTS.md'' que genera ''/init''.** Mete justo lo que sobra: descripción, arquitectura y dependencias. Los ficheros generados por el modelo salen peor que los escritos a mano. Úsalo de borrador y recorta.</note> +
- +
-<sxh markdown;title:AGENTS.md> +
-# Pedidos +
- +
-API REST de pedidos con cliente web. +
- +
-## Órdenes +
-- Compilar y probar: `./mvnw verify` +
-- Solo los tests del servidor: `./mvnw -pl servidor test` +
- +
-## Convenciones +
-- Los importes son `BigDecimal` con escala 2; nunca `double`. +
-- Los errores de negocio heredan de `ErrorDeNegocio`; los controladores no lanzan `RuntimeException`. +
-- Cada requisito de `specs/` tiene al menos un test que cita su identificador (`R-12`). +
- +
-## Límites +
-- No modifiques una migración ya aplicada: crea una nueva. +
-- Pregunta antes de añadir una dependencia o de cambiar un requisito de `specs/`. +
- +
-## Skills del proyecto +
-Explora primero el código que toca la tarea. Después lee la skill que necesite: +
-- `.claude/skills/producto/SKILL.md`: antes de escribir o revisar una especificación. +
-- `.claude/skills/tecnologia/SKILL.md`: antes de añadir una dependencia. +
-- `.claude/skills/arquitectura/SKILL.md`: antes de crear cualquier clase o fichero. +
-- `.claude/skills/despliegue/SKILL.md`: antes de tocar el despliegue. +
-</sxh>+
  
-Cabe en una pantalla, y así tiene que seguir: **menos de 200 líneas**, mejor menos de 60. Cada instrucción de más hace que el modelo cumpla peor todas las demás, no solo la nueva.+==== Ejemplo 2 como agente ====
  
-==== Dónde va lo demás ====+Es lo que debería ser. El principal lanza el agente con «Genera los tests de ''PedidoService''», y el agente, en su contexto, lee la clase, escribe ''PedidoServiceTest'', lanza ''mvn test'', lee la salida, corrige el test que falla, lo vuelve a lanzar... y al terminar devuelve una respuesta: «''PedidoServiceTest.java'' con 6 tests, todos pasan». A tu conversación llega **solo esa línea**. Todo lo que ha leído y todas las vueltas que ha dado se han quedado en su contexto, que desaparece.
  
-^ Qué es ^ Dónde va ^ Ejemplo ^ +==== Ejemplo 2 como skill ====
-| Lo que vale en todas las tareas | ''AGENTS.md'' raíz | «Los importes son ''BigDecimal''» | +
-| Lo que vale solo en una carpeta | ''AGENTS.md'' de esa carpeta | ''servidor/src/test/AGENTS.md'': «los tests de integración crean los pedidos con ''PedidoFactory''; no se mockea el repositorio» | +
-| El detalle que solo hace falta en algunas tareas | Una //skill// | ''arquitectura'', ''despliegue'' | +
-| Un procedimiento que se lanza para una tarea concreta | Una //skill// | ''revisar-pr'' | +
-| Lo que tiene que cumplirse siempre | Un test, el linter o un //hook// | ''SinClaudeMdTest'', el formateador |+
  
-  * **''AGENTS.md'' por carpeta**: Claude Code y OpenCode lo cargan cuando el agente trabaja con ficheros de esa carpeta. Solo se crea si sus normas difieren de las de la raíz, y **no puede contradecirla**: cada herramienta los junta en un orden distinto, así que no está claro cuál gana. +El trabajo también se hace, y se hace igual de bien: el principal carga el fichero y hace lo mismo que haría el agente. La diferencia es **dónde se queda todo eso**: la clase leída, el test escrito, la salida de ''mvn test'' con su traza de error, el test corregido, la segunda salida... todo en tu conversación, cuando a ti solo te interesaba el resultado. Y ese relleno **se paga en cada mensaje que viene después**: en cada turno se vuelve a enviar el contexto entero, así que cuantos más tokens hay dentro, más caro sale cada mensaje nuevo y antes se llena el contexto, que es lo que hace que el modelo empiece a olvidar lo del principio.
-  * **Lo que tiene que cumplirse siempre** no va en ''AGENTS.md'': ahí es una petición, no una garantía. Si de verdad no puede fallar, un test que lo compruebe, como el de la [[#claudemdno_usarlo|regla de ''CLAUDE.md'']].+
  
-==== Cómo se escriben las referencias ==== 
  
-Cada referencia lleva **la ruta entre comillas invertidas** y **cuándo leerla**. Nunca con ''@'':+==== Resumen ====
  
-^ Referencia ^ Claude Code ^ OpenCode ^ +^  ^ Como skill ^ Como agente ^ 
-| ''`.claude/skills/arquitectura/SKILL.md`: antes de crear cualquier clase o fichero.'' | La lee cuando la tarea lo pide | La lee cuando la tarea lo pide | +| Ejemplo 1: cómo se hace un repository JPA | ✓ Las reglas se quedan y valen para el resto de la conversación | No hay nada que hacer: el fichero son reglas, no una tarea. Como mucho las recita, y mueren con él | 
-| ''@.claude/skills/arquitectura/SKILL.md'' | La carga entera al arrancar, en todas las sesiones | No la entiende: es texto | +| Ejemplo 2: generar los tests de una clase | Funciona, pero los ficheros leídos, las salidas de ''mvn test'' y los reintentos se quedan en tu contexto y se gastan más tokens (Más dinero) | ✓ Se hace la misma tareas y solo devuelve el resultado al contexto principal |
-| ''Ver la skill de arquitectura.'' | No sabe cuándo leerla | No sabe cuándo leerla |+
  
-<note warning>**El ''@'' anula el índice.** En Claude Code, ''@ruta'' importa el fichero al arrancar, así que un índice escrito con ''@'' carga todas las //skills// en cada sesión: lo mismo que meterlas en ''AGENTS.md''. El ejemplo de la [[https://opencode.ai/docs/rules/|documentación de OpenCode]] usa ''@'' y en Claude Code hace justo eso.</note>+==== Un caso especial ====
  
-La condición se escribe con **las palabras con las que se pedirá la tarea** («antes de escribir o revisar una especificación»), sin «MUST» ni mayúsculas. En la [[https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals|prueba de Vercel]], «explora primero el proyecto y luego usa la //skill//» acertó más que «debes usar la //skill//»: con la orden tajante, el agente leía la documentación primero, seguía sus ejemplos sin mirar el proyecto y se dejaba cambios.+¿Y si lanzas como //skill// algo que debería ser agente, el generador de tests, **nada más empezar la conversación**, y cuando acaba cierras la conversación?
  
-Lo mismo vale para la ''description'' de cada //skill// ([[#el_frontmatter|el frontmatter]]): las //skills// se activan casi por palabra clave. En la [[https://scottspence.com/posts/measuring-claude-code-skill-activation-with-sandboxed-evals|medición de Scott Spence]], con la palabra en el prompt se activaban casi siempre; con una forma genérica de pedirlo, entre un 20 y un 40 % de las veces.+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.
  
 ---- ----
  
-===== 5. Agente principal y subagentes =====+===== 6. El SKILL.md =====
  
-En este curso los agentes aparecen de dos formas:+Una //skill// **no lleva entradas ni salida**: trabaja dentro de tu conversación, así que ya ve lo que has pedido, y lo que hace se queda ahí. El cuerpo es solo **lo que tiene que saber o hacer**:
  
-  * **El agente principal**: el que habla contigo. En [[cursos:sdd:03-opencode|OpenCode]], Plan y Build; en [[cursos:sdd:04-claude-code|Claude Code]], la propia sesión. +<sxh markdown;title:.opencode/skills/servicios/SKILL.md> 
-  * **Los subagentes**: agentes especializados que el principal lanza para un trozo del trabajo, cada uno con **su propia ventana de contexto**, sus herramientas y sus instrucciones. Esa ventana propia es la razón de fondo para usarlos, más que el paralelismo: es lo que permite abarcar un problema que no cabría en una sola conversación ([[cursos:sdd:12-patrones-agenticos#orquestador|patrón orquestador]]).+--- 
 +name: servicios 
 +description: Convenciones de los servicios de Pedidos (transacciones, validación, 
 +  errores de negocio). Usar al escribir, revisar o probar una clase *Service. 
 +---
  
-----+# servicios
  
-===== 6. Skill o agente =====+Reglas de las clases `*Service` del servidor.
  
-Una //skill// y un agente son los dos un markdown con frontmatter, pero hacen cosas distintas: **la //skill// es el conocimiento** y **el agente organiza el trabajo**: quién lo hace, con qué herramientas, en qué orden y cuándo para. Lo decide una pregunta: **¿cambiaría si el proyecto fuera otro?** Si cambia, es conocimiento y va en una //skill//.+## Convenciones
  
-^ Qué es ^ Skill ^ Agente ^ +- Un servicio por agregado: `PedidoService`, no `PedidoLineaService`. 
-| Convenciones, patrones y vocabulario del proyecto | ✓ | | +- Valida al entrar y lanza `ErrorDeNegocio` con el código del requisito de `specs/`. 
-| Ejemplos ✅/❌, plantillas, documentación de terceros que usa más de un agente | ✓ | | +- No devuelve entidades: devuelve DTOs.
-| Procedimiento de una tarea sin delegar («cómo se revisa un PR aquí») | ✓ | | +
-| Rol, sesgo que evitar y criterio de bien o mal | | ✓ | +
-| Herramientas permitidas y modelo | | ✓ | +
-| Lanzar subagentes y juntar lo que devuelven | | ✓ | +
-| Cuándo para: límite de vueltas y condiciones de parada | | ✓ | +
-| Formato cerrado de la respuesta (''DONE'', ''BLOCKED'') | | ✓ | +
-| ''name'' y ''description'' con el **cuándo** | ✓ | ✓ | +
-| Ejecutar scripts | ✓ | ✓ |+
  
-Así que un agente no lleva las convenciones del proyecto: dice qué //skill// cargar. Tiene [[#la_carpeta_del_agente|la misma carpeta que una //skill//]], pero en ella solo va lo que usa él solo: su plantilla de salida, sus scripts, los roles de sus subagentes. Lo que vale para más de un agente va en una //skill//.+## Ejemplos
  
-<sxh markdown> +- ✅ `throw new ErrorDeNegocio("R-12", "El pedido ya está enviado")` 
-✅ Antes de revisar, carga la skill servicios. +- ❌ `throw new IllegalStateException("No se puede")` (no dice qué requisito incumple)
-❌ Los servicios lanzan ErrorDeNegocio, nunca IllegalStateException... (conocimiento: va en la skill)+
 </sxh> </sxh>
  
-<note>El procedimiento de una tarea que hace el propio agente, como ''/revisar-pr 128'', es una //skill//. En cuanto reparte el trabajo entre subagentes y junta lo que devuelven, es un agente.</note>+Cómo se organiza por dentro una //skill// grande está en [[cursos:sdd:10-creando-skills|Estructura de un skill]].
  
 ---- ----
  
-===== 7. El cuerpo del agente =====+===== 7. El fichero del agente =====
  
-Las instrucciones del agente van en **un fichero ''.md''**: arriba el frontmatter, que cambia según la herramienta ([[#crear_un_agente_en_opencode|OpenCode]], [[#crear_un_agente_en_claude_code|Claude Code]]), y debajo sus instrucciones, que son iguales en las dos. Las instrucciones llevan siempre las mismas secciones, en este orden:+Un agente sí necesita entradas y salida, porque **no ve tu conversación** y **lo que devuelve lo lee otro agente**. Así que su cuerpo lleva **siempre** estas tres secciones, en este orden:
  
-  * **Rol**: quién es y **qué sesgo evita**. Un revisor que no se fía del resumen de quien implementó. +  * **''## Entradas''**: lo que le llega en el prompt, con nombre. Es todo lo que sabe de la tarea. 
-  * **Entradas**: lo que le llega en el prompt, con nombre. +  * **''## Proceso''**: lo que tiene que hacer, en pasos numerados. 
-  * **Proceso**: pasos numerados, un verbo cada uno. +  * **''## Salida''**: qué devuelve y con qué formato exacto.
-  * **Criterios**: cuándo está bien, cuándo mal y qué hace **en la duda: fallar**. +
-  * **Salida**: formato cerrado, con las palabras exactas (''DONE'' / ''BLOCKED''). El principal compara por texto: «indícalo de alguna forma» no se puede comparar.+
  
-<sxh markdown> +<sxh markdown;title:.opencode/agents/revisor-tests.md> 
-# Verificador de tests+--- 
 +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 
 +---
  
-Comprueba que cada requisito de la spec está cubierto por un test que pasa.+# Revisor de tests
  
-## Rol +Revisas los tests de una clase. No arreglas nada: solo dices qué está mal.
-Eres un verificador. No arreglas nada: solo dices qué falta. +
-No te fíes del resumen de quien implementó: comprueba en el código.+
  
 ## Entradas ## Entradas
 +
 Te llegan en el prompt: Te llegan en el prompt:
-- `spec`: ruta del fichero de requisitos. +- `clase`: ruta de la clase que se prueba. 
-- `modulo`: módulo Maven donde están los tests.+- `test`: ruta de su clase de test.
  
 ## Proceso ## Proceso
-1. Saca los identificadores de la spec (`R-1`, `R-2`...). 
-2. Busca en `src/test` el test que cita cada uno. 
-3. Ejecuta `./mvnw -pl <modulo> test`. 
  
-## Criterios +1. Lee `clase` y apunta sus métodos públicos. 
-- OK: todos los requisitos tienen un test que lo cita y todos pasan. +2. Lee `test` y busca al menos un test por cada método público. 
-- Fallo: un requisito sin test o un test que falla. +3. Comprueba que cada test tiene aserciones y que no copia valores del código 
-- En la duda: fallo.+   de producción (el IVA escrito a mano en vez de leerlo). 
 +4. En la duda, cuéntalo como problema.
  
 ## Salida ## Salida
-Primera línea, exactamente `DONE` o `BLOCKED`. 
-Si es `BLOCKED`, una línea por problema: `R-12: sin test`. 
-</sxh> 
  
-<note important>**El subagente no ve tu conversación.** Todo lo que necesita le tiene que llegar en el prompt o estar en su fichero. «Revisa lo que hemos hablado» no funciona; «revisa ''specs/pedidos.md''» sí.</note> +La primera línea es exactamente `PASS` o `FAIL`. Con `PASS` no se escribe nada más. 
- +Con `FAIL`, debajo, una línea por problema con el formato `fichero:inicio-fin:descripcion`: 
-En el frontmatter de las dos herramientas hay tres decisiones que se toman igual: +- `fichero`: ruta relativa a la raíz del proyecto. 
- +- `inicio-fin`: las líneas donde está el problema. Si es una sola, `42-42`. 
-  * **''description''**: igual que en una //skill//, **qué hace y cuándo usarlo**: es lo que lee el principal para decidir si lo lanza ([[#el_frontmatter|cómo se escribe]]). +- `descripcion`: qué está mal, en una sola línea.
-  * **Herramientas**: solo las que necesita. Si no se limitan, **las tiene todas**: un revisor que puede editar acaba arreglando en vez de revisar. +
-  * **Modelo**: si no se pone, el del principal. Lo mecánico (verificar, contar, comprobar un formato) con el más barato: el principal no lo baja solo y gasta el caro. Lo que juzga, diseña o corrige, con el del principal. +
- +
----- +
- +
-===== 8. La carpeta del agente ===== +
- +
-Un agente es **una carpeta con la misma estructura que una //skill//**. Solo el ''AGENT.md'' es obligatorio; cada carpeta aparece únicamente si el agente tiene ese tipo de contenido. +
- +
-<sxh text;gutter:false> +
-.claude/agents/verificador-tests/ +
-├── AGENT.md                    <- obligatorio: frontmatter, instrucciones e índice de los demás ficheros +
-├── cobertura.md                <- un tema que solo hace falta a veces +
-├── agents/ +
-│   └── juez.md                 <- el rol de un subagente que lanza este agente +
-├── templates/ +
-│   └── informe.md              <- texto literal para copiar y rellenar +
-├── examples/ +
-│   └── informe-bloqueado.md    <- un caso resuelto, para ver el resultado +
-├── references/ +
-│   └── surefire-xml.md         <- documentación de terceros copiada tal cual +
-├── scripts/ +
-│   └── requisitos-sin-test.py  <- código que se ejecuta, no se lee +
-├── assets/ +
-│   └── informe.schema.json     <- ficheros que no son markdown +
-└── evals/ +
-    └── requisito-sin-test/     <- casos de prueba del propio agente+
 </sxh> </sxh>
  
-  * **''AGENT.md''**: el frontmatter y las instrucciones de la [[#el_cuerpo_del_agente|sección anterior]], y detrás de la frase de entrada la **tabla índice** de los demás ficheros. Es el **único fichero de la carpeta con ''name'' en el frontmatter**. +<note important>**Lo que no está en ''Entradas'' el agente no lo sabe.** «Revisa lo que hemos hecho» no funciona; el principal tiene que pasarle ''clase'' y ''test'' con sus rutas.</note>
-  * **''<tema>.md''**: lo que solo hace falta en algunos casos sale del ''AGENT.md'' a su fichero. ''cobertura.md'': cuándo un test que no cita el requisito por su identificador cuenta como que lo cubre. +
-  * **''agents/''**: un fichero por cada subagente que lanza, con las mismas secciones que el ''AGENT.md'' (Rol, Entradas, Proceso, Criterios, Salida) y **sin frontmatter**. ''juez.md'': el que decide los casos dudosos. El ''AGENT.md'' dice «lanza un subagente que lea ''agents/juez.md''» y le pasa sus entradas. +
-  * **''templates/''**: la salida con formato fijo, como plantilla literal. ''informe.md'': el informe ''DONE''/''BLOCKED'' con sus huecos. Descrito en prosa, el modelo se inventa el formato. +
-  * **''examples/''**: un caso resuelto entero. No es normativo: una regla que solo está en un ejemplo no es una regla. +
-  * **''references/''**: la documentación de una herramienta sin adaptar, aquí el formato de los informes XML de Surefire. La regla va en el ''AGENT.md'' y apunta aquí. +
-  * **''scripts/''**: lo determinista. ''requisitos-sin-test.py'' cruza los identificadores de la spec con los de los tests, que es más fiable que pedírselo al modelo. Se cita con el comando exacto ([[#scripts|cómo se escriben]]). +
-  * **''assets/''**: lo que usan los scripts o la salida y no es markdown: un esquema JSON, un XSD, una imagen. +
-  * **''evals/''**: los casos de prueba del agente, una carpeta por caso con el prompt que escribiría el usuario (''prompt.md''), los ficheros de partida (''fixture.sh'') y cómo se puntúa (''graders/''). Se repiten al cambiar el agente o el modelo.+
  
-La tabla índice del ''AGENT.md'' dice **cuándo cargar** cada fichero. Las rutas van **enteras desde la raíz del proyecto**: el subagente trabaja desde la raíz y no sabe dónde está su carpeta.+==== La salida: PASS o FAIL ====
  
-<sxh markdown;title:.claude/agents/verificador-tests/AGENT.md> +El agente termina con **una sola palabra en la primera línea**: ''PASS'' si todo está bien, ''FAIL'' si no. El principal compara esa palabra tal cual para decidir qué hace; con «parece que los tests están bastante bien» no puede.
-# Verificador de tests+
  
-Comprueba que cada requisito de la spec está cubierto por un test que pasa.+Con ''FAIL'', **una línea por problema** con el formato ''fichero:inicio-fin:descripcion'', que dice dónde ir a arreglarlo:
  
-## Índice +<sxh markdown> 
- +FAIL 
-| Fichero | Qué contiene | Cuándo cargarlo | +src/test/java/com/tienda/PedidoServiceTest.java:28-28:el nombre del test no cita el requisito 
-|---|---|---| +src/test/java/com/tienda/PedidoServiceTest.java:30-45:escribe 21 en vez de leer el IVA del código de producción 
-| `.claude/agents/verificador-tests/cobertura.md` | Cuándo un test cubre un requisito | Si un test no cita el identificador | +src/main/java/com/tienda/PedidoService.java:52-60:cancelar() no tiene ningún test
-| `.claude/agents/verificador-tests/agents/juez.md` | Rol del juez | Al lanzar el juez | +
-| `.claude/agents/verificador-tests/templates/informe.md` | Formato del informe | Al escribir la salida | +
- +
-## Rol +
-...+
 </sxh> </sxh>
  
-<note important>**Solo el ''AGENT.md'' lleva ''name''.** Claude Code busca agentes en todas las subcarpetas de ''.claude/agents/'' y trata como agente cualquier ''.md'' que tenga ''name'' en el frontmatter; el resto lo toma por documentación y no lo carga. Un ''agents/juez.md'' con ''name'' aparecería como un agente suelto que puede lanzar cualquiera.</note> +<sxh markdown> 
- +PASS
----- +
- +
-===== 9. Crear un agente en OpenCode ===== +
- +
-Va en ''.opencode/agents/<nombre>.md'', y **el nombre del agente es el del fichero**. ''opencode agent create'' lo crea con preguntas, pero a mano es igual de rápido. +
- +
-<note warning>**La carpeta del agente no puede ir en ''.opencode/agents/''.** OpenCode convierte en agente **todo** ''.md'' que haya ahí, también en subcarpetas: ''verificador-tests/templates/informe.md'' aparece como el agente ''verificador-tests/templates/informe''. Así que en OpenCode el agente es un fichero suelto que manda leer el ''AGENT.md'' de la carpeta de ''.claude/agents/'': una sola carpeta para las dos herramientas.</note> +
- +
-<sxh markdown;title:.opencode/agents/verificador-tests.md> +
---- +
-description: Comprueba que cada requisito de una spec tiene un test que lo cita y +
-  que pasa. Usar después de implementar una funcionalidad, antes del commit. +
-mode: subagent +
-model: anthropic/claude-haiku-5-5 +
-permission: +
-  edit: deny +
-  bash: +
-    "*": deny +
-    "./mvnw *": allow +
---- +
- +
-Antes de empezar, carga la skill requisitos. +
- +
-Lee `.claude/agents/verificador-tests/AGENT.md` y sigue sus instrucciones.+
 </sxh> </sxh>
- 
-  * **''mode''**: ''subagent'' para que solo lo lance otro agente; ''primary'' para que sea un agente principal como Plan y Build. **Si no se pone, vale para las dos cosas**: aparece entre los principales al pulsar ''Tab''. 
-  * **''model''**: con el proveedor delante, ''proveedor/modelo'', igual que en ''/models''. 
-  * **''permission''**: cada herramienta a ''allow'', ''ask'' o ''deny''. En ''bash'' se puede ir orden a orden: primero ''"*"'' y después las excepciones, porque **gana la última regla que encaja**. 
-  * **La //skill//** no se puede cargar desde el frontmatter: se le pide en la primera línea del cuerpo. 
- 
-Como principal, se pone ''mode: primary'' y se cambia a él con ''Tab'', como a Plan y Build. 
  
 ---- ----
  
-===== 10. Crear un agente en Claude Code =====+===== Ejercicios =====
  
-Va en ''.claude/agents/<nombre>/AGENT.md'', dentro de [[#la_carpeta_del_agente|su carpeta]]. Claude Code no saca el nombre del fichero ni de la carpeta, sino del campo ''name''. ''/agents'' lo crea con preguntas, pero a mano es igual de rápido.+==== Ejercicio 1 ====
  
-<sxh markdown;title:.claude/agents/verificador-tests/AGENT.md> +Di si cada tarea se hace con una //skill// o con un agente, y por qué:
---- +
-name: verificador-tests +
-description: Comprueba que cada requisito de una spec tiene un test que lo cita y +
-  que pasa. Usar después de implementar una funcionalidad, antes del commit. +
-tools: Read, Grep, Bash +
-model: haiku +
-skills: +
-  - requisitos +
----+
  
-# Verificador de tests+^ Tarea ^ Skill o agente ^ Por qué ^ 
 +| Las convenciones de los controladores REST del proyecto | | | 
 +| 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 se acaba de escribir | | |
  
-Comprueba que cada requisito de la spec está cubierto por un test que pasa.+==== Ejercicio 2 ====
  
-## Índice +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.
-... +
-</sxh>+
  
-  * **''name''**: obligatorio, el nombre con el que se lanza. +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.
-  * **''tools''**: la lista de herramientas que puede usar. +
-  * **''model''**: ''haiku'', ''sonnet'', ''opus'' o ''inherit'' (el del principal). +
-  * **''skills''**: las //skills// que se cargan **enteras** al arrancar. Así recibe el conocimiento sin llevarlo dentro.+
  
-Como principal, para que toda la sesión siga su rol y pueda coordinar a otros: +==== Ejercicio 3 ====
- +
-<sxh bash> +
-claude --agent orquestador +
-</sxh> +
- +
-----+
  
-===== Fuentes =====+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''.
  
-  * [[https://agents.md/|AGENTS.md]]: el estándar, con ejemplos y la lista de herramientas que lo leen. +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.
-  * [[https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals|AGENTS.md outperforms skills in our agent evals]]: la prueba de Vercel. Índice en ''AGENTS.md'': 100 %; //skill// sola: 53 %; //skill// con instrucción explícita: 79 %. La //skill// no llegó a usarse en el 56 % de los casos. +
-  * [[https://agentskills.io/specification|Specification - Agent Skills]]: el estándar de las //skills//: formato de ''SKILL.md'' y carga por niveles (descripción, cuerpo, ficheros de apoyo). +
-  * [[https://dreaming.press/posts/agents-md-vs-agent-skills-evals.html|AGENTS.md vs Agent Skills evals]]: lectura crítica de la prueba de Vercel. Lo que decide es dónde está el aviso de cargar la documentación (siempre en contexto o a decisión del modelo), no el formato. +
-  * [[https://scottspence.com/posts/measuring-claude-code-skill-activation-with-sandboxed-evals|Measuring Claude Code skill activation]]: otra medición. Sin ayuda, las //skills// se activan solas la mitad de las veces; cuando se activan, siempre es la correcta. +
-  * [[https://aihero.dev/a-complete-guide-to-agents-md|A complete guide to AGENTS.md]]: ''AGENTS.md'' mínimo y el detalle en ficheros enlazados por tema; qué no meter en él. +
-  * [[https://skills.cat/skills/heykvnzhao/dotfiles/agents-md-best-practices|agents-md-best-practices]]: //skill// que parte un ''AGENTS.md'' grande en un índice y un fichero por tema. +
-  * [[https://github.com/opsmill/infrahub-sdk-python/pull/609|infrahub-sdk-python PR #609]]: caso real. Un ''CLAUDE.md'' de 317 líneas pasa a un ''AGENTS.md'' de 77 más un ''AGENTS.md'' por carpeta; después el repositorio añadió //skills// para sus procedimientos. +
-  * [[https://www.humanlayer.dev/blog/writing-a-good-claude-md|Writing a good CLAUDE.md]]: por qué cada instrucción de más empeora el cumplimiento del resto, y la carpeta de documentos enlazada desde el índice. +
-  * [[https://arxiv.org/abs/2602.11988|Evaluating AGENTS.md]]: estudio de ETH Zurich. Los ficheros de contexto encarecen más de un 20 % cada tarea y en general no mejoran el resultado; sí ayudan cuando cuentan prácticas no estándar del proyecto. +
-  * [[https://code.claude.com/docs/en/memory|Claude Code: memory]]: menos de 200 líneas; los procedimientos y lo que vale solo para una parte del código, a //skills//; ''@ruta'' no ahorra contexto porque carga el fichero al arrancar. +
-  * [[https://code.claude.com/docs/en/features-overview|Claude Code: features overview]]: cuándo usar el fichero de instrucciones, //skills//, subagentes o //hooks//; el reparto «el fichero dice qué seguir y la //skill// tiene la guía». +
-  * [[https://claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more|Steering Claude Code]]: el fichero de instrucciones como índice que apunta a otros ficheros. +
-  * [[https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills|Equipping agents for the real world with Agent Skills]]: por qué las //skills// se cargan por niveles y qué pueden llevar dentro (scripts, plantillas). +
-  * [[https://opencode.ai/docs/rules/|OpenCode: rules]]: OpenCode no sigue solo las rutas que aparecen en ''AGENTS.md''; hay que decirle cuándo leer cada fichero. +
-  * [[https://opencode.ai/docs/skills/|OpenCode: skills]]: en qué carpetas busca //skills//, ''.claude/skills/'' incluida. +
-  * [[https://code.claude.com/docs/en/sub-agents|Claude Code: subagents]]: todos los campos del frontmatter, ''skills'', los subagentes anidados y la búsqueda en subcarpetas de ''.claude/agents/''. +
-  * [[https://opencode.ai/docs/agents/|OpenCode: agents]]: agentes principales y subagentes, ''mode'' y ''permission''. +
-  * [[https://dzone.com/articles/mcp-vs-skills-vs-agents|MCP vs Skills vs Agents With Scripts: Which One Should You Pick?]]+
  
cursos/sdd/08-skills-agentes.1793913808.txt.gz · Última modificación: por claude