Diferencias

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

--- cursos:sdd:09-creando-skills [2026/11/05 22:22] – borrado - editor externo (Fecha desconocida) 127.0.0.1
+++ cursos:sdd:09-creando-skills [2026/11/05 22:39] (actual) – Quitados enlaces a secciones del tema 8 que ya no existen claude
@@ Línea 1: / Línea 1: @@
+====== 9. Estructura de un skill ======
+Qué es una //skill//, su frontmatter y cómo se redacta están en [[cursos:sdd:08-skills-agentes|Skills y agentes]]. Aquí, la estructura completa de una //skill//: qué carpetas y ficheros puede tener, qué secciones lleva el ''SKILL.md'' según el tipo. Cómo se prueba está en [[cursos:sdd:20-evaluacion-skills|Evaluación de skills]].
+Más información:
+  * [[https://agentskills.io/specification|Specification - Agent Skills]]: el estándar de las //skills//: ''SKILL.md'', ficheros de apoyo y carga por niveles.
+  * [[https://code.claude.com/docs/en/skills|Claude Code: skills]]: dónde se guardan, cómo se lanzan y cómo se pasan argumentos con ''$ARGUMENTS''.
+  * [[https://github.com/github/spec-kit|GitHub Spec Kit]]: de sus comandos sale la estructura de las //skills// de procedimiento (Formato de entrada, Outline).
+  * [[https://github.com/anthropics/skills/tree/main/skills/skill-creator|skill-creator]]: la //skill// de Anthropic para crear y evaluar //skills//.
+Cada //skill// es una carpeta dentro de la carpeta de //skills// del proyecto. La carpeta en concreto depende de la herramienta:
+  * **OpenCode**: ''.opencode/skills/''.
+  * **Claude Code**: ''.claude/skills/''.
+OpenCode también lee ''.claude/skills/'', así que con esa carpeta una misma //skill// vale para las dos.
+----
+===== 1. Tipos de skills =====
+Hay dos tipos de //skills//:
+  * **Las que saben cosas**: describen las convenciones del proyecto (cómo son los servicios, cómo se escriben los tests). No hacen nada solas: las cargan otras //skills// y los agentes.
+  * **Las que hacen cosas**: ejecutan un proceso por fases (crear un servicio, revisar un PR). Las lanzas tú con ''/''.
+Lo que hace una //skill// que hace cosas es, en el fondo, el trabajo de un [[cursos:sdd:08-skills-agentes#agente_principal_y_subagentes|agente]]. Pero crear un //skill// que actúa de agente, no como agente tiene las siguientes ventajas:
+  * **Un agente no tiene carpeta propia.** Es un único fichero en ''.claude/agents/'', así que sus plantillas, scripts o ejemplos no pueden ir junto a él. Una //skill// es una carpeta y lleva dentro todo lo que usa ([[#estructura_de_carpetas_y_ficheros|ver la estructura]]).
+  * **Lanzarlo es más engorroso.** En Claude Code un agente se lanza con ''agent-'' delante del nombre; una //skill//, directamente:
+<sxh bash>
+@agent-crear-servicio R-12
+/do-crear-servicio R-12
+</sxh>
+Normalmente no hace falta convertirla en agente: lo que aporta un agente es empezar con el contexto vacío, y eso ya se consigue lanzando la //skill// en una sesión limpia, con ''/clear'' antes. Si aun así quieres que se ejecute como un agente, en Claude Code basta con ''context: fork'' en el frontmatter:
+<sxh markdown;title:.claude/skills/do-crear-servicio/SKILL.md>
+---
+name: do-crear-servicio
+description: Crea un servicio de Pedidos con su test a partir de un requisito de specs/.
+context: fork
+---
+</sxh>
+<note tip>Personalmente opino que a la diferencia entre skill y agente se le ha dado demasiado importancia cuando podrían haber sido lo mismo y solo haber incluido ''context: fork'' en los skills como ha hecho claude code.</note>
+===== 2. El nombre =====
+El nombre de la //skill// (su carpeta y su ''name'') empieza por un prefijo que dice de qué tipo es:
+  * **''k-''**, de //knowledge//, conocimiento en inglés: las que **saben** cosas. Describen las convenciones del proyecto y las cargan otras //skills// y los agentes: ''k-servicios'', ''k-tests''.
+  * **''do-''**, «hacer» en inglés: las que **hacen** cosas. Ejecutan un proceso y las lanzas tú: ''do-crear-servicio'', ''do-revisar-pr''.
+Detrás del prefijo, en //kebab-case//, el tema en las ''k-'' y un verbo en las ''do-''.
+Ventajas del prefijo:
+  * **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 las //skills// que hacen cosas, sin las de conocimiento, que no se lanzan a mano.
+===== 3. Estructura de carpetas y ficheros =====
+Una //skill// no suele ser un único ''SKILL.md'': lleva una serie de ficheros auxiliares que la organizan y que el LLM solo carga cuando los necesita, en vez de cargar la //skill// entera. Solo el ''SKILL.md'' es obligatorio; cada carpeta aparece únicamente si la //skill// tiene ese tipo de contenido.
+==== Qué hay en cada carpeta ====
+^ Carpeta o fichero ^ Contiene ^ Ejemplo ^
+| ''SKILL.md'' | Instrucciones e índice |  |
+| ''<tema>.md'' | Son ficheros extra que deberían estar en SKILL.md pero que los sacamos fuera para que el agente no tenga que leer todo si no lo necesita | transacciones.md |
+| ''agents/'' | El rol completo de un subagente que lanza la //skill//: uno por fichero. | verificador.md |
+| ''templates/'' | Plantillas literales con huecos. Es para cuando el skill debe generar algún tipo de fichero para que tenga una guia de como debe ser. | service-impl.md |
+| ''examples/'' | Ejemplo de como queda lo que tiene que generar. Un buen ejemplo siempre ayuda mucho al agente a hacer su trabajo. Mejor un buen ejemplo que una buena descripción | pedido-service.md |
+| ''references/'' | Documentación de referencia. Podría ser la documentación oficial de Spring que ponemos aqui | spring-transactional.md |
+| ''scripts/'' | Script en bash o python , etc que ejecuta el skill para hacer su tarea. Si algo se puede hacer con un script en vez de usar más tokens, es mejor crear un script. | sin-transaccion.py |
+| ''assets/'' | Esquemas, XSD, imágenes, etc | errores.schema.json |
+| ''evals/'' | Dentro hay carpetas con los test unitarios para probar el skill ([[cursos:sdd:20-evaluacion-skills|cómo se hacen]]) | update-sin-filtrar/ |
+==== Qué carpetas tiene cada tipo ====
+Las que suele tener cada [[#tipos_de_skills|tipo de skill]]:
+^ Carpeta ^ Skill de conocimiento (''k-'') ^ Skill que hace (''do-'') ^
+| ''SKILL.md'' | ✓ | ✓ |
+| ''<tema>.md'' | ✓ | |
+| ''agents/'' | | ✓ |
+| ''templates/'' | ✓ | ✓ |
+| ''examples/'' | ✓ | |
+| ''references/'' | ✓ | |
+| ''scripts/'' | ✓ | ✓ |
+| ''assets/'' | ✓ | ✓ |
+| ''evals/'' | ✓ | ✓ |
+La de conocimiento guarda lo que **se sabe**: temas, ejemplos y documentación. La que hace guarda lo que **se ejecuta**: subagentes, plantillas de lo que genera y scripts. Si una ''do-'' necesita las reglas, carga la ''k-''; no las copia.
+==== Ejemplo: k-servicios ====
+Para explicar la estructura de carpetas de un skill , lo vamos a hacer con un ejemplo de un skill que "sabe" como son los servicios en Spring [[https://anilr9.medium.com/understanding-service-in-spring-boot-a-complete-guide-with-examples-b08825e8ccd8|Understanding @Service in Spring Boot: A Complete Guide with Examples]]
+<sxh text;gutter:false>
+.claude/skills/k-servicios/
+├── SKILL.md
+├── transacciones.md
+├── templates/
+│   └── service-impl.md
+├── examples/
+│   └── pedido-service.md
+├── references/
+│   └── spring-transactional.md
+├── scripts/
+│   └── sin-transaccion.py
+└── assets/
+    └── errores.schema.json
+</sxh>
+==== Ejemplo: do-crear-servicio ====
+La //skill// que crea un servicio a partir de un requisito de ''specs/''. Las reglas de los servicios no están aquí: las carga de ''k-servicios''.
+<sxh text;gutter:false>
+.claude/skills/do-crear-servicio/
+├── SKILL.md
+├── agents/
+│   └── verificador.md
+├── templates/
+│   └── service-test.md
+└── scripts/
+    └── sin-test.py
+</sxh>
+===== 4. SKILL.md y <tema>.md =====
+En el fichero ''SKILLS.md'' está toda la explicación/descripción de lo que debe saber o hacer el skill, sin embargo no es adecuado tener ficheros demasiado largos. Por ese motivo están los ficheros ''<tema>.md'' que son simplemete secciones del fichero ''SKILLS.md'' y que se referencian desde ''SKILLS.md''.
+El motivo de hace esto es para ahorrar contexto. A veces un skill trata de varios temas relacionados. Por ejemplo, si vamos a cear un CRUD, podríamos tener un skill que sepa hacer CRUDs y en ese caso hablaría sobre controladores, servicios y repositorios. Cuando la IA está programando el controlador no necesita saber como se hace un servicio o un repositorio.
+==== La description y la frase de entrada ====
+La ''description'' del frontmatter ([[cursos:sdd:08-skills-agentes#el_frontmatter|cómo es]]) y la frase que va justo después del H1 se parecen, pero el modelo las lee en momentos distintos:
+^ ^ ''description'' ^ Frase de entrada ^
+| Cuándo la lee | Siempre: está en contexto junto con las de todas las //skills// | Solo cuando la //skill// ya está cargada |
+| Para qué | Decidir si carga la //skill// | Saber qué es y cómo actuar |
+| Qué dice | Qué es y **cuándo usarla**, con las palabras que escribiría el usuario | En las ''k-'', qué cubre y **quién la usa**. En las ''do-'', el **rol** y qué transforma en qué |
+<sxh markdown;title:.claude/skills/do-crear-servicio/SKILL.md>
+---
+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.
+---
+# do-crear-servicio
+Eres un desarrollador del servidor: conviertes un requisito de `specs/` en un `*Service` con su test.
+</sxh>
+La frase de entrada es imprescindible cuando la //skill// se ejecuta sin pasar por la ''description'':
+  * **Con ''context: fork''**: el cuerpo del ''SKILL.md'' es el prompt del subagente. Si no fija el rol, el subagente no lo tiene.
+  * **Cuando la lanzas tú con ''/do-crear-servicio''**: se carga directamente, sin que la ''description'' haya servido para elegirla.
+<note tip>Si la frase de entrada repite la ''description'', sobra. Si da el rol o dice quién la usa, se queda.</note>
+===== 5. El índice =====
+La tabla índice del ''SKILL.md'' ([[cursos:sdd:08-skills-agentes#el_skillmd|cómo es]]) va **justo después de la frase de entrada**, antes de cualquier otra sección, y tiene **todos** los ficheros:
+  * **Un fichero que no está en la tabla es un huérfano**: no lo carga nadie.
+  * **''evals/'' y ''assets/'' van como una sola fila** de carpeta: nadie los lee como instrucciones.
+  * **Cada fichero se cita además donde se usa**, diciendo cuándo cargarlo. La tabla da la visión de conjunto; la cita, el momento.
+<sxh markdown>
+✅ En la Fase 2, copia `templates/service-impl.md` y rellena los huecos.
+❌ Ver también `templates/service-impl.md`. (no dice cuándo)
+</sxh>
+  * **Todo ''.md'' de más de 100 líneas lleva su propio ''## Índice''** en las primeras 40 líneas. El modelo a veces lee solo el principio de un fichero largo: si el índice está abajo, no sabe qué hay.
+----
+===== 6. Dos tipos de skill =====
+==== Skill de conocimiento ====
+<sxh markdown;title:.claude/skills/k-servicios/SKILL.md>
+---
+name: k-servicios
+description: Convenciones de los servicios de Pedidos (transacciones, validación,
+  errores de negocio). Usar al escribir, revisar o probar una clase *Service.
+---
+# k-servicios
+Reglas de las clases `*Service` del servidor. La cargan `do-crear-servicio` y `do-revisar-pr`.
+## Índice
+| Fichero                     | Qué contiene                           |
+|-----------------------------|----------------------------------------|
+| `transacciones.md`          | Qué métodos son transaccionales y cómo |
+| `templates/service-impl.md` | Esqueleto de un servicio nuevo         |
+## 1. Conceptos clave
+<vocabulario del dominio: agregado, error de negocio...>
+## 2. Convenciones del proyecto
+<solo lo propio del proyecto, no lo del framework>
+## 3. Patrones recomendados
+<plantillas literales, o punteros a templates/>
+## 4. Ejemplos ✅/❌
+<casos correctos e incorrectos, cada ❌ con su porqué>
+## 5. Anti-patrones
+<lo que no se hace nunca y por qué>
+</sxh>
+  * **H1 igual que el ''name''.** Y nada por debajo de ''####'': si hace falta un quinto nivel, la estructura está mal.
+  * **Frase de entrada**: qué cubre y **quién la usa**, para que el modelo sepa si es la que busca.
+==== Skill de procedimiento ====
+Sigue la estructura de los comandos de [[https://github.com/github/spec-kit|Spec Kit]]:
+<sxh markdown;title:.claude/skills/do-crear-servicio/SKILL.md>
+---
+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.
+---
+# do-crear-servicio
+Eres un desarrollador del servidor: conviertes un requisito de `specs/` en un `*Service` con su test.
+## Índice
+| Fichero                     | Qué contiene                            |
+|-----------------------------|-----------------------------------------|
+| `templates/service-test.md` | Esqueleto del test del servicio         |
+| `agents/verificador.md`     | Rol del subagente que comprueba el test |
+| `scripts/sin-test.py`       | Lista los requisitos sin test           |
+| `evals/`                    | Casos de prueba de la skill             |
+## Formato de entrada
+```text
+$ARGUMENTS
+```
+You **MUST** consider the user input before proceeding (if not empty). Se espera el
+identificador del requisito (`R-12`) y, opcionalmente, el nombre del servicio.
+## Outline
+. **Leer** el requisito (Fase 1).
+. **Escribir** el servicio y su test (Fase 2).
+. **Comprobar** que el requisito tiene test y pasa (Fase 3).
+**STOP conditions**:
+- No hay ningún requisito con ese identificador → **ERROR** y detente.
+- El servicio ya existe → **STOP** y pregunta antes de sobrescribirlo.
+## 1. Fase 1 — Leer el requisito
+. Busca el identificador en `specs/`.
+. Carga la skill `k-servicios`.
+## 2. Fase 2 — Escribir el servicio
+. Escribe el servicio con la plantilla de `k-servicios`.
+. Copia `templates/service-test.md` y rellena los huecos, con el identificador del requisito en el nombre del test.
+## 3. Fase 3 — Comprobar
+. Ejecuta `python3 .claude/skills/do-crear-servicio/scripts/sin-test.py specs/ src/test/java`.
+. Lanza un subagente con model: haiku que lea `agents/verificador.md` y pásale `requisito` y `ruta_test`.
+. Ejecuta `./mvnw -pl servidor test`.
+**LIMIT**: máximo 3 vueltas de corrección; si sigue fallando, avisa con lo que queda.
+## Quick Guidelines
+- Un servicio por agregado.
+- Ningún requisito sin su test.
+- Si el requisito es ambiguo, pregunta: no lo interpretes.
+</sxh>
+Las secciones, en este orden:
+  * **Frase de entrada**: el **rol** que asume el modelo y **qué transforma en qué**.
+  * **''## Formato de entrada''**: un bloque ''text'' con ''$ARGUMENTS'', que Claude Code sustituye por lo que escribes detrás de ''/do-crear-servicio''. La línea en inglés es la de Spec Kit, tal cual, y la siguiente dice qué argumentos espera.
+  * **''## Outline''**: las fases numeradas, un verbo cada una, y al final las **''STOP conditions''**: cuándo aborta (''ERROR'') y cuándo para a preguntar (''STOP'').
+  * **Una sección por fase** del Outline, con sus pasos.
+  * **''## Quick Guidelines''**: lo esencial en **10 puntos como máximo**, al final del cuerpo.
+==== Palabras clave ====
+El cuerpo va en español, pero las palabras que marcan una orden van **en inglés y en negrita**: el modelo les da más peso que a «debes» o «es importante».
+^ Palabra ^ Para qué ^
+| ''**MUST**'' / ''**MUST NOT**'' | Obligación o prohibición absoluta |
+| ''**CRITICAL**'' | Lo que el modelo suele hacer mal aunque se le diga |
+| ''**STOP**'' | Para y pregunta al usuario |
+| ''**ERROR**'' | Aborta con un mensaje |
+| ''**LIMIT**'' | Un número máximo: preguntas, vueltas, ficheros |
+Solo en lo que de verdad no puede fallar. El resto, en imperativo y en segunda persona: «lee», «valida», no «podrías leer».
+==== Si genera un fichero: checklist y vueltas ====
+Una //skill// que escribe un fichero termina esa fase con un **checklist** que el modelo repasa antes de dar el fichero por bueno, y un **''LIMIT''** de vueltas para no quedarse corrigiendo sin fin:
+<sxh markdown>
+### Checklist del servicio
+- [ ] ¿Cada método público valida su entrada?
+- [ ] ¿Cada requisito de `specs/` tiene un test con su identificador?
+**MUST NOT** dar el servicio por terminado con algún punto sin cumplir.
+**LIMIT**: máximo 3 vueltas de corrección; si sigue fallando, avisa con lo que queda.
+</sxh>
+==== agents/: los subagentes ====
+Si una fase delega en un subagente (comprobar, revisar, juzgar), su rol va en un fichero de ''agents/'', y el ''SKILL.md'' dice cuándo lanzarlo y qué le pasa:
+<sxh markdown>
+✅ Lanza un subagente con model: haiku que lea `agents/verificador.md` y pásale `requisito` y `ruta_test`.
+❌ Lanza un subagente que lea `agents/verificador.md`. (no dice qué le pasa ni con qué modelo)
+</sxh>
+Todos los ficheros de ''agents/'' tienen las mismas secciones, en este orden:
+<sxh markdown;title:.claude/skills/do-crear-servicio/agents/verificador.md>
+# Verificador
+Comprueba que un requisito tiene su test y que el test prueba lo que pide el requisito.
+## Rol
+Revisas el trabajo de otro sin haberlo visto hacer. No le das la razón por haberlo intentado.
+## Entradas
+Te llegan en el prompt:
+- `requisito`: identificador del requisito en `specs/` (`R-12`).
+- `ruta_test`: el fichero de test que hay que comprobar.
+## Proceso
+. Lee el requisito en `specs/`.
+. Lee el test y busca el identificador en su nombre.
+. Comprueba que cada condición del requisito tiene su aserción.
+## Criterios
+- OK cuando: el test cita el requisito y comprueba todas sus condiciones.
+- Fallo cuando: falta el identificador o alguna condición no tiene aserción.
+- En la duda: fallo.
+## Salida
+La primera línea es exactamente `PASS R-12` o `FAIL R-12`; debajo, una línea por condición sin probar.
+✅ `FAIL R-12` / `Sin aserción: el pedido enviado no se puede cancelar.`
+❌ `Parece que el test está bastante bien.` (el que lo lanza no puede comparar eso)
+## Pautas
+- **MUST NOT** modificar el test: solo dice qué falta.
+</sxh>
+  * **Autocontenido**: el subagente no ha leído el ''SKILL.md'', así que no lo cita («ver SKILL.md §2»). Todo lo que usa le llega en ''## Entradas''.
+  * **Criterios explícitos**: cuándo pasa, cuándo falla y qué hace en la duda: fallar.
+  * **Salida cerrada**: palabras literales (''PASS''/''FAIL'') que la //skill// compara tal cual, no un texto libre.
+  * **Modelo barato si el rol es mecánico**: contar, comprobar un formato o que un fichero existe, con ''model: haiku''. El que juzga o diseña se queda con el modelo principal.
+<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>
+==== El siguiente paso lo lanzas tú ====
+Una //skill// de procedimiento **no lanza la siguiente** cuando decides tú cuándo se sigue: termina diciendo la orden exacta y para.
+<sxh markdown>
+✅ Servicio creado. Siguiente paso: `/do-revisar-pr`. **STOP**.
+❌ Servicio creado. Ahora lanzo do-revisar-pr. (te quita la revisión de lo generado)
+</sxh>
+===== 7. Argumentos de entrada =====
+Lo que escribes detrás de ''/do-…'' llega entero en ''$ARGUMENTS'', el bloque de ''## Formato de entrada'' ([[#skill_de_procedimiento|ver la estructura]]). Si es un solo valor (''R-12''), basta con lo que ya hay. Pero muchas //skills// reciben varias piezas, como la ''/test'' de [[clase:daw:daw-proyecto:tema06#la_skill_do-testcrear_y_reparar|Despliegue y proyecto]]:
+<sxh bash>
+/do-test unit create PedidoService
+/do-test api create Pedido: alta válida, sin cliente, cliente que no existe
+/do-test e2e repair
+</sxh>
+En ese caso, el ''## Formato de entrada'' **describe el formato pieza a pieza**: qué valores admite, si es obligatoria y qué se hace si falta. Las palabras fijas van primero y el texto libre siempre al final, porque es lo único que puede llevar espacios:
+<sxh markdown;title:.claude/skills/do-test/SKILL.md>
+---
+name: do-test
+description: Crea o repara los tests unitarios, de arquitectura, de API o E2E.
+  Usar cuando se pida escribir tests, generarlos o arreglar los que fallan.
+argument-hint: <unit|arch|api|e2e> <create|repair> [clase, reglas o escenarios]
+---
+# do-test
+Eres el responsable de los tests: los creas a partir del código o de los escenarios y reparas los que fallan.
+## Formato de entrada
+```text
+$ARGUMENTS
+```
+You **MUST** consider the user input before proceeding (if not empty). El formato es
+`<tipo> <verbo> [resto]`:
+- `tipo`: `unit`, `arch`, `api` o `e2e`. Obligatorio.
+- `verbo`: `create` o `repair`. Obligatorio.
+- `resto`: todo lo que va detrás del verbo, tal cual.
+  - `unit create`: una clase o un paquete. Si no hay, las clases de `domain` sin tests.
+  - `arch create`: las reglas de arquitectura, en castellano.
+  - `api create` y `e2e create`: los escenarios. Obligatorio.
+  - `repair`: no lleva.
+**STOP conditions**:
+- Falta el tipo o el verbo, o no es uno de los valores → **ERROR** con la forma de uso
+  y detente.
+- `api create` o `e2e create` sin escenarios → **STOP** y pide los escenarios.
+</sxh>
+  * **''argument-hint''**: lo que enseña el autocompletado al escribir ''/do-test''. Así no hay que recordar el orden de las piezas.
+  * **''resto''**: se explica para cada combinación, porque significa una cosa distinta según el verbo.
+<note important>**No uses ''$0'', ''$1''… para coger cada pieza.** Claude Code los parte por espacios, así que el texto libre (''Pedido: alta válida, sin cliente'') llega troceado. Y si falta un argumento, el ''$2'' llega al modelo escrito tal cual. Coge siempre ''$ARGUMENTS'' entero y deja que lo parta el modelo con el formato que le has dado.</note>
+<note important>**''$ARGUMENTS'' se sustituye en todo el fichero**, no solo en ''Formato de entrada''. Si una //skill// tiene que //hablar// del placeholder, como ''k-skill'', no puede escribirlo junto: lo cuenta partido («''$'' seguido de ''ARGUMENTS''»). Escrito tal cual, al cargarla aparece en su lugar lo que hayas escrito tú.</note>
+===== 8. Formato de salida =====
+Cuando una //skill// o un [[#agentslos_subagentes|subagente de agents/]] revisa algo, **la primera línea es el resultado**, una sola palabra (Puede ser la que queramos):
+  * **''PASS''**: no hay problemas. No lleva nada más.
+  * **''FAIL''**: hay problemas, y debajo va **una línea por problema**.
+Ahora lo normal es que el agente nos retorne la lista de problemas que nos ha encontrado. Esa lista obviamente debe ser texto, así que podría ser un JSON , un XML, etc.
+Pero pensar que esos formatos son demasiado estrictos, por lo que se gastarán tokens en que tenga alguno de esos formato y además puede cometer errores.
+Por ello es mejor un formato sencillo y facil de leer.
+Mi recomendación es simplemente columnas separadas por ":" con un formato libre al final.
+Ejemplos de ellos podrían ser:
+^ Formato ^ Cuándo ^
+| ''fichero:linea:descripcion'' | El problema está en una línea |
+| ''fichero:inicio-fin:descripcion'' | Abarca varias líneas: un método, un bloque |
+| ''fichero:descripcion'' | Afecta al fichero entero |
+| ''fichero:linea:tipo:descripcion'' | En una línea, con su tipo |
+| ''fichero:inicio-fin:tipo:descripcion'' | En varias líneas, con su tipo |
+| ''fichero:tipo:descripcion'' | En el fichero entero, con su tipo |
+| ''paquete.Clase.metodo:descripcion'' | Es de un método: ''com.tienda.PedidoService.crear'' |
+| ''paquete.Clase:descripcion'' | Es de la clase entera |
+| ''paquete.Clase.metodo:tipo:descripcion'' | De un método, con su tipo |
+| ''requisito:descripcion'' | Es de un requisito de ''specs/'': ''R-12'' |
+Según lo que haga cada agente debes elegir el formato que más se acople a tu problema.
+Lo mismo pasa con el tipo. A modo de ejemplo te indico posibles valores:
+^ Agente ^ Valores ^ Qué miden ^
+| Codex (''codex review'') | ''P0'', ''P1'', ''P2'', ''P3'' | Prioridad: ''P0'' bloquea el despliegue, ''P1'' es urgente |
+| ''pr-review-toolkit'' (plugin de Claude Code) | ''Critical'', ''Important'' | Gravedad: arreglar antes del merge o conviene arreglarlo |
+| ''skill-reviewer'' (plugin de Claude Code) | ''critical'', ''major'', ''minor'' | Gravedad |
+| ''claude-security'' (plugin de Claude Code) | ''CRITICAL'', ''HIGH'', ''MEDIUM'', ''LOW'' | Gravedad de una vulnerabilidad |
+| CodeRabbit | ''Critical'', ''Major'', ''Minor'', ''Trivial'', ''Info'' | Gravedad |
+| ::: | ''Potential issue'', ''Refactor suggestion'', ''Nitpick'' | Clase de comentario: fallo, mejora o detalle sin importancia |
+| ''code-reviewer'' (plugin de Claude Code) | Un número de 0 a 100 | Confianza en que el problema es real: solo informa de los que pasan de 80 |
+Ahora que hemos visto el formato, veamos como decirselo al agente para que retorne ese formato.Hay que tener una sección titulada "Formato de Salida" con el siguiente formato
+<sxh markdown;title:.claude/skills/do-revisar-pr/SKILL.md>
+## Formato de Salida
+La primera línea es `PASS` o `FAIL`. Con `PASS` no se escribe nada más. Con `FAIL`,
+debajo, una línea por problema con el formato `fichero:linea:tipo:descripcion`:
+- `fichero` es donde se ha encontrado el problema. La ruta es relativa al proyecto.
+- `linea` es un número (`42`) o un rango (`50-71`). Si el problema es del fichero
+  entero, no lleva `linea`: `fichero:tipo:descripcion`.
+- `tipo` es `CRITICAL`, `MAJOR` o  `MINOR`.
+- `descripcion`es la descripción del problema que ha encontrado. Es texto libre pero si hay retornos de carro se deben escapar para que solo sea una línea.
+**MUST NOT** escribir nada más antes ni después.
+</sxh>
+==== Ejemplos ====
+Una revisión sin problemas:
+<sxh markdown>
+PASS
+</sxh>
+''do-revisar-pr'', con ''tipo'' (''fichero:linea:tipo:descripcion'', ''fichero:inicio-fin:tipo:descripcion'' y ''fichero:tipo:descripcion''):
+<sxh markdown>
+FAIL
+src/main/java/com/tienda/PedidoService.java:42:CRITICAL:no comprueba que el cliente exista
+src/main/java/com/tienda/PedidoService.java:50-71:MINOR:crear() valida, calcula el total y guarda
+specs/pedidos.md:MAJOR:R-12 no tiene ningún test
+</sxh>
+Una //skill// que revisa los tests, sin ''tipo'' (''fichero:linea:descripcion'', ''fichero:inicio-fin:descripcion'' y ''fichero:descripcion''):
+<sxh markdown>
+FAIL
+src/test/java/com/tienda/PedidoServiceTest.java: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
+src/test/java/com/tienda/ClienteServiceTest.java:no prueba ningún caso de error
+</sxh>
+Una //skill// que revisa el diseño de las clases, por método (''paquete.Clase.metodo:descripcion'', ''paquete.Clase:descripcion'' y ''requisito:descripcion''):
+<sxh markdown>
+FAIL
+com.tienda.domain.PedidoService.crear:valida, calcula el total y guarda: son tres métodos
+com.tienda.domain.PedidoService:depende de ClienteRepository, que es de otro agregado
+R-12:ningún método lo implementa
+</sxh>
+----
+===== Ejercicios =====
+==== Ejercicio 1 ====
+Esta //skill// tiene cinco fallos de estructura. Encuéntralos y di cómo se arregla cada uno.
+<sxh text;gutter:false>
+.claude/skills/K_Controladores/
+├── skill.md
+├── validacion/
+│   └── reglas.md
+├── agents/
+│   └── revisor-agent.md
+├── templates/
+│   └── controller-template.md
+└── examples/
+    └── pedido-controller.md
+</sxh>
+==== Ejercicio 2 ====
+Escribe la //skill// de conocimiento ''k-tests'' con las convenciones de los tests de tu proyecto: frontmatter, frase de entrada, tabla índice y las cinco secciones. Pon en ''templates/'' el esqueleto de una clase de test.
+==== Ejercicio 3 ====
+Escribe la //skill// de procedimiento ''do-crear-test'', que recibe un identificador de requisito y escribe su test cargando ''k-tests''. Tiene que tener ''Formato de entrada'', ''Outline'' con sus ''STOP conditions'', una sección por fase y ''Quick Guidelines''. Pruébala con ''/do-crear-test R-3''.