logongas

Herramientas de usuario

Herramientas del sitio

Ocultar Menú
Traza:
cursos:sdd:08-skills

Diferencias

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

Enlace a la vista de comparación

Próxima revisión		Revisión previa
cursos:sdd:08-skills [2026/10/26 14:14] – Nuevo tema: Skills, con skills y AGENTS.md de Skills, Agentes y MCP claudecursos:sdd:08-skills [2026/10/26 15:55] (actual) – Enlace roto a la sección de AGENTS.md de OpenCode, que ya no existe: apunta a /init claude
Línea 1: Línea 1:
 ====== Skills ====== ====== Skills ======
  
-Qué es una //skill// en dos líneas está en [[cursos:sdd:02-conceptos-basicos#skills|Conceptos básicos]]; cómo se lanza y dónde se guarda, en [[cursos:sdd:03-opencode#skills|OpenCode]] y [[cursos:sdd:03-claude-code#skills|Claude Code]]. Aquí, cómo se escriben y cómo se reparte el conocimiento del proyecto entre ''AGENTS.md'' y las //skills//.+Qué es una //skill// en dos líneas está en [[cursos:sdd:02-conceptos-basicos#skills|Conceptos básicos]]; cómo se lanza y dónde se guarda, en [[cursos:sdd:03-opencode#skills|OpenCode]] y [[cursos:sdd:03-claude-code#skills|Claude Code]]. Aquí, qué va en una //skill// y qué en un agente, cómo se escriben y cómo se reparte el conocimiento del proyecto entre ''AGENTS.md'' y las //skills//.
  
 ---- ----
Línea 31: Línea 31:
 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. 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.
  
-<note important>La **descripción** es lo único que el modelo lee para decidir si la usa. Se escribe diciendo **cuándo** se aplica, no qué hace: «usar cuando se pida revisar un PR» funciona; «utilidades de revisión» no la activa nunca.</note>+La **descripción** es lo único que el modelo lee para decidir si la usa: [[#el_frontmatter|cómo se escribe]].
  
 Dónde viven: Dónde viven:
Línea 44: Línea 44:
 ---- ----
  
-===== 2. AGENTS.md =====+===== 2. Cómo se escribe una skill ===== 
 + 
 +==== Skill o agente ==== 
 + 
 +Una //skill// y un [[cursos:sdd:07-agentes|agente]] son los dos un markdown con frontmatter, pero hacen cosas distintas: **la //skill// es el conocimiento** y **el agente organiza el trabajo**. Lo decide una pregunta: **¿cambiaría si el proyecto fuera otro?** Si cambia, es conocimiento y va en una //skill//. 
 + 
 +^ Qué es ^ Skill ^ Agente ^ 
 +| Convenciones, patrones y vocabulario del proyecto | ✓ | | 
 +| Ejemplos ✅/❌, plantillas, documentación de terceros | ✓ | | 
 +| 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 | ✓ | ✓ | 
 + 
 +Un agente es **un solo fichero ''.md'', sin carpeta**: no tiene dónde guardar ejemplos, plantillas ni scripts. Lo que necesita saber lo carga de una //skill//, y los scripts que ejecuta están en la carpeta ''scripts/'' de una //skill//. 
 + 
 +<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> 
 + 
 +==== El frontmatter ==== 
 + 
 +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. 
 + 
 +<sxh yaml> 
 +# ✅ qué cubre, cuándo usarla y con qué palabras se pide 
 +description: Convenciones de los servicios de Pedidos (transacciones, validación, 
 +  errores de negocio). Usar al escribir, revisar o probar una clase *Service. 
 + 
 +# ❌ no dice cuándo: no se carga nunca 
 +description: Utilidades para servicios. 
 + 
 +# ❌ cuenta el proceso, que va en el cuerpo, y no dice cuándo 
 +description: Primero lee el servicio, luego revisa las transacciones y lanza los tests. 
 +</sxh> 
 + 
 +==== La carpeta ==== 
 + 
 +Solo el ''SKILL.md'' es obligatorio; cada carpeta aparece únicamente si la //skill// tiene ese tipo de contenido. 
 + 
 +<sxh plain> 
 +.claude/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 
 +</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. 
 +  * **''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|scripts]]. 
 + 
 +==== El SKILL.md ==== 
 + 
 +Detrás del frontmatter, una frase de qué cubre y, si hay más ficheros, **la tabla índice**: cada fichero con **cuándo cargarlo**. Un fichero que no está en la tabla no lo lee nadie. 
 + 
 +<sxh markdown;title:.claude/skills/servicios/SKILL.md> 
 +--- 
 +name: servicios 
 +description: Convenciones de los servicios de Pedidos (transacciones, validación, 
 +  errores de negocio). Usar al escribir, revisar o probar una clase *Service. 
 +--- 
 + 
 +# servicios 
 + 
 +Reglas de las clases `*Service` del servidor. 
 + 
 +## Índice 
 + 
 +| Fichero | Qué contiene | Cuándo cargarlo | 
 +|---|---|---| 
 +| `transacciones.md` | Qué métodos son transaccionales y cómo | Al escribir un método que guarda | 
 +| `templates/service.java` | Esqueleto de un servicio nuevo | Al crear un servicio | 
 + 
 +## 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. 
 +</sxh> 
 + 
 +==== Cómo se redacta ==== 
 + 
 +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 [[cursos:sdd:07-agentes|agente]]. 
 + 
 +  * Se cita con **el comando exacto** y la palabra «ejecuta». 
 +<sxh plain> 
 +✅ 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> 
 +  * **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 =====
  
 ''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. ''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.
Línea 112: Línea 240:
 <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> <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>
  
-Cómo generar un primer ''AGENTS.md'' con ''/init'' y cómo mantenerlo: [[cursos:sdd:03-opencode#agentsmdlas_instrucciones_fijas_del_proyecto|AGENTS.md en OpenCode]].+Cómo generar un primer ''AGENTS.md'' con ''/init'' y cómo mantenerlo: [[cursos:sdd:03-opencode#init|/init en OpenCode]].
  
 ==== CLAUDE.md: no usarlo ==== ==== CLAUDE.md: no usarlo ====
Línea 141: Línea 269:
 ---- ----
  
-===== 3. Cómo se organiza AGENTS.md =====+===== 4. Cómo se organiza AGENTS.md =====
  
-La [[#agentsmd|sección 2]] 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.+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.
  
 ==== Qué entra ==== ==== Qué entra ====
Línea 212: Línea 340:
 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. 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.
  
-Lo mismo vale para la ''description'' de cada //skill// ([[#que_es_una_skill|sección 1]]): 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.+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.
  
 ---- ----
cursos/sdd/08-skills.1793020481.txt.gz · Última modificación: por claude