logongas

Herramientas de usuario

Herramientas del sitio

Ocultar Menú
Traza:
cursos:sdd:19-creando-skills

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:19-creando-skills [2026/10/30 08:25] – Cambia el título a «Estructura de un skill» claudecursos:sdd:19-creando-skills [2026/10/30 13:56] (actual) – Lorenzo
Línea 1: Línea 1:
-====== 19. Estructura de un skill ====== +====== 20. Estructura de un skill ======
- +
-Qué es una //skill//, su frontmatter y cómo se redacta están en [[cursos:sdd:08-skills|Skills]]. Aquí, la estructura completa de una //skill//: qué carpetas y ficheros puede tener, qué secciones lleva el ''SKILL.md'' según el tipo y cómo se prueba. El modelo es ''k-skill'', la //skill// que fija cómo se escriben las //skills// en un proyecto real.+
  
 +Qué es una //skill//, su frontmatter y cómo se redacta están en [[cursos:sdd:08-skills|Skills]]. Aquí, la estructura completa de una //skill//: qué carpetas y ficheros puede tener, qué secciones lleva el ''SKILL.md'' según el tipo y cómo se prueba. 
 Más información: Más información:
  
Línea 9: Línea 8:
   * [[https://github.com/github/spec-kit|GitHub Spec Kit]]: de sus comandos sale la estructura de las //skills// de procedimiento (User Input, Outline).   * [[https://github.com/github/spec-kit|GitHub Spec Kit]]: de sus comandos sale la estructura de las //skills// de procedimiento (User Input, Outline).
   * [[https://github.com/anthropics/skills/tree/main/skills/skill-creator|skill-creator]]: la //skill// de Anthropic para crear y evaluar //skills//.   * [[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. La carpeta =====+===== 1. El nombre =====
  
-Solo el ''SKILL.md'' es obligatorio; cada carpeta aparece únicamente si la //skill// tiene ese tipo de contenido.+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. 
 + 
 + 
 +===== 2. Estructura de carpetas y ficheros de un skill que "Sabe" ===== 
 +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> <sxh text;gutter:false>
-.claude/skills/k-servicios/ +.opencode/k-servicios/ 
-├── SKILL.md                    <- obligatorio: instrucciones e índice de los demás ficheros +├── SKILL.md 
-├── transacciones.md            <- un tema que solo hace falta a veces+├── transacciones.md
 ├── templates/ ├── templates/
-│   └── service-impl.md         <- texto literal para copiar y rellenar+│   └── service-impl.md
 ├── examples/ ├── examples/
-│   └── pedido-service.md       <- un caso resuelto, para ver el resultado+│   └── pedido-service.md
 ├── references/ ├── references/
-│   └── spring-transactional.md <- documentación de terceros copiada tal cual+│   └── spring-transactional.md
 ├── scripts/ ├── scripts/
-│   └── sin-transaccion.py      <- código que se ejecuta, no se lee+│   └── sin-transaccion.py
 ├── assets/ ├── assets/
-│   └── errores.schema.json     <- ficheros que no son markdown+│   └── errores.schema.json
 └── evals/ └── evals/
-    └── update-sin-filtrar/     <- casos de prueba de la propia skill+    └── update-sin-filtrar/
 </sxh> </sxh>
  
 Qué hace cada pieza está en [[cursos:sdd:08-skills#la_carpeta|Skills]]. Lo que distingue a cada carpeta es **quién la lee y cuándo entra en contexto**: Qué hace cada pieza está en [[cursos:sdd:08-skills#la_carpeta|Skills]]. Lo que distingue a cada carpeta es **quién la lee y cuándo entra en contexto**:
  
-^ Carpeta ^ Contiene ^ Lo lee ^ Se carga ^ +^ Carpeta o fichero ^ Contiene ^ Ejemplo ^ 
-| ''SKILL.md'' | Instrucciones e índice | El agente | Al usar la //skill// | +| ''SKILL.md'' | Instrucciones e índice |  | 
-| ''<tema>.md'' | Reglas del proyecto sobre un tema | El agente | Cuando la tarea toca ese tema | +| ''<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 | 
-| ''templates/'' | Plantillas literales con huecos | Quien escribe el fichero | Al escribirlo | +| ''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/'' | Un caso resuelto; no es normativo | Quien necesita ver el resultado | Bajo demanda | +| ''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 terceros sin adaptar. Puede ir en inglés | Quien necesita el catálogo completo | Bajo demanda | +| ''references/'' | Documentación de referencia. Podría ser la documentación oficial de Spring que ponemos aqui | spring-transactional.md | 
-| ''scripts/'' | Operaciones deterministas | Nadie: se ejecuta | Al ejecutarlo | +| ''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, HTML, imágenes | Los scripts | Bajo demanda | +| ''assets/'' | Esquemas, XSD, imágenes, etc | errores.schema.json | 
-| ''evals/'' | Casos de prueba | Quien evalúa la //skill// | Solo al evaluarla |+| ''evals/'' | Dentro hay carpetas con los test unitarios para probar el skill | update-sin-filtrar/ |
  
-Reglas de la carpeta: 
  
-  * **La carpeta se llama igual que el ''name''** del frontmatter, y dentro hay **un solo ''SKILL.md''**, con ese nombre exacto. +===== 3. SKILL.md ===== 
-  * **En la raíz, solo las carpetas del árbol.** Un tema es un fichero ''<tema>.md'', no una carpeta ''transacciones/''. +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''.
-  * **Nombres en //kebab-case// y sin repetir la carpeta.** Las excepciones son ''SKILL.md'' y ''README.md''. +
-<sxh text;gutter:false> +
-✅ scripts/sin-transaccion.py, templates/service-impl.md +
-❌ scripts/sin_transaccion.py   (no es kebab-case) +
-❌ templates/service-template.md (repite la carpeta) +
-</sxh>+
  
-<note important>**Una //skill// no lleva ''agents/''.** Si una fase lanza subagentes y junta lo que devuelven, ya no es una //skill//: es un [[cursos:sdd:07-agentes#la_carpeta_del_agente|agente]], y los roles de sus subagentes van en la carpeta del agente ([[cursos:sdd:08-skills#skill_o_agente|skill o agente]]).</note>+El motivo de hace esto es paa 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. 
  
----- 
  
-===== 2. El índice =====+===== 3. El índice =====
  
 La tabla índice del ''SKILL.md'' ([[cursos:sdd:08-skills#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: La tabla índice del ''SKILL.md'' ([[cursos:sdd:08-skills#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:
Línea 76: Línea 89:
 ---- ----
  
-===== 3. Dos tipos de skill =====+===== 4. Dos tipos de skill =====
  
-Cada tipo tiene su estructura fija de ''SKILL.md''. Se distinguen por el nombre:+Cada tipo tiene su estructura fija de ''SKILL.md''. Se distinguen por [[#el_nombre|el prefijo]]:
  
 ^ ^ Conocimiento ^ Procedimiento ^ ^ ^ Conocimiento ^ Procedimiento ^
-| Nombre | ''k-<tema>'': ''k-servicios'' | Un verbo: ''crear-servicio'', ''revisar-pr'' | 
 | Qué hace | Describe convenciones, patrones y vocabulario | Ejecuta un proceso por fases | | Qué hace | Describe convenciones, patrones y vocabulario | Ejecuta un proceso por fases |
-| Quién la usa | Otras //skills// y agentes, que la cargan | Tú, con ''/crear-servicio R-12'' |+| Quién la usa | Otras //skills// y agentes, que la cargan | Tú, con ''/do-crear-servicio R-12'' |
 | Argumentos | No | ''$ARGUMENTS'' | | Argumentos | No | ''$ARGUMENTS'' |
 | Fases y ''STOP conditions'' | No | ✓ | | Fases y ''STOP conditions'' | No | ✓ |
  
-Si hacen falta las dos cosas, son dos //skills//: ''k-servicios'' con las reglas y ''crear-servicio'' con el proceso, que carga la primera. Mezcladas, el conocimiento solo se aprovecha al lanzar el proceso.+Si hacen falta las dos cosas, son dos //skills//: ''k-servicios'' con las reglas y ''do-crear-servicio'' con el proceso, que carga la primera. Mezcladas, el conocimiento solo se aprovecha al lanzar el proceso.
  
 ==== Skill de conocimiento ==== ==== Skill de conocimiento ====
Línea 100: Línea 112:
 # k-servicios # k-servicios
  
-Reglas de las clases `*Service` del servidor. La cargan `crear-servicio` y `revisar-pr`.+Reglas de las clases `*Service` del servidor. La cargan `do-crear-servicio` y `do-revisar-pr`.
  
 ## Índice ## Índice
Línea 132: Línea 144:
 Sigue la estructura de los comandos de [[https://github.com/github/spec-kit|Spec Kit]]: Sigue la estructura de los comandos de [[https://github.com/github/spec-kit|Spec Kit]]:
  
-<sxh markdown;title:.claude/skills/crear-servicio/SKILL.md>+<sxh markdown;title:.claude/skills/do-crear-servicio/SKILL.md>
 --- ---
-name: crear-servicio+name: do-crear-servicio
 description: Crea un servicio de Pedidos con su test a partir de un requisito de 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.   specs/. Usar cuando se pida crear, añadir o generar un servicio o una clase *Service.
 --- ---
  
-# crear-servicio+# do-crear-servicio
  
 Eres un desarrollador del servidor: conviertes un requisito de `specs/` en un `*Service` con su test. Eres un desarrollador del servidor: conviertes un requisito de `specs/` en un `*Service` con su test.
Línea 183: Línea 195:
 ## 3. Fase 3 — Comprobar ## 3. Fase 3 — Comprobar
  
-1. Ejecuta `python3 .claude/skills/crear-servicio/scripts/sin-test.py specs/ src/test/java`.+1. Ejecuta `python3 .claude/skills/do-crear-servicio/scripts/sin-test.py specs/ src/test/java`.
 2. Ejecuta `./mvnw -pl servidor test`. 2. Ejecuta `./mvnw -pl servidor test`.
  
Línea 198: Línea 210:
  
   * **Frase de entrada**: el **rol** que asume el modelo y **qué transforma en qué**.   * **Frase de entrada**: el **rol** que asume el modelo y **qué transforma en qué**.
-  * **''## User Input''**: un bloque ''text'' con ''$ARGUMENTS'', que Claude Code sustituye por lo que escribes detrás de ''/crear-servicio''. La línea en inglés es la de Spec Kit, tal cual, y la siguiente dice qué argumentos espera.+  * **''## User Input''**: 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'').   * **''## 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.   * **Una sección por fase** del Outline, con sus pasos.
Línea 207: Línea 219:
 ---- ----
  
-===== 4. evals/: las pruebas de la skill =====+===== 5. evals/: las pruebas de la skill =====
  
 Una //skill// se prueba como el código: una batería de casos que se repite **al editarla y al cambiar de modelo**. Cada caso responde a dos preguntas: Una //skill// se prueba como el código: una batería de casos que se repite **al editarla y al cambiar de modelo**. Cada caso responde a dos preguntas:
Línea 301: Línea 313:
 ==== Ejercicio 3 ==== ==== Ejercicio 3 ====
  
-Escribe la //skill// de procedimiento ''crear-test'', que recibe un identificador de requisito y escribe su test cargando ''k-tests''. Tiene que tener ''User Input'', ''Outline'' con sus ''STOP conditions'', una sección por fase y ''Quick Guidelines''. Pruébala con ''/crear-test R-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 ''User Input'', ''Outline'' con sus ''STOP conditions'', una sección por fase y ''Quick Guidelines''. Pruébala con ''/do-crear-test R-3''.
  
 ==== Ejercicio 4 ==== ==== Ejercicio 4 ====
  
-Crea la carpeta ''evals/'' de ''crear-test'' con tres casos: dos que salgan de fallos que hayas visto al pedir tests sin la //skill// y uno negativo. Rellena la tabla:+Crea la carpeta ''evals/'' de ''do-crear-test'' con tres casos: dos que salgan de fallos que hayas visto al pedir tests sin la //skill// y uno negativo. Rellena la tabla:
  
 ^ Caso ^ Prompt ^ Evaluador del resultado ^ Evaluador del proceso ^ ^ Caso ^ Prompt ^ Evaluador del resultado ^ Evaluador del proceso ^
cursos/sdd/19-creando-skills.1793345158.txt.gz · Última modificación: por claude