This page is generated from the following source files:
Before installing Spec Kit, ensure the development environment meets the following requirements:
| Requirement | Version | Purpose |
|---|---|---|
| Python | 3.11+ | Runtime environment for Specify CLI (docs/installation.md:8) |
| uv | Latest | Package management tool (docs/installation.md:7) |
| Git | Latest | Version control and repository operations (docs/installation.md:9) |
| AI Coding Agent | Any supported | Code generation and spec execution |
Supported Operating Systems:
Supported AI Agents:
The toolkit supports a wide range of AI coding agents, including but not limited to:
| Agent | Support Status | Notes |
|---|---|---|
| Claude Code | ✅ | Full support (README.md:182) |
| GitHub Copilot | ✅ | Full support (README.md:187) |
| Gemini CLI | ✅ | Full support (README.md:186) |
| Cursor | ✅ | Full support (README.md:185) |
| Codex CLI | ✅ | Requires --ai-skills flag (README.md:184) |
| Windsurf | ✅ | Full support (README.md:200) |
For a complete list of 25+ supported agents, refer to the Supported AI Agents section in the README.
Spec Kit offers three installation approaches to accommodate different workflow preferences and enterprise requirements.
This method installs Specify CLI permanently on the system, making it available globally in PATH.
Install a specific stable release:
bash1# Replace vX.Y.Z with the latest release tag from https://github.com/github/spec-kit/releases 2uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z
Install latest from main branch:
bash1uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
Benefits of persistent installation:
uv tool list, uv tool upgrade, uv tool uninstall (README.md:101)For users who prefer not to install the tool permanently, uvx allows running Specify CLI directly.
Create a new project:
bash1# Replace vX.Y.Z with the latest release tag 2uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT_NAME>
Initialize in existing project:
bash1uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init . --ai claude
Alternative syntax for existing projects:
bash1uvx --from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init --here --ai claude
For environments that block access to PyPI or GitHub, Spec Kit provides an enterprise installation guide. This method uses pip download to create portable, OS-specific wheel bundles on a connected machine for transfer to air-gapped systems (README.md:106).
Refer to the Enterprise / Air-Gapped Installation guide for detailed step-by-step instructions.
| Method | Use Case | Pros | Cons |
|---|---|---|---|
| Persistent | Daily development | Always available, easy updates | Requires manual upgrade |
| One-time | Occasional use, CI/CD | No system modification | Longer startup time |
| Enterprise | Air-gapped environments | Works offline | Manual bundle management |
This section provides the fastest path to get Spec Kit running with a new or existing project.
After installation, initialize Spec Kit in the target project directory.
Create a new project:
bash1specify init <PROJECT_NAME>
Initialize in existing project with Claude:
bash1specify init . --ai claude
Alternative syntax:
bash1specify init --here --ai claude
Run the check command to verify all required tools are installed:
bash1specify check
This command validates:
AGENT_CONFIG (e.g., claude, gemini, code/code-insiders, cursor-agent, windsurf, junie, qwen, opencode, codex, kiro-cli, shai, qodercli, vibe, kimi, iflow, pi) (README.md:215)Start the AI assistant in the project directory. Most agents expose Spec Kit as /speckit.* slash commands (README.md:110).
Note: Codex CLI in skills mode uses $speckit-* syntax instead of slash commands (README.md:110).
Spec Kit follows a spec-driven development workflow with six primary commands.
Use the /speckit.constitution command to create governing principles and development guidelines:
bash1/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements
This command establishes the project's constitution that guides all subsequent development decisions.
Use the /speckit.specify command to describe the desired functionality. Focus on what and why, not the technical implementation:
bash1/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.
Use the /speckit.plan command to define the tech stack and architecture:
bash1/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.
Use /speckit.tasks to create an actionable task list from the implementation plan:
bash1/speckit.tasks
Use /speckit.implement to execute all tasks and build the feature:
bash1/speckit.implement
After installation, confirm Specify CLI is properly installed:
bash1specify check
Expected behavior: The command checks for git and all configured CLI-based agents (README.md:215).
After running specify init, the project directory should contain the Spec Kit configuration files and agent-specific command files. The exact structure depends on the AI agent selected during initialization.
To upgrade to a newer version:
bash1uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.Z
For detailed upgrade instructions, refer to the Upgrade Guide (README.md:77).
Symptoms: Running specify command returns "command not found" error.
Possible Causes:
uv tool directory is not in PATHSolutions:
uv is properly installed: uv --versionspecify-cli is in the tool list: uv tool listuv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@vX.Y.ZSymptoms: Slash commands like /speckit.constitution are not recognized by the AI agent.
Possible Causes:
Solutions:
--ai flag was used during initialization (README.md:69)--ai-skills flag and $speckit-* syntax instead of slash commands (README.md:184)specify init . --ai <agent-name>Symptoms: Installation fails due to blocked access to PyPI or GitHub.
Solution: Use the Enterprise / Air-Gapped Installation method which creates portable wheel bundles on a connected machine for transfer (README.md:106).
Symptoms: Unexpected behavior after upgrading or using latest main branch.
Possible Causes:
Solutions:
Symptoms: Installation fails with Python version errors.
Solution: Ensure Python 3.11 or higher is installed (docs/installation.md:8). Verify with:
bash1python --version
After completing the quick start, explore these resources for deeper understanding:
Comprehensive Guide: Follow the detailed step-by-step instructions in spec-driven.md (README.md:150)
Video Overview: Watch the video overview to see Spec Kit in action (README.md:154)
Community Walkthroughs: Explore real-world examples:
Customization: Learn about Extensions & Presets to customize Spec Kit for specific workflows (README.md:28)
CLI Reference: Review the complete Specify CLI command reference for advanced options (README.md:206)