Skills y patrones reutilizables

La caja de herramientas del fontanero

Un fontanero no lleva en la cabeza el manual de cada grifo. Lleva una caja con compartimentos: abre el que toca cuando lo necesita. Y repite siempre el mismo procedimiento para problemas parecidos.

Una skill hace eso para un agente: es una carpeta con un procedimiento reutilizable que sirve en varios proyectos, en vez de repetir instrucciones largas en cada repositorio.

Qué hay (y qué no) dentro

Según el patrón de la fuente, sí caben:

• Flujos de trabajo reutilizables.
• Procedimientos de decisión de un dominio.
• Plantillas, listas de comprobación y material de referencia que el agente carga a demanda.
• Pequeños scripts estables y seguros.

No caben:

• Datos específicos de un proyecto (viven en ese repo).
• Secretos, tokens o URLs privadas.
• Manuales enormes que haya que leer siempre antes de actuar.
• Comandos destructivos, salvo que estén bien documentados y exijan aprobación explícita.

Divulgación progresiva

Una skill se organiza por capas, de lo más corto a lo más profundo:

harness-creator/
├── SKILL.md       <- cuándo se activa + el flujo más corto y fiable
├── references/    <- material profundo, solo si hace falta
├── templates/     <- artefactos listos para copiar
├── scripts/       <- ayudantes opcionales
└── evals/         <- comprobaciones de calidad

El encabezado (frontmatter) de SKILL.md explica cuándo activarla; el cuerpo da el camino corto; el resto se lee solo si el problema lo pide. Es la misma idea que aplicaremos al repo en divulgación progresiva.

Ejemplo real: harness-creator

Esta skill sirve para crear, auditar y mejorar el harness de un repositorio. Su propia regla de diseño: mantener el archivo raíz corto (rutas e invariantes, no un manual completo). Se ocupa de los cinco subsistemas: instrucciones, estado, verificación, alcance y ciclo de vida. Ofrece tareas como crear un harness mínimo con un script:

node skills/harness-creator/scripts/create-harness.mjs --target /ruta/al/proyecto

o auditar uno existente con validate-harness.mjs, que da puntuación por subsistema y señala el más débil. Aviso de la propia skill: esa puntuación es estructural; la eficacia real se mide con sesiones antes y después sobre tareas representativas.

Lista de validación de una skill

- [ ] SKILL.md existe y tiene frontmatter válido
- [ ] Todo archivo referenciado existe dentro de la skill
- [ ] Las plantillas son seguras de copiar a otro repo
- [ ] No depende de rutas locales privadas

Con esto cierras el módulo de herramientas. Sigue por el contexto y cómo cuidarlo: la ventana de contexto.