writing-great-skills

Skill para Escribir Excelentes Skills

Un skill es una promesa: dado este tipo de solicitud, produce este tipo de output profesional, siempre. Los mejores archivos SKILL.md ganan en dos cosas — el modelo los dispara en el momento correcto, y una vez disparado produce el artefacto correcto sin necesidad de intervención manual. Este skill te ayuda a escribir uno que haga ambas cosas.

Partiendo de un brief

Dado un concepto inicial ("un skill para escribir changelogs"), produce el SKILL.md completo de todas formas — infiere el deliverable, inputs y estructura, y marca las elecciones genuinamente abiertas. Nunca devuelvas un esqueleto con <!-- TODO --> pendiente; rellénalo.

Inputs Requeridos

Solicita (si no se proporcionan ya), o infiere y etiqueta:

• Qué debe hacer el skill y el artefacto concreto que produce
• Cuándo debe dispararse (las formas en que un usuario realmente escribiría la solicitud)
• Los inputs que necesita del usuario
• Cualquier framework o estándar que codifique (para atribución)

La anatomía de un excelente SKILL.md

1. Frontmatter (esto es lo que hace que tu skill sea encontrado)

---
name: kebab-case-name           # coincide con la carpeta; corto, específico
description: "<una frase rica>"
---

La descripción es la línea más importante del archivo — es todo lo que el modelo ve cuando decide si cargar el skill (divulgación progresiva: solo nombres + descripciones están en contexto hasta que uno se invoca). Una descripción sólida tiene tres partes:

• Qué hace + el deliverable concreto.
• Una cláusula de activación "Úsalo cuando…" listando las formas reales ("Úsalo cuando te pidan escribir un postmortem, hacer un análisis de causa raíz o documentar un incidente").
• Una cláusula "Produce…" nombrando el output ("Produce un postmortem sin culpa con cronología, causa raíz e items de acción").

Escribe los disparadores como los usuarios hablan, no como los categorizarías. Cubre sinónimos.

2. Declaración de valor de una línea

Abre el cuerpo con una sola frase sobre el valor, en la voz de un profesional senior.

3. Partiendo de un brief

Declara que el skill entrega un artefacto completo incluso con inputs mínimos — infiere y etiqueta supuestos, nunca dejes placeholders entre corchetes, nunca rechaces por falta de contexto. Esto es lo que separa un skill que funciona de uno que demanda.

4. Inputs Requeridos

Una breve lista de qué solicitar — e instrucciones para proceder con inferencias etiquetadas si faltan.

5. Formato de Salida / Estructura

El corazón del skill: una plantilla concreta — encabezados reales, tablas y secciones — del artefacto final. Muestra la forma, no la describas de forma abstracta. Aquí es donde vive la mayor parte de la calidad.

6. Controles de Calidad

Una breve lista de verificación que el output debe satisfacer (la rúbrica que un revisor aplicaría). Hazlos observables.

7. Anti-Patrones

Los modos de fallo específicos a evitar — los outputs perezosos o genéricos que un modelo más débil produciría.

Proceso

1. Clava el deliverable en una frase antes de escribir nada más.
2. Escribe la descripción y somete a prueba los disparadores ("¿elegiría el modelo esto sobre un skill vecino?").
3. Borra el Formato de Salida como una plantilla real.
4. Añade Controles de Calidad y Anti-Patrones que apunten a los modos de fallo específicos de este skill.
5. Valida: npm run skillcheck (estructura) y ejecútalo contra un brief mínimo para confirmar que no pide inputs.

Formato de Salida

Devuelve:

1. El SKILL.md completo en un bloque cercado, listo para guardar en skills/<name>/SKILL.md.
2. Una nota de 3–5 bullets "por qué funciona": las frases de activación elegidas, el deliverable, y el anti-patrón más incisivo que resguarda.

Controles de Calidad

• [ ] El name está en kebab-case y coincide con la carpeta prevista
• [ ] La descripción declara qué hace, tiene una cláusula de activación "Úsalo cuando…", y nombra qué Produce
• [ ] El cuerpo tiene: línea de valor, working-from-a-brief, inputs, una plantilla de Formato de Salida concreta, Controles de Calidad, Anti-Patrones
• [ ] Sin texto TODO/placeholder dejado
• [ ] Los disparadores son distintos de skills vecinos (no se dispararán erróneamente ni se saltarán)
• [ ] Pasaría npm run skillcheck sin errores

Anti-Patrones

• Una descripción vaga sin frases de activación — el skill nunca se selecciona
• Un Formato de Salida que describe el artefacto en lugar de templatizarlo
• Controles de Calidad que no son observables ("el output debe ser bueno")
• Dejar <!-- TODO --> o placeholders entre corchetes en el archivo final
• Solapamiento tan pesado con un skill existente que el modelo no puede elegir entre ellos