Por qué GitHub Spec Kit es tan interesante: seis skills que vale la pena estudiar

Es fácil resumir mal GitHub Spec Kit.

Una descripción superficial sería: convierte una idea en spec.md, plan.md, tasks.md y código.

Una descripción más interesante sería: Spec Kit convierte una solicitud abierta y poco confiable a un agente en una secuencia de transformaciones acotadas, con entradas y salidas explícitas, contratos de modificación declarados en los prompts, verificaciones y rutas de recuperación.

Esta segunda descripción explica por qué el proyecto importa a quienes crean Agent Skills personalizadas.

Este artículo es una revisión a nivel de código fuente de las seis etapas por las que más preguntan los lectores:

specify -> clarify -> plan -> tasks -> analyze -> implement

Revisé las plantillas de prompts, las plantillas de artefactos, la integración con Cursor, la documentación oficial y el historial de versiones de Spec Kit v0.13.0, publicada el July 17, 2026. Cuando el artículo explica qué hacen los archivos, las afirmaciones están respaldadas por el código fuente. El flujo de trabajo para una empresa que aparece más adelante es un diseño ilustrativo basado en mi criterio de ingeniería.

Antes de comenzar, importa aclarar un término: las explicaciones más antiguas suelen llamarlos simplemente “comandos slash”. Al inicializarse con --integration cursor-agent, Spec Kit v0.13.0 los instala por defecto como Agent Skills en .cursor/skills/speckit-<name>/SKILL.md. Para los procesos principales sin personalizaciones, los archivos compartidos templates/commands/*.md son la fuente de generación; los presets y las extensiones pueden reemplazar el contenido instalado que finalmente se utiliza. Por eso son tanto una interfaz de comandos como, en Cursor, Agent Skills reales.

En resumen

• Spec Kit es interesante porque cada skill se comporta como una pasada tipada de un compilador, no como una colección reutilizable de consejos para escribir prompts.
• Cada pasada reduce la libertad del modelo:
  • specify separa qué y por qué de la implementación
  • clarify convierte la ambigüedad de alto impacto en decisiones registradas
  • plan convierte los requisitos en un diseño técnico fundamentado en investigación
  • tasks convierte el diseño en trabajo ordenado por dependencias y verificable de forma independiente
  • analyze comprueba la consistencia entre artefactos sin editar los tres que revisa
  • implement ejecuta el trabajo aprobado mientras actualiza el progreso persistente
• El prompt en Markdown es solo una capa. Los scripts deterministas resuelven rutas y estado; las plantillas acotan la estructura de salida; los artefactos transportan contexto entre sesiones; y las verificaciones y los hooks dan instrucciones o controlan las transiciones, sujetos a lo que hagan cumplir el agente y el entorno.
• El diseño es sólido, pero no infalible. Parte de la “validación” sigue dependiendo del criterio del modelo, la correspondencia entre tareas y requisitos es semántica y no está demostrada formalmente, las pruebas son opcionales por defecto y la skill de implementación puede modificar una superficie amplia.
• Un flujo de especificaciones propio de una empresa puede aplicar la misma arquitectura de control mediante:
  • verificaciones previas legibles por máquina
  • contratos explícitos de lectura y escritura
  • plantillas y transferencia de artefactos controladas por la empresa
  • ciclos acotados de aclaración y revisión
  • controles de políticas y cobertura
  • condiciones Done When verificables
• No deberíamos copiar literalmente los prompts gigantes. Deberíamos copiar la arquitectura de control.

Qué aprenderás aquí

• Por qué Spec Kit es más que una cadena de prompts en Markdown
• Cómo funcionan internamente las seis skills solicitadas
• Qué decisión de diseño de cada skill reduce los fallos del agente
• En qué aspectos las skills siguen siendo heurísticas, riesgosas o demasiado amplias
• Cómo se combinan las etapas en un pipeline de artefactos
• Cómo convertir los patrones más sólidos en un flujo de especificaciones específico para una empresa
• Una skill de planificación concreta, una organización de artefactos, una secuencia de adopción y una lista de verificación para evaluar el flujo

Audiencia: ingenieros y arquitectos que diseñan flujos de trabajo repetibles asistidos por IA.

La idea central: tratar las skills como pasadas de un compilador

Un compilador no le pide a un solo componente que entienda el texto fuente, lo optimice, genere código máquina, enlace dependencias y verifique el binario en un único paso sin estructura. Usa representaciones intermedias y pasadas con funciones más acotadas.

Spec Kit aplica esa idea al trabajo de los agentes:

Los “tipos” de esta analogía son contratos de procedimiento expresados en plantillas e instrucciones. No son tipos verificados formalmente ni límites de seguridad.

natural-language intent
        |
        v
  [specify]  -> spec.md: behavior contract
        |
        v
  [clarify]  -> spec.md: ambiguity reduced
        |
        v
    [plan]   -> plan.md + research + model + contracts
        |
        v
   [tasks]   -> tasks.md: executable work graph
        |
        v
  [analyze]  -> artifact-level read-only report
        |
        v
 [implement] -> code + planned tests + checked task state

Cada artefacto es una representación intermedia:

• spec.md representa el comportamiento deseado sin comprometerse con un stack.
• plan.md representa las decisiones de implementación sin convertirse en la cola de tareas.
• tasks.md representa el orden de ejecución sin reemplazar los requisitos.
• El código representa una implementación de esos artefactos aprobados.

Esta separación aporta tres cosas útiles.

Primero, reduce la cantidad de preguntas que el modelo debe responder al mismo tiempo. Segundo, permite atribuir los errores a una etapa. Tercero, crea puntos de revisión que una persona u otro agente puede inspeccionar antes de que los errores se conviertan en código costoso de corregir.

La conclusión central del artículo es:

La mayor innovación de Spec Kit no es “escribir primero una especificación”. Es asignar un contrato a cada transformación y hacer que esos contratos persistan fuera del contexto del modelo.

La arquitectura de cuatro capas detrás de las skills

Los archivos SKILL.md instalados atraen la atención, pero son solo una capa.

Esa división es importante. Un prompt no es bueno para localizar de manera confiable el directorio correcto de una funcionalidad en distintos sistemas operativos. Un script sí puede hacerlo. Un script no es bueno para convertir una idea vaga de producto en escenarios de usuario coherentes. Un modelo sí puede hacerlo. Spec Kit le asigna a cada parte el trabajo para el que está mejor preparada.

El proyecto se resuelve a partir de SPECIFY_INIT_DIR o del contexto local del proyecto Spec Kit; la funcionalidad activa se resuelve a partir de SPECIFY_FEATURE_DIRECTORY o .specify/feature.json, no de la rama de Git que está activa. Esto corrige una suposición común en tutoriales antiguos de Spec Kit.

La integración de Cursor en v0.13.0 hace portable esta arquitectura al generar Agent Skills a partir de las plantillas comunes. El frontmatter de la skill generada incluye name, description, compatibility, metadatos del autor y metadatos de la plantilla de origen, mientras que las referencias a comandos y las rutas de scripts se reescriben para adaptarse a la forma de invocación de Cursor.

Este es un mejor modelo de portabilidad que mantener seis prompts derivados manualmente para cada agente.

Skill 1: speckit-specify

Su verdadera función

specify no se limita a escribir una especificación. Es un mecanismo que hace cumplir el límite entre la intención de producto y el diseño técnico.

Recibe una descripción de la funcionalidad en lenguaje natural y debe producir:

• historias de usuario priorizadas y verificables de forma independiente
• escenarios de aceptación
• casos límite
• requisitos funcionales numerados
• entidades clave cuando hay datos involucrados
• criterios de éxito medibles e independientes de la tecnología
• supuestos explícitos

También crea y registra de forma persistente el directorio de la funcionalidad activa, copia la plantilla de especificación seleccionada y crea una lista de verificación de calidad de requisitos.

Los patrones de prompt más interesantes

1. Definir lo que queda fuera es tan importante como definir el objetivo

La skill indica qué pertenece a la fase —actores, acciones, datos, restricciones—, pero también qué no pertenece: detalles de implementación, frameworks, APIs y estructura del código.

Esto protege el “qué”, que es estable, de un compromiso prematuro con el “cómo”, que es flexible.

2. La aclaración tiene un límite

La skill permite un máximo de tres marcadores [NEEDS CLARIFICATION] durante la especificación inicial. Los prioriza según:

scope > security/privacy > user experience > technical detail

Para todo lo demás se deben usar supuestos razonables y documentados.

Es un diseño sutil pero valioso. Un agente sin restricciones o bien supone demasiado, o hace un cuestionario tan largo que el flujo se detiene. Un límite de aclaraciones obliga a priorizar.

3. La redacción incluye un ciclo acotado de autorrevisión

Después de escribir la especificación, la skill genera checklists/requirements.md y evalúa la especificación con esa lista. Para los puntos que no se cumplen, excepto los marcadores de aclaración sin resolver, revisa y vuelve a intentar hasta tres veces; los marcadores de aclaración siguen un flujo de preguntas acotado por separado.

El ciclo tiene:

• un criterio de evaluación identificado: la lista de verificación
• un límite de reintentos: tres
• una salida de escalamiento: documentar los problemas restantes y advertir

Eso es mucho más sólido que “revisa tu trabajo con cuidado”.

Dónde sigue siendo débil

La skill indica al modelo que use “valores predeterminados razonables”, incluidos valores del dominio. Esto mantiene el avance, pero también puede convertir un supuesto en un requisito aparentemente autorizado. La retención de datos, la autenticación, el cumplimiento legal y las expectativas de rendimiento no siempre son áreas en las que sea seguro asumir una norma de la industria.

Además, la lista de verificación es evaluada por el mismo modelo que escribió la especificación. Es un mecanismo útil de revisión, no una prueba independiente.

Lección para skills personalizadas: define categorías de supuestos. Los valores predeterminados de bajo impacto se pueden inferir y registrar; las decisiones de seguridad, legales, irreversibles o que cambian la audiencia deben provocar una aclaración.

Skill 2: speckit-clarify

Su verdadera función

clarify es un protocolo para extraer decisiones.

Examina la especificación actual según una taxonomía detallada:

• alcance funcional
• dominio y modelo de datos
• interacción y UX
• cualidades no funcionales
• integraciones
• manejo de fallos
• restricciones y compromisos
• terminología
• señales de finalización
• marcadores de posición sin resolver

Luego ordena las preguntas candidatas usando una heurística de Impact * Uncertainty.

Los patrones de prompt más interesantes

1. Exactamente una pregunta a la vez

A diferencia de specify, que puede presentar hasta tres preguntas críticas juntas, clarify hace una pregunta, valida la respuesta, la escribe en la especificación y solo entonces pasa a la siguiente pregunta en espera.

La aclaración secuencial permite que cada respuesta cambie cuál es la siguiente pregunta que vale la pena hacer.

2. Las recomendaciones reducen el costo de interacción

Para preguntas de opción múltiple, la skill debe recomendar una opción y explicar por qué. El usuario puede aceptarla con “yes” o “recommended”.

Esto evita que el usuario tenga que hacer todo el análisis desde cero, sin quitarle la decisión.

3. Cada respuesta se refleja en la sección correspondiente

La skill no solo agrega un registro de preguntas y respuestas. Actualiza el requisito funcional, la historia de usuario, la entidad, el criterio de éxito, el caso límite o la terminología que la respuesta modificó. Elimina el texto anterior que contradiga la respuesta y guarda después de cada una.

Esto crea dos registros:

decision history  -> Clarifications session
current truth     -> owning spec section

4. Se vuelve a evaluar el estado de calidad para las etapas posteriores

Si existe la lista de verificación de requisitos, solo se cambian los estados de las casillas que realmente variaron. El informe de finalización muestra los puntos que ahora se cumplen, las regresiones, las brechas restantes y los totales antes y después.

Esta es una validación consciente de los cambios, no simplemente otra reescritura completa.

Dónde sigue siendo débil

La taxonomía es lo suficientemente amplia como para que un modelo clasifique asuntos del nivel de planificación como ambigüedad de producto o viceversa. La skill le indica que posponga los detalles de ejecución propios del plan, pero ese límite sigue dependiendo de su criterio.

También limita cada sesión a cinco preguntas. Eso es bueno para el diseño de la interacción, pero “se hicieron cinco preguntas” no equivale a “la funcionalidad está suficientemente especificada”. El informe de finalización conserva correctamente las categorías pospuestas y pendientes; los equipos deben leerlas.

Lección para skills personalizadas: una skill de aclaración debe modificar de inmediato el artefacto fuente, mantener un registro compacto de decisiones y reportar lo que sigue sin resolverse. Las respuestas en el chat por sí solas no constituyen un estado persistente.

Para conocer el patrón más amplio de propiedad de artefactos aplicado a comentarios de revisión, consulta Cómo gestionar el feedback en GitHub Spec Kit.

Skill 3: speckit-plan

Su verdadera función

plan es un compilador de requisitos a diseño con controles de gobernanza.

Lee la especificación de la funcionalidad, la constitución y la plantilla del plan. Luego crea:

• plan.md
• research.md
• data-model.md
• contracts/ cuando el proyecto tiene interfaces externas
• quickstart.md como guía de validación de extremo a extremo

Los patrones de prompt más interesantes

1. Las incógnitas se convierten en tareas de investigación

La sección de contexto técnico permite explícitamente NEEDS CLARIFICATION. La Fase 0 convierte cada incógnita, dependencia y pregunta sobre integraciones en trabajo de investigación. El research.md final registra:

• decisión
• justificación
• alternativas consideradas

La planificación no oculta la incertidumbre; la convierte en una subtarea que produce un artefacto.

2. La gobernanza se aplica antes y después del diseño

La plantilla del plan incluye una verificación de la constitución antes de la investigación y exige evaluarla nuevamente después del diseño de la Fase 1.

Esto detecta un fallo común:

high-level plan passes principles
        |
        v
detailed design introduces a violation

Toda excepción justificada debe quedar en una tabla explícita de seguimiento de complejidad, junto con la alternativa más simple que se rechazó.

3. Los artefactos de apoyo tienen propósitos distintos

La skill evita poner todo en un único documento de diseño gigante:

• research.md contiene decisiones y alternativas.
• data-model.md contiene entidades, relaciones, validación y estado.
• contracts/ contiene interfaces observables desde el exterior.
• quickstart.md contiene escenarios de validación ejecutables, no código de implementación.

Eso es divulgación progresiva a nivel de artefactos.

Dónde sigue siendo débil

El plan predeterminado puede generar más artefactos de los que necesita un cambio pequeño. El prompt sí indica que se omitan los contratos para trabajo puramente interno, pero los equipos aún necesitan aplicar proporcionalidad.

La investigación del plan solo es tan confiable como sus fuentes y su acceso al repositorio. “Investigación completa” puede significar que el modelo produjo una justificación plausible, no que una persona validó la evidencia primaria.

Lección para skills personalizadas: convierte las incógnitas en tareas de investigación identificadas, pero exige que se indique el origen de las fuentes para las decisiones verificables externamente. Separa “decisión tomada” de “afirmación verificada”.

Skill 4: speckit-tasks

Su verdadera función

tasks es un compilador de planes de ejecución.

Consume artefactos obligatorios (spec.md, plan.md) y artefactos opcionales (data-model.md, contracts/, research.md, quickstart.md). Genera un formato de tareas estricto:

- [ ] T012 [P] [US1] Create User model in src/models/user.py

Cada símbolo tiene un significado:

• casilla de verificación: estado persistente del progreso
• T012: identidad estable de ejecución
• [P]: oportunidad segura de paralelización
• [US1]: trazabilidad al valor para el usuario
• ruta de archivo: alcance concreto de modificación

Los patrones de prompt más interesantes

1. Las historias de usuario, no las capas técnicas, organizan la entrega

La lista de tareas se ordena así:

Setup
  -> Foundational blockers
  -> User Story 1 (P1 / MVP)
  -> User Story 2
  -> User Story 3
  -> Cross-cutting polish

Dentro de una historia, los modelos, servicios, endpoints y pruebas permanecen juntos. Esto fomenta entregas verticales que se pueden demostrar y validar de forma independiente.

2. El paralelismo es una afirmación con condiciones

[P] solo se permite cuando las tareas usan archivos diferentes y no dependen de trabajo sin terminar. El documento generado debe incluir el orden de dependencias y ejemplos de ejecución paralela.

Esto es más útil que decirle a un orquestador que “paralice cuando sea posible”. Crea una hipótesis de planificación que se puede inspeccionar.

El aislamiento de la ejecución sigue siendo responsabilidad de mecanismos externos al marcador; De la especificación a la entrega paralela aborda ramas, worktrees y responsabilidades.

3. El alcance del MVP queda definido

Se espera que la Historia de Usuario 1 entregue un producto mínimo verificable de forma independiente. El informe de finalización recomienda un alcance de MVP, normalmente limitado a esa historia.

Esto le da a la fase de implementación un punto de parada intencional.

Dónde sigue siendo débil

Las pruebas son opcionales a menos que la especificación o el usuario las soliciten explícitamente. Para muchos repositorios de producción, ese valor predeterminado es demasiado permisivo. Una constitución o un preset puede exigir pruebas, pero la skill principal de tareas no lo hace.

Las rutas de archivos se generan antes de la implementación. En sistemas existentes, las rutas exactas pueden resultar incorrectas después de una exploración más profunda. La respuesta correcta es actualizar el plan o las tareas, no forzar el código en la ubicación que se había supuesto.

[P] también refleja independencia entre archivos, no todas las dependencias semánticas. Dos tareas pueden editar archivos distintos y aun así entrar en conflicto por una interfaz compartida o por el orden de una migración.

Lección para skills personalizadas: haz que cada elemento de trabajo tenga identidad, trazabilidad a su origen, alcance de modificación, estado de dependencias y una condición de aceptación independiente. Trata los marcadores de paralelismo como afirmaciones revisables, no como una verdad para el planificador.

Skill 5: speckit-analyze

Su verdadera función

analyze es un enlazador de solo lectura y analizador estático a nivel de artefactos para los artefactos de planificación.

Construye modelos internos de:

• requisitos y criterios de éxito
• acciones del usuario y criterios de aceptación
• cobertura de tareas
• reglas de la constitución

Luego comprueba duplicaciones, ambigüedad, especificación insuficiente, alineación con la constitución, cobertura, terminología, entidades y orden.

Los patrones de prompt más interesantes

1. La modificación está explícitamente prohibida

El procedimiento de análisis indica “STRICTLY READ-ONLY”, produce un informe y exige la aprobación explícita del usuario antes de aplicar correcciones. Más precisamente, no edita spec.md, plan.md ni tasks.md; su resolvedor puede registrar el estado de la funcionalidad bajo ciertas condiciones y los hooks configurados quedan fuera de esa garantía.

Este es un límite de confianza importante. Un verificador que edita silenciosamente el artefacto que evalúa puede ocultar evidencia y hacer imposible reproducir la revisión.

2. La autoridad de la constitución es explícita

La constitución no es negociable durante el análisis. Un conflicto no se puede “resolver” debilitando o reinterpretando la constitución dentro de la misma skill.

Los demás defectos regresan a la etapa responsable del artefacto afectado: los defectos de requisitos a specify o clarify, los de diseño a plan y los de descomposición a tasks.

3. El análisis produce cobertura, no solo texto

El informe incluye:

• IDs estables para los hallazgos
• severidad
• ubicaciones
• recomendaciones
• cobertura de requisitos por tareas
• tareas sin correspondencia
• métricas agregadas

Esto le da al usuario una base para tomar decisiones, no un simple “se ve bien”.

4. El análisis tiene un límite de salida

La skill limita los hallazgos a 50 y agrupa el excedente. Pide ejemplos de alto valor en lugar de volcar cada observación de estilo.

Dónde sigue siendo débil

El “modelo semántico” y la correspondencia de cobertura son inferidos por un modelo de lenguaje mediante IDs, palabras clave y frases clave. Esto no es trazabilidad formal. Una tarea puede mencionar el sustantivo correcto y aun así no satisfacer el requisito.

La skill pide IDs y recuentos deterministas entre ejecuciones, pero las salidas del modelo no son inherentemente deterministas. Los IDs explícitos y estables de requisitos ayudan; no garantizan una correspondencia semántica idéntica.

Lección para skills personalizadas: haz que las skills de auditoría sean de solo lectura a nivel de artefactos por defecto, define las restricciones que las rigen y produce una matriz de cobertura. Luego sé transparente sobre cuáles verificaciones son heurísticas y qué operaciones de configuración o hooks aún pueden escribir estado.

Skill 6: speckit-implement

Su verdadera función

implement es un ejecutor con estado.

Hace más que escribir código:

1. resuelve la funcionalidad activa
2. comprueba todas las listas de verificación de calidad si existe un directorio para ellas
3. pregunta antes de continuar si alguna lista está incompleta
4. carga las tareas, el plan, los artefactos de diseño opcionales, la constitución y la guía de validación
5. verifica los archivos de exclusión del proyecto
6. analiza las fases y dependencias de las tareas
7. ejecuta el trabajo fase por fase
8. marca las tareas completadas con [X]
9. se detiene si falla una tarea secuencial
10. valida la implementación contra los artefactos

Los patrones de prompt más interesantes

1. El estado de preparación es visible antes de modificar

Una lista incompleta no bloquea automáticamente para siempre, pero obliga a tomar una decisión explícita de continuar o detenerse. Es un buen modelo para controles flexibles:

evidence incomplete
  -> show exact status
  -> require conscious override
  -> continue only with recorded user intent

2. El progreso se registra fuera de la conversación

Cada tarea completada se marca en tasks.md. Una ejecución posterior puede reanudarse a partir del estado persistente en lugar de depender de la memoria de la conversación.

La guía oficial de funcionalidades complejas recomienda limitar la implementación por rango de tareas o por fase. Esta es una respuesta directa a la degradación de la ventana de contexto:

/speckit.implement only execute tasks T001-T010, then stop

3. El comportamiento ante fallos varía según el tipo de dependencia

• Fallo secuencial: detenerse.
• Fallo en paralelo: conservar el trabajo exitoso y reportar los fallos.
• Trabajo poco claro o bloqueado: explicarlo y sugerir los siguientes pasos.

La skill codifica una semántica operativa en lugar de limitarse a decir “maneja los errores”.

Dónde sigue siendo débil

Esta es la etapa más amplia y riesgosa.

La skill puede modificar código de aplicación, pruebas, estado de tareas, dependencias y configuración de archivos de exclusión. Su lógica genérica para esos archivos puede ser útil en un proyecto nuevo, pero sorprendente para una funcionalidad acotada en un proyecto existente. Una skill personalizada rara vez debería heredar un contrato de modificación tan amplio sin declararlo explícitamente.

La casilla de una tarea también es solo una afirmación de progreso. Marcar [X] no demuestra la aceptación. Las pruebas deterministas del repositorio, CI y la revisión humana siguen siendo las autoridades.

Por último, una sola ejecución de implementación aún puede superar los límites de contexto. La propia documentación de Spec Kit recomienda acotar por fase, delegar o dividir funcionalidades grandes en especificaciones más pequeñas.

Lección para skills personalizadas: separa el estado de progreso del estado de aceptación, limita el alcance de modificación de cada ejecución y define un verificador externo obligatorio.

Las seis skills como un solo sistema de control

Los prompts individuales son útiles, pero su composición es el verdadero diseño:

Surgen varios principios reutilizables.

1. Cada skill tiene un verbo dominante

Especificar. Aclarar. Planificar. Descomponer. Analizar. Implementar.

Una skill puede realizar trabajo de apoyo, pero su contrato de modificación declarado en el prompt y su salida siguen organizados alrededor de un verbo.

2. Los artefactos son APIs entre skills

La siguiente skill no necesita toda la conversación. Necesita un artefacto validado con un esquema conocido.

3. La revisión de solo lectura a nivel de artefactos es una fase de primera clase

El análisis no está escondido al final de la implementación. Es una fase separada y no reescribe los tres artefactos que evalúa. El estado del resolvedor y los hooks configurados aún necesitan su propia revisión.

4. El flujo registra decisiones, no solo resultados

Los supuestos, las aclaraciones, las alternativas, los IDs de tareas, los estados de las listas de verificación y el trabajo completado sobreviven a la sesión del modelo.

5. La mayoría de los ciclos tienen condiciones de parada visibles

Los ciclos de aclaración, validación, hallazgos y flujo de trabajo están acotados. La implementación ejecuta todas las tareas por defecto; limitarla por rango de tareas o fase es una recomendación documentada que el usuario debe solicitar.

6. El prompt no pretende ser un mecanismo de control

La documentación del flujo advierte explícitamente que los pasos de shell se ejecutan con privilegios locales y que el motor del flujo no es un sandbox de capacidades. Las instrucciones influyen en el comportamiento; los permisos del sistema operativo, las políticas de herramientas, CI y la revisión limitan el impacto.

Qué puede aprender un flujo de especificaciones específico para una empresa

Supongamos que una empresa quiere una herramienta interna de especificaciones para cambios en servicios de cara al cliente. La empresa ya tiene un proceso de ingeniería con reglas definidas:

• cada especificación debe indicar objetivos, lo que queda fuera, responsables y criterios de aceptación medibles
• los cambios en APIs públicas requieren un plan de compatibilidad
• los cambios en datos persistentes requieren planes de migración, backfill y rollback
• los cambios en autenticación o autorización requieren un modelo de amenazas
• cada despliegue necesita secciones de observabilidad, feature flags y rollback
• la implementación no puede comenzar hasta que se registren las aprobaciones de producto e ingeniería

La implementación incorrecta sería un enorme prompt de “sigue nuestro proceso”. Mezclaría descubrimiento de producto, arquitectura, gobernanza, planificación de tareas y cambios de código en un solo contexto.

El diseño más sólido es un pipeline específico para la empresa:

feature request
      |
      v
[company-specify]  -> spec.md from the product requirements template
      |
      v
[company-clarify]  -> decisions.md + resolved requirements
      |
      v
[company-plan]     -> plan.md + API/data/security/rollout sections
      |
      v
[company-tasks]    -> tasks.md with owners, dependencies, and checks
      |
      v
[company-analyze]  -> read-only policy and coverage report
      |
      v
[company-implement] -> scoped code changes + durable task state

Esto no es Spec Kit con los nombres cambiados. La empresa controla los esquemas de los artefactos y las reglas de transición.

Las reglas específicas deben estar en entradas versionadas, no solo en texto dentro de una skill:

.company-spec/
|-- constitution.md
|-- profiles/
|   |-- service-change.yaml
|   |-- data-migration.yaml
|   `-- security-sensitive.yaml
|-- templates/
|   |-- spec.md
|   |-- plan.md
|   `-- tasks.md
|-- policies/
|   |-- api-compatibility.md
|   |-- data-migrations.md
|   `-- production-rollouts.md
|-- scripts/
|   `-- company-spec-context
`-- skills/
    |-- company-specify/
    |-- company-clarify/
    |-- company-plan/
    |-- company-tasks/
    |-- company-analyze/
    `-- company-implement/

Las plantillas definen la salida requerida. Los perfiles determinan qué secciones de plantilla y controles se aplican a una clase de cambio. Las políticas proporcionan reglas detalladas. El resolvedor de contexto devuelve datos como el cambio activo, el responsable del servicio, el tipo de repositorio, el perfil seleccionado y las rutas de los artefactos. Las skills siguen siendo procedimientos acotados que conectan esas entradas.

Un patrón concreto de skill personalizada

Considera la etapa de planificación. Su función no es inventar el proceso de la empresa. Su función es aplicar el perfil seleccionado y producir un plan técnico revisable.

---
name: company-plan
description: Create the approved technical plan for a company service change. Use after company-specify and company-clarify have produced an approved spec.
metadata:
  owner: platform-engineering
  version: "1.0"
---

# Company Plan

## Mutation Contract
- May create or update plan.md in the active change directory.
- May add research notes under research/.
- Do not edit spec.md, tasks.md, or application code.

## Preflight
1. Run `.company-spec/scripts/company-spec-context plan --json` once.
2. Read the returned spec, constitution, profile, plan template, service metadata, and policy paths.
3. Stop if spec status is not `approved`.
4. Stop if a high-impact clarification remains unresolved.

## Artifact Contract
Populate the resolved plan template without deleting required headings.

Always include:
- architecture and affected boundaries
- requirement-to-design mapping
- test strategy
- observability and rollout
- rollback conditions

When selected by the profile:
- public API compatibility and deprecation
- schema migration and backfill
- threat model and permission changes
- privacy or regulatory review

## Decision Rules
- Prefer existing approved platform components.
- Record each material alternative and rejection reason.
- Do not invent service metadata; report missing catalog data.
- A policy exception must name its owner and approval record.

## Validation
1. Run `company-spec validate plan --change "$CHANGE_ID"`.
2. Revise schema or coverage failures; maximum two passes.
3. Stop on policy failures that require human approval.

## Done When
- Every requirement maps to a design decision.
- Every applicable profile gate passes or has an approved exception.
- Rollout, observability, and rollback are testable.
- Validation exits successfully.

El resolvedor podría devolver:

{
  "changeId": "billing-webhook-retries",
  "profile": "service-change",
  "specStatus": "approved",
  "specPath": "changes/billing-webhook-retries/spec.md",
  "planPath": "changes/billing-webhook-retries/plan.md",
  "planTemplate": ".company-spec/templates/plan.md",
  "service": {
    "name": "billing-api",
    "owner": "payments-platform",
    "tier": 1
  },
  "requiredPolicies": [
    ".company-spec/policies/api-compatibility.md",
    ".company-spec/policies/production-rollouts.md"
  ]
}

El script resuelve el contexto determinista; la skill toma decisiones técnicas. Si falta el responsable del servicio, el resolvedor reporta ese dato. El modelo no debería adivinarlo.

La skill tampoco incorpora todas las reglas de API, migración y despliegue. Esos detalles permanecen en archivos de políticas versionados y se cargan solo cuando el perfil seleccionado los requiere. Esto sigue el principio de divulgación progresiva de la especificación de Agent Skills, al tiempo que mantiene las reglas reales de la empresa disponibles para revisión fuera del prompt.

Un plan práctico para construir el flujo de la empresa

Construye el flujo desde las políticas hacia afuera:

1. Elige una clase de cambio. Comienza con cambios en servicios de cara al cliente en lugar de intentar modelar todos los flujos de ingeniería.
2. Escribe los contratos de los artefactos. Define los campos obligatorios y ejemplos para spec.md, plan.md y tasks.md.
3. Crea perfiles. Codifica cuándo son obligatorias las secciones de API, datos, seguridad, privacidad y despliegue.
4. Construye una resolución de contexto determinista. Resuelve como JSON el cambio activo, el repositorio, el responsable del servicio, el nivel de riesgo, el perfil y las rutas de los artefactos.
5. Implementa skills acotadas. Dale a specify, clarify, plan, tasks, analyze e implement contratos de lectura y escritura y condiciones de parada independientes.
6. Agrega verificaciones automatizadas. Valida la estructura de las plantillas, las aprobaciones obligatorias, la cobertura de requisitos, los identificadores de tareas y las excepciones de políticas sin depender por completo del criterio del modelo.
7. Haz una prueba piloto con cambios reales. Compara los artefactos generados con el proceso de revisión actual de la empresa antes de permitir modificaciones durante la etapa de implementación.
8. Versiona y gobierna el flujo. Asigna responsables a plantillas, políticas, perfiles, scripts y skills; registra los cambios incompatibles del proceso.

Prueba el comportamiento, no la redacción del prompt:

Entre las métricas operativas útiles están la tasa de validación al primer intento, la cantidad de aclaraciones, las excepciones de políticas, el retrabajo de revisión, los defectos de requisitos no detectados, los fallos de planes de rollback y el tiempo transcurrido desde la especificación aprobada hasta la implementación aceptada. El objetivo no es maximizar los documentos generados. Es hacer explícitas las decisiones importantes de la empresa antes de que el código sea costoso de cambiar.

Qué no copiar

Spec Kit es una fuente rica de patrones, pero copiarlo mecánicamente empeoraría el flujo de la empresa.

Cuándo vale la pena usar el pipeline completo

La arquitectura compensa cuando el costo de un requisito mal entendido supera el costo de mantener los artefactos intermedios. Para profundizar en los fundamentos de planificación más allá de este análisis, consulta Planificación correcta para el desarrollo de ingeniería; para el diseño más amplio del repositorio, consulta Construyamos repositorios centrados en prompts.

La lección de diseño más profunda

La forma más útil de pensar en las Agent Skills no es:

prompt snippets the model can remember

Es:

small operating procedures
with typed inputs,
bounded authority,
durable state,
artifact schemas,
validation,
and explicit handoffs

Spec Kit es interesante porque hace visibles esas propiedades.

specify controla la intención. clarify controla la incertidumbre. plan controla el compromiso técnico. tasks controla la descomposición. analyze controla las inconsistencias. implement controla la ejecución.

La cadena no garantiza que se produzca software correcto. Está diseñada para que los errores aparezcan en un límite donde sea más barato corregirlos y más fácil atribuirlos.

Esa es la lección que vale la pena llevar a cualquier flujo personalizado.

Fuentes

Fuentes primarias y oficiales, consultadas el July 17, 2026:

• Lanzamiento de GitHub Spec Kit v0.13.0 — versión fijada y fecha de lanzamiento
• README de Spec Kit en v0.13.0 — enfoque del proyecto, inventario de comandos y skills, integraciones, extensiones, presets y paquetes
• Referencia de Agentic SDD en v0.13.0 — orden y comportamiento oficiales de las fases
• Guía de inicio rápido en v0.13.0 — recorridos breve y de producción, comportamiento del estado de la funcionalidad
• Plantilla de specify en v0.13.0 — flujo de especificación, límite de aclaraciones y ciclo de calidad
• Plantilla de clarify en v0.13.0 — taxonomía de ambigüedad, preguntas secuenciales y escrituras incrementales
• Plantilla de plan en v0.13.0 — fases de investigación y diseño, verificaciones de la constitución
• Plantilla de tasks en v0.13.0 — formato estricto de tareas, organización por historias de usuario y marcadores de paralelismo
• Plantilla de analyze en v0.13.0 — análisis de solo lectura a nivel de artefactos, cobertura semántica, severidad y límites de salida
• Plantilla de implement en v0.13.0 — control de listas de verificación, reglas de ejecución, seguimiento del progreso y verificaciones de finalización
• Integración de Cursor en v0.13.0 — estructura de .cursor/skills y modo de skills predeterminado
• Generador de integración de skills en v0.13.0 — transformación de plantillas comunes en Agent Skills
• Gestión de funcionalidades complejas — delimitación de la implementación y orientación sobre la ventana de contexto
• Referencia de flujos de trabajo en v0.13.0 — estado reanudable, controles, ciclos, fan-out y límite de seguridad del shell
• GitHub Blog: desarrollo guiado por especificaciones con IA — motivos históricos del lanzamiento, publicado el September 2, 2025
• Especificación de Agent Skills — estructura portable de skills y orientación sobre divulgación progresiva

Lecturas relacionadas en este devlog:

• Planificación correcta para el desarrollo de ingeniería
• OpenSpec vs GitHub Spec Kit
• Cómo gestionar el feedback en GitHub Spec Kit
• Una estrategia de modelos fase por fase para GitHub Spec Kit
• De la especificación a la entrega paralela
• Construyamos repositorios centrados en prompts