Agent Configuration

Project Initialization

The primary way to configure agent integration is through the specify init command. This sets up the complete project structure with agent-specific configurations.

Basic Initialization

New Project
Existing Project

Create a new project directory with Spec Kit integration:

# Interactive mode - prompts for agent selection
specify init my-project

# Direct agent specification
specify init my-project --ai claude
specify init my-project --ai gemini
specify init my-project --ai copilot

Initialize Spec Kit in an existing directory:

# Using dot notation
specify init . --ai claude

# Using --here flag (recommended)
specify init --here --ai windsurf

# Force merge without confirmation
specify init --here --force --ai cursor-agent

Agent-Specific Configuration

Each agent has unique configuration requirements based on its directory structure and command format.

Claude Code Configuration

Directory Structure:

.claude/
└── commands/
    ├── speckit.constitution.md
    ├── speckit.specify.md
    ├── speckit.plan.md
    ├── speckit.tasks.md
    ├── speckit.implement.md
    ├── speckit.clarify.md
    ├── speckit.analyze.md
    ├── speckit.checklist.md
    └── speckit.taskstoissues.md

Initialization:

specify init my-project --ai claude

Special Notes:

Uses Markdown format with $ARGUMENTS for argument passing
Supports the claude migrate-installer command
CLI tool checked at ~/.claude/local/claude as fallback

Gemini CLI Configuration

Directory Structure:

.gemini/
└── commands/
    ├── speckit.constitution.toml
    ├── speckit.specify.toml
    ├── speckit.plan.toml
    ├── speckit.tasks.toml
    ├── speckit.implement.toml
    ├── speckit.clarify.toml
    ├── speckit.analyze.toml
    ├── speckit.checklist.toml
    └── speckit.taskstoissues.toml

Initialization:

specify init my-project --ai gemini

Special Notes:

Uses TOML format with {{args}} for argument passing
Requires gemini CLI tool installation
Commands stored in prompt field of TOML files

GitHub Copilot Configuration

Directory Structure:

.github/
└── agents/
    ├── speckit.constitution.agent.md
    ├── speckit.specify.agent.md
    ├── speckit.plan.agent.md
    ├── speckit.tasks.agent.md
    ├── speckit.implement.agent.md
    ├── speckit.clarify.agent.md
    ├── speckit.analyze.agent.md
    ├── speckit.checklist.agent.md
    └── speckit.taskstoissues.agent.md

Initialization:

specify init my-project --ai copilot

Special Notes:

Uses .agent.md extension with special mode frontmatter field
IDE-based, no CLI tool requirement
Commands stored in .github/agents/ (not commands/ subdirectory)

Windsurf Configuration

Directory Structure:

.windsurf/
└── workflows/
    ├── speckit.constitution.md
    ├── speckit.specify.md
    ├── speckit.plan.md
    ├── speckit.tasks.md
    ├── speckit.implement.md
    ├── speckit.clarify.md
    ├── speckit.analyze.md
    ├── speckit.checklist.md
    └── speckit.taskstoissues.md

Initialization:

specify init my-project --ai windsurf

Special Notes:

Uses workflows/ subdirectory instead of commands/
IDE-based, no CLI tool requirement
Markdown format with $ARGUMENTS

opencode Configuration

Directory Structure:

.opencode/
└── command/          # Note: singular 'command', not 'commands'
    ├── speckit.constitution.md
    ├── speckit.specify.md
    ├── speckit.plan.md
    ├── speckit.tasks.md
    ├── speckit.implement.md
    ├── speckit.clarify.md
    ├── speckit.analyze.md
    ├── speckit.checklist.md
    └── speckit.taskstoissues.md

Initialization:

specify init my-project --ai opencode

Special Notes:

Uses singular command/ directory (unique to opencode)
Requires opencode CLI tool installation
Markdown format with $ARGUMENTS

Generic Agent Configuration

Custom Directory Structure:

.myagent/              # Your custom directory
└── commands/          # Or your custom subdirectory
    ├── speckit.constitution.md
    ├── speckit.specify.md
    ├── speckit.plan.md
    └── ...

Initialization:

specify init my-project --ai generic --ai-commands-dir .myagent/commands/

Special Notes:

Requires --ai-commands-dir parameter
Creates standard Markdown format commands
No CLI tool checks performed
Useful for unsupported or custom agents

Advanced Configuration Options

Script Type Selection

Choose between POSIX shell scripts (bash/zsh) or PowerShell scripts:

specify init my-project --ai claude --script sh

When to use each:

sh: Linux, macOS, WSL, or bash-compatible environments (default)
ps: Windows with PowerShell, cross-platform PowerShell scenarios

Agent Skills Installation

Install commands as agentskills.io compatible skills:

