Qué es una skill y qué es un subagente en dos líneas está en Conceptos básicos (skills, subagentes); cómo se lanzan y dónde se guardan, en OpenCode y Claude Code. Aquí, cómo se escriben las dos y qué va en una skill y qué en un agente. Cómo se reparte el conocimiento del proyecto entre AGENTS.md y las skills, en AGENTS.md.

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.

.opencode
└── skills
    └── revisar-pr
        ├── SKILL.md          <- las instrucciones
        └── checklist.md      <- material de apoyo, se carga solo si hace falta

---
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.

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: 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 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 (AGENTS.md pequeño). Lo que no puede hacer una skill es actuar: solo guía cómo se actúa.

Dos campos, los dos obligatorios:

• name: el mismo que el nombre de la carpeta.
• 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.

# ✅ 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.

Solo el SKILL.md es obligatorio; cada carpeta aparece únicamente si la skill tiene ese tipo de contenido.

.opencode
└── skills
    └── servicios
        ├── SKILL.md          <- obligatorio: las reglas y el índice de los demás ficheros
        ├── transacciones.md  <- un tema que solo hace falta a veces
        ├── templates/        <- texto literal para copiar y rellenar
        ├── examples/         <- casos resueltos, para ver el resultado
        ├── references/       <- documentación de terceros copiada tal cual
        └── scripts/          <- código que se ejecuta, no se lee

• <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.
• templates/: un fichero con estructura fija se da como plantilla literal; 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 librería sin adaptar. La regla del proyecto va en la raíz y apunta aquí.
• scripts/: ver scripts.

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.

---
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

Reglas de las clases `*Service` del servidor.

## Índice

| Fichero | Qué contiene |
|---|---|
| `transacciones.md` | Qué métodos son transaccionales y cómo |
| `templates/service.java` | Esqueleto de un servicio nuevo |

## Convenciones

- Un servicio por agregado: `PedidoService`, no `PedidoLineaService`.
- Valida al entrar y lanza `ErrorDeNegocio` con el código de `specs/`.
- No devuelve entidades: devuelve DTOs.

## Ejemplos

- ✅ `throw new ErrorDeNegocio("R-12", "El pedido ya está enviado")`
- ❌ `throw new IllegalStateException("No se puede")` (no dice qué requisito incumple)

## Nunca

- Llamar a un repositorio de otro agregado: se pasa por su servicio.

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.

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.

• Se cita con el comando exacto y la palabra «ejecuta».

✅ 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)

• 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.

En este curso los agentes aparecen de dos formas:

• El agente principal: el que habla contigo. En OpenCode, Plan y Build; en Claude Code, la propia sesión.
• 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 (patrón orquestador).

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.

Así que un agente no lleva las convenciones del proyecto: dice qué skill cargar. Tiene 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.

✅ Antes de revisar, carga la skill servicios.
❌ Los servicios lanzan ErrorDeNegocio, nunca IllegalStateException... (conocimiento: va en la skill)

Las instrucciones del agente van en un fichero .md: arriba el frontmatter, que cambia según la herramienta (OpenCode, Claude Code), y debajo sus instrucciones, que son iguales en las dos. Las instrucciones llevan siempre las mismas 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.
• Proceso: pasos numerados, un verbo cada uno.
• 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.

# Verificador de tests

Comprueba que cada requisito de la spec está cubierto por un test que pasa.

## Rol
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
Te llegan en el prompt:
- `spec`: ruta del fichero de requisitos.
- `modulo`: módulo Maven donde están los tests.

## 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
- OK: todos los requisitos tienen un test que lo cita y todos pasan.
- Fallo: un requisito sin test o un test que falla.
- En la duda: fallo.

## Salida
Primera línea, exactamente `DONE` o `BLOCKED`.
Si es `BLOCKED`, una línea por problema: `R-12: sin test`.

En el frontmatter de las dos herramientas hay tres decisiones que se toman igual:

• description: igual que en una skill, qué hace y cuándo usarlo: es lo que lee el principal para decidir si lo lanza (cómo se escribe).
• 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.

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.

.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

• AGENT.md: el frontmatter y las instrucciones de la 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.
• <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 (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.

# Verificador de tests

Comprueba que cada requisito de la spec está cubierto por un test que pasa.

## Índice

| Fichero | Qué contiene | Cuándo cargarlo |
|---|---|---|
| `.claude/agents/verificador-tests/cobertura.md` | Cuándo un test cubre un requisito | Si un test no cita el identificador |
| `.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
...

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.

---
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.

• 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.

Va en .claude/agents/<nombre>/AGENT.md, dentro de 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.

---
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

Comprueba que cada requisito de la spec está cubierto por un test que pasa.

## Índice
...

• name: obligatorio, el nombre con el que se lanza.
• 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:

claude --agent orquestador

• Specification - Agent Skills: el estándar de las skills: formato de SKILL.md y carga por niveles (descripción, cuerpo, ficheros de apoyo).
• 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».
• Equipping agents for the real world with Agent Skills: por qué las skills se cargan por niveles y qué pueden llevar dentro (scripts, plantillas).
• OpenCode: skills: en qué carpetas busca skills, .claude/skills/ incluida.
• Claude Code: subagents: todos los campos del frontmatter, skills, los subagentes anidados y la búsqueda en subcarpetas de .claude/agents/.
• OpenCode: agents: agentes principales y subagentes, mode y permission.
• MCP vs Skills vs Agents With Scripts: Which One Should You Pick?