spec-kit-template: Skill for Claude Code

SKILL — spec-style (Markdown robusto, mínimos cambios)

Principio rector

Fix local, no reformat global.
Solo corrige el fragmento que causa mala lectura/render o provoca errores típicos (listas pegadas, fences rotos, tablas inválidas). Evita “embellecer” documentos enteros.

Alcance

• Aplica a ediciones Markdown en:
  • docs/spec/** (principal)
  • docs/kit/** (cuando se edita documentación del kit)

No-objetivos

• No reescritura por estilo si el Markdown ya renderiza bien.
• No normalización masiva de espaciados, tablas o listas si no hay beneficio claro.

---

Reglas duras (robustez)

1) Encabezados con separación mínima

• Debe haber 1 línea en blanco después de cualquier encabezado #..####.
• Debe haber 1 línea en blanco antes de un encabezado (salvo que sea la primera línea del archivo).

✅

## Sección

Texto.

❌

## Sección
Texto.

2) Listas separadas de párrafos

• Si una lista va después de un párrafo → 1 línea en blanco antes.
• Si tras una lista viene un párrafo/encabezado → 1 línea en blanco después.

✅

Texto previo.

- A
- B

Texto posterior.

3) Fences correctos y estables

• Usar fences … para código.
• Debe haber 1 línea en blanco antes y después del bloque (fuera de listas).
• Si el fence está dentro de una lista, indentar el fence y su contenido con 4 espacios por nivel de lista.

✅ Dentro de lista:

- Ejemplo:

    ```json
    { "a": 1 }
    ```

Excepción: no “normalizar” espacios dentro de fences. El contenido del bloque se respeta.

4) Tablas válidas

• El número de columnas debe ser consistente en cabecera/separador/filas.
• Evitar pipes | sin escapar dentro de celdas.
• Evitar saltos de línea dentro de celdas.

Nota: el separador puede ser |---|---| o | --- | --- | (ambos válidos). Preferencia se define en “Recomendadas”.

5) Sin tabs y sin trailing spaces

• No usar tabuladores.
• Evitar espacios al final de línea.