SkillForge

¿Qué hace SkillForge?

Crea habilidades bien formadas y conformes a las especificaciones a partir de patrones observados.

Cuándo Forjar

✅ Forja cuando:

• Has repetido la misma secuencia 2-3 veces en una sesión
• Una convención del proyecto no está documentada en ningún lado
• Resolviste un problema difícil con una solución reutilizable
• Alguien te pide que crees una habilidad

❌ No forjes cuando:

• Es una tarea única
• Ya existe una habilidad que lo cubre (actualízala en su lugar)
• La "habilidad" es solo un comando simple (usa un alias de script)

Pasos

1. Nombra el patrón

• ¿Qué problema resuelve esta habilidad?
• ¿Qué lo desencadena? (sé específico: el campo description es la superficie de descubrimiento)
• ¿Cuáles son las entradas y salidas?

2. Elige un nombre

• kebab-case, de 1 a 64 caracteres
• Preferiblemente comenzando con verbo: deploy-preview, scaffold-component, triage-bug
• Una responsabilidad por habilidad

3. Crea el directorio de la habilidad

mkdir -p skills/<nombre-de-la-habilidad>

4. Escribe SKILL.md

Usa este esqueleto:

---
name: <nombre-de-la-habilidad>
description: <qué hace>. Úsalo cuando <desencadenantes>.
metadata:
  forged-by: <id-del-agente>
  forged-from: <sesión-o-contexto>
  forged-reason: "<por qué se creó>"
---

# <Nombre de la Habilidad>

## Entradas
- ...

## Pasos
1. ...
2. ...

## Convenciones
- Patrones específicos del proyecto que aplican

## Casos Extremos
- Problemas conocidos o manejo especial

5. Añade scripts (opcional)

Si la habilidad implica generación de archivos o automatización:

skills/<nombre-de-la-habilidad>/
├── SKILL.md
├── scripts/
│   └── run.sh         # Automatización ejecutable
└── references/
    └── conventions.md # Referencia detallada (mantiene SKILL.md ligero)

6. Registra la habilidad

Actualiza .skills-registry.md en la raíz del proyecto (al mismo nivel que skills/). Créalo si no existe:

| <nombre-de-la-habilidad> | local | <hoy> | 1 | <descripción> |

Si el proyecto usa el registro legible por máquina (.skills-registry.json), actualízalo también. skdd forge maneja ambos formatos automáticamente.

Actualizar una Habilidad Existente

Cuando uses una habilidad y encuentres algo que no cubre:

1. Añade el nuevo caso extremo o paso al SKILL.md existente
2. Si la habilidad se está volviendo demasiado larga (>200 líneas), divídela
3. Actualiza last-used e incrementa usage-count en el registro

Lista de Verificación de Calidad

Antes de confirmar una nueva habilidad:

• name está en kebab-case, ≤64 caracteres
• description incluye qué hace Y cuándo usarlo
• Los pasos están numerados y son accionables
• No hay rutas fijas, secretos ni valores específicos del entorno
• SKILL.md tiene menos de 200 líneas (mueve los detalles a references/)
• Registrada en .skills-registry.md