specify init my-project --ai claude --ai-skills

What this does:

Creates agent-specific skills/ directory (e.g., .claude/skills/)
Converts each command to a skill with SKILL.md file
Adds enhanced descriptions and metadata
Enables skill discovery and portability

Example skill structure:

.claude/
├── commands/
│   └── speckit.specify.md
└── skills/
    └── speckit-specify/
        └── SKILL.md

Skill file format:

---
name: speckit-specify
description: Create or update feature specifications from natural language descriptions. Use when starting new features or refining requirements.
compatibility: Requires spec-kit project structure with .specify/ directory
metadata:
  author: github-spec-kit
  source: templates/commands/specify.md
---

# Speckit Specify Skill

[Command content...]

Git Repository Management

Automatic Git Init (Default)
Skip Git Initialization

By default, Spec Kit initializes a Git repository with an initial commit:

specify init my-project --ai claude
# Creates git repo, commits initial structure

Disable automatic Git repository creation:

specify init my-project --ai claude --no-git
# Project created without git init

Tool Requirement Override

Skip CLI tool checks during initialization:

specify init my-project --ai claude --ignore-agent-tools

Use this flag only when:

You’re setting up templates for later use
The agent tool is installed in a non-standard location
You’re creating documentation or examples

You’ll still need the agent tool to actually use the commands.

GitHub API Configuration

When working in environments with rate limiting (CI/CD, corporate networks):

specify init my-project --ai claude --github-token ghp_your_token_here

Benefits:

Increases rate limit from 60/hour to 5,000/hour
Required in some corporate/CI environments
Prevents template download failures

Debug Mode

Enable verbose diagnostic output for troubleshooting:

specify init my-project --ai claude --debug

Debug output includes:

Detailed API request/response information
Template extraction progress
File creation operations
Error stack traces

Project Structure

Regardless of the agent chosen, all projects share this core structure:

my-project/
├── .specify/                    # Core Spec Kit directory
│   ├── memory/
│   │   └── constitution.md      # Project principles (from template)
│   ├── scripts/
│   │   ├── bash/               # POSIX shell scripts
│   │   │   ├── create-new-feature.sh
│   │   │   ├── setup-plan.sh
│   │   │   └── ...
│   │   └── powershell/         # PowerShell scripts
│   │       ├── Create-New-Feature.ps1
│   │       ├── Setup-Plan.ps1
│   │       └── ...
│   ├── specs/                  # Feature specifications (created during workflow)
│   │   └── 001-feature-name/
│   │       ├── spec.md
│   │       ├── plan.md
│   │       └── tasks.md
│   └── templates/              # Document templates
│       ├── spec-template.md
│       ├── plan-template.md
│       ├── tasks-template.md
│       ├── constitution-template.md
│       └── checklist-template.md
├── .<agent>/                   # Agent-specific directory
│   ├── commands/              # (or workflows/, prompts/, agents/)
│   │   └── speckit.*.md       # (or .toml, .agent.md)
│   └── skills/                # (optional, with --ai-skills)
│       └── speckit-*/
│           └── SKILL.md
└── .git/                       # Git repository (unless --no-git)

Environment Variables

SPECIFY_FEATURE

Override automatic feature detection for non-Git repositories:

# Set before using /speckit.plan or follow-up commands
export SPECIFY_FEATURE="001-photo-albums"

# Then run commands in your AI agent
/speckit.plan ...
/speckit.tasks

When to use:

Working in a repository without Git branches
Overriding automatic feature directory detection
Testing or debugging feature workflows

Note: Must be set in the agent’s environment context, not just your shell.

GitHub Authentication

Configure GitHub API access:

# Option 1: GITHUB_TOKEN (recommended)
export GITHUB_TOKEN=ghp_your_token_here

# Option 2: GH_TOKEN (GitHub CLI compatible)
export GH_TOKEN=ghp_your_token_here

# Then initialize project
specify init my-project --ai claude

Multi-Agent Projects

You can initialize a project with multiple agents by running specify init multiple times:

# Initialize with Claude
specify init my-project --ai claude

# Add Gemini support
cd my-project
specify init --here --ai gemini --force

# Add GitHub Copilot support
specify init --here --ai copilot --force

Result:

my-project/
├── .specify/          # Shared infrastructure
├── .claude/
│   └── commands/
├── .gemini/
│   └── commands/
└── .github/
    └── agents/

While technically possible, using multiple agents in the same project can lead to:

Confusion about which agent to use
Potential conflicts in generated files
Difficulty maintaining consistency

Recommendation: Choose one primary agent per project for best results.

Updating Agent Configurations

To update agent configurations after initialization:

Upgrade Specify CLI

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

Reinitialize Project

