Cómo crear tu propia skill SDD en Claude Code (qué es y por qué importa)
Si has probado Spec-Driven Development en Claude Code, probablemente ya has notado el problema: aunque la metodología es sólida, cada sesión empieza desde cero. A veces Claude hace spec, a veces se la salta. A veces planifica fases, a veces dispara código directamente. Sin estructura, SDD termina siendo "vibe coding con prólogo". La solución es montar una skill SDD propia que orqueste el flujo de forma determinista. En este artículo te explico qué es, qué problema resuelve y los principios de arquitectura que uso en mi skill de producción.
📌 En resumen
Una skill SDD seria = un script que lleva el estado del flujo + un SKILL.md que le dice al LLM que solo ejecute lo que el script indique. El LLM no decide el flujo, lo sigue. Resultado: spec → plan → implementar → revisar SIEMPRE en orden, con validaciones que bloquean atajos. La diferencia entre SDD aleatorio y SDD profesional.
El problema que resuelve una skill SDD propia
Llevo meses usando SDD con Claude Code y he visto el mismo patrón repetirse: sin una skill que dirija el flujo, todo se descontrola en cuestión de minutos.
- Le pides a Claude que aplique SDD a una feature → genera una spec.
- Lees la spec rápido, dices "vale, hazlo" → Claude se salta el plan y empieza a codificar.
- A la tercera ronda de cambios, ya nadie sabe qué requisitos hay, qué se cumplió y qué falta.
El problema no es la IA. Es que tú estás dirigiendo el flujo a mano, y los humanos somos los primeros en saltarnos pasos. Una skill SDD bien hecha automatiza esa disciplina: cuando ejecutas /sdd mi-feature, el sistema sabe exactamente en qué fase estás y bloquea cualquier intento de saltar adelante.
Arquitectura: orquestador determinista + ejecutor LLM
El patrón clave que aprendí a base de iteraciones es separar dos responsabilidades:
- El orquestador (un script clásico, típicamente Python): lleva el estado, valida transiciones, decide qué viene después. Es código determinista. No alucina.
- El ejecutor (Claude vía SKILL.md): recibe órdenes del script, ejecuta tareas concretas (generar spec, escribir código, revisar). No decide el flujo.
La comunicación entre los dos es estructurada (JSON, normalmente): el script imprime el estado actual y una instrucción concreta de qué hacer a continuación. El LLM la lee y la ejecuta. No improvisa.
Este patrón tiene un nombre técnico: state machine externa al LLM. Tú diseñas los estados válidos del flujo (por ejemplo: nuevo → esperando spec → spec lista → plan listo → esperando implementación → revisión → cerrado) y el script garantiza que solo se puede transitar entre ellos en orden, con validaciones en cada paso.
El truco menos conocido: dónde viven los artefactos
Uno de los aprendizajes más importantes (y caros, porque los descubres tras horas de fricción) es dónde colocar los archivos que genera tu flujo SDD dentro del proyecto. La respuesta correcta: NO los pongas dentro de .claude/.
El motivo es práctico: Claude Code marca todo lo que vive dentro de .claude/ como archivo sensible (porque ahí van settings, credenciales, configuración personal) y te pide confirmación con cada Write o Edit. Si tu flujo SDD genera y modifica decenas de archivos (specs, planes, notas de implementación…), eso se traduce en decenas de prompts de permiso por sesión. Insufrible.
Mi recomendación: una carpeta dedicada en la raíz del proyecto, al mismo nivel que .git/. Está fuera de la lista de paths protegidos, así que Claude opera con fluidez sin pedir confirmación cada vez. Para el versionado: incluye en git las specs, planes y documentación; ignora solo los archivos de estado puramente locales.
💡 Patrón recomendado
.git/ (versión), .claude/ (config personal de Claude, NO tocar artefactos aquí), carpeta dedicada para SDD (artefactos del flujo), código fuente al mismo nivel. Cada cosa en su sitio, cero fricción con permisos.
Los artefactos que genera el flujo
Un flujo SDD profesional produce varios documentos a lo largo del ciclo. Cada uno cumple una función distinta y se valida antes de avanzar al siguiente:
| Artefacto | Propósito |
|---|---|
| PRD (Product Requirements) | Visión de la feature: qué se quiere, para quién, casos de uso, qué queda fuera. 1-3 páginas. Es la brújula. |
| Spec | Requisitos funcionales detallados en formato Given/When/Then. Testeables. Es el contrato técnico. |
| Plan | Descomposición en fases pequeñas con tabla de cobertura RF → Fase. Es el mapa de ruta. |
| Notas de implementación | Decisiones tomadas durante el desarrollo, problemas resueltos. Es el diario de obra. |
| Review | Auditoría final: cada RF marcada como cumplida / parcial / fallo, con evidencia. Es el acta de entrega. |
| Tests | Suite automatizada que valida cada fase y se ejecuta antes de avanzar al siguiente bloque. |
La clave es que no se puede saltar de un artefacto a otro sin pasar por el orquestador. Si intentas pasar a implementación sin haber cerrado el plan, el script lo bloquea.
Principios de diseño que marcan la diferencia
Sin entrar en código específico (eso lo cubrimos en detalle en el curso), estos son los principios que separan una skill SDD útil de una que genera más problemas que soluciona:
- El LLM no decide el flujo, lo sigue. Toda transición pasa por el orquestador. Si el script no contempla un caso, se para y reporta; nunca improvisa.
- Validación defensiva en cada transición. No te fíes de que la spec esté bien formada. El script verifica formato, completitud y coherencia antes de avanzar.
- Estado persistente en el proyecto, no en home. El estado del flujo viaja con el repositorio: cualquier miembro del equipo puede retomar donde quedó.
- Comando central idempotente. Toda invocación de la skill empieza consultando el estado. El LLM siempre sabe en qué fase está, aunque hayan pasado días.
- Implementación bloque por bloque, no de un tirón. Cada fase se cierra con tests pasando antes de abrir la siguiente. Nunca acabas con código a medias.
- Bloqueo defensivo ante errores. Si una validación falla, parar y reportar. Nunca intentar "ayudar" haciendo cosas raras.
- Modo "mini" para features pequeñas. No toda feature merece una spec de 200 líneas. Tener un modo reducido evita que la skill sea pesada y se acabe evitando.
- Configuración inicial guardada una sola vez. Stack, BD, idioma del proyecto: se preguntan al iniciar el primer flujo y se guardan. No se vuelve a preguntar.
- Activación proactiva pero acotada. La descripción del SKILL.md debe decir tanto cuándo activar como cuándo NO. Si no, la skill se dispara para cosas triviales.
- Modelo apropiado para cada nivel. Skills mecánicas usan modelos baratos (Haiku); skills que requieren razonamiento usan Sonnet. No mates moscas a cañonazos con Opus.
Composición de skills: una pieza no lo hace todo
Otro patrón clave que vale la pena entender: una skill puede invocar a otras como herramientas. En vez de meter toda la lógica dentro de tu skill SDD, delegas tareas específicas a skills especializadas.
Por ejemplo: si tu flujo SDD necesita interactuar con una base de datos en algún momento (registrar progreso, consultar el schema actual), no metas el código de PostgreSQL dentro del orquestador SDD. Mejor crea una skill postgres-db separada y haz que SDD la invoque. Lo mismo para ejecutar tests Playwright: una skill dedicada a tests, invocada cuando una fase se cierra.
Beneficios:
- Separación clara de responsabilidades: cada skill hace una sola cosa.
- Reutilización: la sub-skill la usas para otras cosas también.
- Mantenimiento: si cambia algo, lo arreglas en un sitio.
- Testabilidad: cada pieza se prueba aislada.
Limitaciones que conviene tener claras
- Una skill SDD añade una capa de proceso. Para cambios triviales (renombrar variable, corregir typo) es overkill. Diseña la skill para que se active solo en features de cierto tamaño.
- La curva inicial es real. Las primeras semanas se nota la fricción del proceso. Compensa cuando ves que tu código deja de tener regresiones constantes.
- Requiere disciplina inicial para no saltarse pasos durante la fase de "esto urgente lo hago rápido". Por eso conviene que la skill bloquee, no que sugiera.
El siguiente paso
Si los conceptos de este artículo encajan con cómo quieres trabajar, construir tu propia skill SDD es una inversión muy rentable. La versión mínima viable (estados básicos, comandos esenciales, validaciones simples) puedes tenerla en unos días. La versión profesional, con sub-skills, tests integrados y todos los matices, es proyecto de semanas iterando con casos reales.
Si quieres acelerar la curva con un programa estructurado, casos reales y la implementación completa paso a paso (incluyendo el código del orquestador, plantillas de PRD/spec/plan validadas, patrones probados en producción y todos los trucos que te ahorran meses de error y rehacer), echa un vistazo al curso de Programación asistida con IA en nacaIA Academy. Cubre SDD avanzado, creación de skills profesionales y patrones de arquitectura para llevar Claude Code a producción seria.
Próximos pasos
- Lee qué es SDD si todavía tienes dudas sobre el método.
- Diseña en papel la máquina de estados de tu skill SDD: qué fases tendrá y qué validaciones bloquearán cada transición.
- Decide qué artefactos generará cada paso (PRD, spec, plan…) y en qué formato.
- Empieza con un MVP de 3-4 estados y ve añadiendo según necesites.
- Si quieres dar el salto con un proceso guiado y casos reales, echa un vistazo al curso de nacaIA Academy.
Construir tu propia skill SDD es una de esas inversiones que parecen pequeñas y resultan ser de las más rentables: convierte el "vibe coding con prólogo" en un flujo profesional que escala con el proyecto.