Instalar Spec Kit: specify-cli y los cambios en los comandos /speckit-*

Spec Kit es el kit de herramientas de código abierto de GitHub para el desarrollo guiado por especificaciones (Spec-Driven Development): primero se escribe la especificación, después un plan y tareas, y por último tu asistente de programación con IA implementa las tareas. Su línea de comandos se llama specify y viene del paquete specify-cli.

Muchos tutoriales en internet siguen usando el comando de instalación antiguo, el indicador --ai y nombres de comando como /speckit.specify, y al copiarlos suele fallar. Esta página recoge, siguiendo la documentación oficial, la forma correcta actual y enumera qué ha cambiado.

Cuándo se comprobó

Redactada a partir de la documentación oficial de Spec Kit y comprobada el 26-10-2026. El proyecto avanza rápido, así que si algo difiere, fíate de specify --help en tu equipo y de la documentación oficial antes que de esta página.

Para quién es

• Quienes quieran probar un flujo guiado por especificaciones dentro de un asistente de programación con IA como Claude Code, GitHub Copilot, Gemini CLI, CodeBuddy CLI, Pi u Oh My Pi.
• Quienes instalaron Spec Kit siguiendo un tutorial antiguo y ahora ven errores o comandos que no aparecen.

Requisitos previos

Elemento	Requisito
Sistema operativo	Linux, macOS o Windows (los scripts de PowerShell funcionan sin WSL)
Python	3.11 o superior
Gestor de paquetes	uv (recomendado) o pipx
Asistente de programación con IA	Cualquier asistente compatible; la documentación oficial enumera decenas de integraciones
Git	Opcional, solo necesario si se activa la extensión de git

Spec Kit en sí no necesita Node.js. Si tu asistente se instala con npm, consulta primero Instalación de AI Agent CLI.

Instalar specify-cli

Opción 1: desde PyPI (la más corta)

# Recomendado: uv
uv tool install specify-cli

# O pipx
pipx install specify-cli

# O pip
pip install specify-cli

Para fijar una versión: uv tool install specify-cli==0.12.11 (usa la versión de la página de releases).

Opción 2: desde una etiqueta de release de GitHub

La documentación oficial la presenta como la vía reproducible recomendada. Necesita uv:

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z

Sustituye vX.Y.Z por una etiqueta de Releases. Conserva la v inicial, por ejemplo v0.12.11.

Verificar la instalación

specify version
specify self check

specify version confirma que el comando funciona e imprime su versión. specify self check es de solo lectura e indica si hay una versión más reciente.

Inicializar un proyecto

specify init my-project --integration claude
cd my-project

--integration elige tu asistente de IA. Los valores habituales son claude, copilot, gemini, codebuddy, pi y omp. Opciones útiles:

• --script sh|ps|py: elige el tipo de script. Por defecto es ps en Windows y sh en el resto.
• --here --force: inicializa dentro de un directorio existente que no está vacío. --force reconoce la advertencia de fusión, así que haz commit o copia de seguridad de tus cambios locales antes.
• --non-interactive: para CI. Sin --integration se elige GitHub Copilot por defecto; no te sorprenda ese valor.

Nombres de comando: /speckit-*

Después de inicializar, ejecuta estos comandos en el chat de tu asistente de IA, no en el terminal:

Paso	Comando	Qué hace
1	/speckit-constitution	Escribe los principios del proyecto con los que se comprueban los pasos posteriores; una vez por proyecto
2	/speckit-specify	Convierte una descripción de la funcionalidad en lenguaje corriente en spec.md
3	/speckit-clarify	Pregunta por los huecos de la especificación e incorpora las respuestas
4	/speckit-plan	Genera plan.md y otros artefactos de diseño para tu pila tecnológica
5	/speckit-checklist	Genera una lista de comprobación de la calidad de los requisitos
6	/speckit-tasks	Genera un tasks.md ordenado por dependencias
7	/speckit-analyze	Comprobación de solo lectura de conflictos y huecos entre spec.md, plan.md y tasks.md
8	/speckit-implement	Ejecuta tasks.md en orden
9	/speckit-converge	Comprueba el código frente a la especificación y añade tareas por cada hueco; repite implement y converge hasta que informe Converged

El camino más corto es specify → plan → tasks → implement → converge. Solo el camino completo añade constitution, clarify, checklist y analyze.

Tu asistente puede escribirlos de otra forma

El inicio rápido oficial usa los nombres con guion /speckit-* (el modo de skills predeterminado de GitHub Copilot). Los tutoriales antiguos y las notas de actualización aún muestran la forma con punto, como /speckit.specify. El formato de invocación cambia según el asistente y el modo, así que guíate por los nombres que aparezcan de verdad en la lista de comandos de tu asistente tras la inicialización.

Qué ha cambiado respecto a los tutoriales antiguos

Habitual en tutoriales antiguos	Ahora
Solo uv tool install ... --from git+https://...	specify-cli también está en PyPI y se instala con uv, pipx o pip; la instalación desde una etiqueta de GitHub sigue siendo compatible
specify init --ai claude	La documentación oficial usa --integration claude en todas partes
/speckit.specify, /speckit.plan	El inicio rápido usa /speckit-specify y /speckit-plan, y añade /speckit-converge
/constitution propaga los cambios a las plantillas y a los archivos de comandos	Ahora solo actualiza .specify/memory/constitution.md; para recuperar la propagación antigua, ejecuta specify preset add constitution-sync
Las funciones de git siempre activas	Ahora son una extensión opcional: specify extension add git
La funcionalidad activa se deduce de la rama de Git	.specify/feature.json registra el directorio de la funcionalidad activa

Actualizar

Actualizar la propia línea de comandos:

specify self check                 # solo lectura: ¿hay una versión más reciente?
specify self upgrade --dry-run     # vista previa sin actualizar
specify self upgrade               # actualizar a la última versión estable
specify self upgrade --tag vX.Y.Z  # fijar una etiqueta de release

Actualizar los archivos de un proyecto existente, desde el directorio del proyecto:

specify integration status         # listar integraciones instaladas y archivos modificados
specify integration upgrade <key>  # ejecutar una vez por cada integración instalada
specify extension update           # actualizar todas las extensiones

Pasa --force a specify integration upgrade solo cuando el comando informe de archivos gestionados modificados localmente y hayas revisado la diferencia.

Problemas comunes

• command not found: uv: instala uv primero y vuelve a ejecutar el comando de instalación.
• No such option: --integration: hay un specify antiguo (por ejemplo 0.1.6) antes en tu PATH. Reinstala con la misma herramienta que usaste al principio, por ejemplo uv tool install --force specify-cli, y confírmalo con specify version.
• Dos copias instaladas: instalar con uv, pipx y pip deja una copia distinta cada vez. Actualiza con la misma herramienta y no las mezcles.
• Una instalación desde PyPI no se actualiza sola: la versión se queda donde la instalaste, así que usa los comandos de actualización de arriba.
• Init rechaza un directorio existente: tras hacer commit o copia de seguridad, añade --here --force.

Siguientes pasos

• Para decidir entre Spec Kit y OpenSpec, lee Spec Kit frente a OpenSpec.
• Para ver el flujo de especificaciones que usa el propio HagiCode, lee la Introducción a OpenSpec.

Documentación oficial de Spec Kit