cd my-project
specify init --here --ai claude --force

The --force flag merges new templates and commands without prompting. Your existing .specify/specs/ and .specify/memory/constitution.md are preserved.

Review Changes

Check updated command files and templates:

git diff .claude/commands/
git diff .specify/templates/

Customizing Commands

You can customize the generated slash commands after initialization:

Markdown Commands
TOML Commands

Edit command files directly in .claude/commands/, .cursor/commands/, .opencode/command/, etc.

---
description: "Your custom description"
---

# Custom prompt content

Your custom instructions here...

Execute: bash .specify/scripts/bash/create-new-feature.sh $ARGUMENTS

Edit TOML configuration in .gemini/commands/ or .qwen/commands/:

description = "Your custom description"

prompt = """
# Custom prompt content

Your custom instructions here...

Execute: bash .specify/scripts/bash/create-new-feature.sh {{args}}
"""

Customizations are overwritten when you run specify init --here --force. To preserve customizations:

Back up modified command files before upgrading
Use version control to track changes
Reapply customizations after upgrade
Consider contributing improvements upstream

Troubleshooting

Commands not appearing in agent

Symptoms: Slash commands don’t show up in your AI agentSolutions:

Restart your AI agent or IDE

Verify command files exist in the correct directory:

ls -la .claude/commands/
ls -la .gemini/commands/

Check file permissions (especially on Unix systems):
```
chmod 644 .claude/commands/*.md
```
Ensure you’re in the project root directory

Script execution failures

Symptoms: Commands fail when trying to execute scriptsSolutions:

Verify script executable permissions:

ls -la .specify/scripts/bash/
chmod +x .specify/scripts/bash/*.sh

Check script type matches your system:

# Should show sh scripts on Unix, ps on Windows
ls .specify/scripts/

Reinitialize with correct script type:

# For Windows PowerShell
specify init --here --ai claude --script ps --force

Template download failures

Symptoms: GitHub API rate limit errors during initializationSolutions:

Use GitHub token for authentication:

specify init my-project --ai claude --github-token ghp_your_token

Set environment variable:

export GITHUB_TOKEN=ghp_your_token
specify init my-project --ai claude

Wait for rate limit to reset (check with --debug flag)

Agent tool not found

Symptoms: CLI tool check fails during initializationSolutions:

Install the required CLI tool:
- Claude: https://docs.anthropic.com/en/docs/claude-code/setup
- Gemini: https://github.com/google-gemini/gemini-cli
- opencode: https://opencode.ai

Verify tool is in PATH:

which claude
which gemini
which opencode

Use --ignore-agent-tools to skip check (if you’ll install later):
```
specify init my-project --ai claude --ignore-agent-tools
```

Next Steps

Supported Agents

View all 15+ supported AI agents with installation links and status

Agent Overview

Learn about agent integration concepts and the spec-driven workflow

Quick Start Guide

Get started with your first spec-driven development project

CLI Reference

Complete reference for all Specify CLI commands

CLI Reference

Complete reference for all Specify CLI commands and options

Get Started

Core Concepts

CLI Reference

Slash Commands

AI Agents

Advanced

Agent Configuration

Project Initialization

Basic Initialization

Agent-Specific Configuration

Advanced Configuration Options

Script Type Selection

Agent Skills Installation

Git Repository Management

Tool Requirement Override

GitHub API Configuration

Debug Mode

Project Structure

Environment Variables

SPECIFY_FEATURE

GitHub Authentication

Multi-Agent Projects

Updating Agent Configurations

Customizing Commands

Troubleshooting

Next Steps

Supported Agents

Agent Overview

Quick Start Guide

CLI Reference

CLI Reference

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

Slash Commands

AI Agents

Advanced

​Project Initialization

​Basic Initialization

​Agent-Specific Configuration

​Advanced Configuration Options

​Script Type Selection

​Agent Skills Installation

​Git Repository Management

​Tool Requirement Override

​GitHub API Configuration

​Debug Mode

​Project Structure

​Environment Variables

​SPECIFY_FEATURE

​GitHub Authentication

​Multi-Agent Projects

​Updating Agent Configurations

​Customizing Commands

​Troubleshooting

​Next Steps

Supported Agents

Agent Overview

Quick Start Guide

CLI Reference

CLI Reference

Build docs developers (and LLMs) love

Project Initialization

Basic Initialization

Agent-Specific Configuration

Advanced Configuration Options

Script Type Selection

Agent Skills Installation

Git Repository Management

Tool Requirement Override

GitHub API Configuration

Debug Mode

Project Structure

Environment Variables

SPECIFY_FEATURE

GitHub Authentication

Multi-Agent Projects

Updating Agent Configurations

Customizing Commands

Troubleshooting

Next Steps