Extension User Guide

Complete guide for using Spec Kit extensions to enhance your workflow.

Introduction
Getting Started
Finding Extensions
Installing Extensions
Using Extensions
Managing Extensions
Configuration
Troubleshooting
Best Practices

Introduction

What are Extensions?

Extensions are modular packages that add new commands and functionality to Spec Kit without bloating the core framework. They allow you to:

Integrate with external tools (Jira, Linear, GitHub, etc.)
Automate repetitive tasks with hooks
Customize workflows for your team
Share solutions across projects

Why Use Extensions?

Clean Core: Keeps spec-kit lightweight and focused
Optional Features: Only install what you need
Community Driven: Anyone can create and share extensions
Version Controlled: Extensions are versioned independently

Getting Started

Prerequisites

Spec Kit version 0.1.0 or higher
A spec-kit project (directory with .specify/ folder)

Check Your Version

bash

specify version
# Should show 0.1.0 or higher

First Extension

Let's install the Jira extension as an example:

bash

# 1. Search for the extension
specify extension search jira

# 2. Get detailed information
specify extension info jira

# 3. Install it
specify extension add jira

# 4. Configure it
vim .specify/extensions/jira/jira-config.yml

# 5. Use it
# (Commands are now available in Claude Code)
/speckit.jira.specstoissues

Finding Extensions

specify extension search searches all active catalogs simultaneously, including the community catalog by default. Results are annotated with their source catalog and install status.

Browse All Extensions

bash

specify extension search

Shows all extensions across all active catalogs (default and community by default).

Search by Keyword

bash

# Search for "jira"
specify extension search jira

# Search for "issue tracking"
specify extension search issue

Filter by Tag

bash

# Find all issue-tracking extensions
specify extension search --tag issue-tracking

# Find all Atlassian tools
specify extension search --tag atlassian

Filter by Author

bash

# Extensions by Stats Perform
specify extension search --author "Stats Perform"

Show Verified Only

bash

# Only show verified extensions
specify extension search --verified

Get Extension Details

bash

# Detailed information
specify extension info jira

Shows:

Description
Requirements
Commands provided
Hooks available
Links (documentation, repository, changelog)
Installation status

Installing Extensions

Install from Catalog

bash

# By name (from catalog)
specify extension add jira

This will:

Download the extension from GitHub
Validate the manifest
Check compatibility with your spec-kit version
Install to .specify/extensions/jira/
Register commands with your coding agent
Create config template

Install from URL

bash

# From GitHub release
specify extension add <extension-name> --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip

Install from Local Directory (Development)

bash

# For testing or development
specify extension add --dev /path/to/extension

Installation Output

text

✓ Extension installed successfully!

Jira Integration (v1.0.0)
  Create Jira Epics, Stories, and Issues from spec-kit artifacts

Provided commands:
  • speckit.jira.specstoissues - Create Jira hierarchy from spec and tasks
  • speckit.jira.discover-fields - Discover Jira custom fields for configuration
  • speckit.jira.sync-status - Sync task completion status to Jira

⚠  Configuration may be required
   Check: .specify/extensions/jira/

Automatic Agent Skill Registration

If your project uses a skills-based integration (e.g., --integration claude, --integration codex) or was initialized with --integration-options="--skills", extension commands are automatically registered as agent skills during installation. This ensures that extensions are discoverable by agents that use the agentskills.io skill specification.

text

✓ Extension installed successfully!

Jira Integration (v1.0.0)
  ...

✓ 3 agent skill(s) auto-registered

When an extension is removed, its corresponding skills are also cleaned up automatically. Pre-existing skills that were manually customized are never overwritten.

Using Extensions

Using Extension Commands

Extensions add commands that appear in your coding agent (Claude Code):

text

# In Claude Code
> /speckit.jira.specstoissues

# Or use a namespaced alias (if provided)
> /speckit.jira.sync

Extension Configuration

Most extensions require configuration:

bash

# 1. Find the config file
ls .specify/extensions/jira/

# 2. Copy template to config
cp .specify/extensions/jira/jira-config.template.yml \
   .specify/extensions/jira/jira-config.yml

# 3. Edit configuration
vim .specify/extensions/jira/jira-config.yml

# 4. Use the extension
# (Commands will now work with your config)

Extension Hooks

Some extensions provide hooks that execute after core commands:

Example: Jira extension hooks into /speckit.tasks

text

# Run core command
> /speckit.tasks

# Output includes:
## Extension Hooks

**Optional Hook**: jira
Command: `/speckit.jira.specstoissues`
Description: Automatically create Jira hierarchy after task generation

Prompt: Create Jira issues from tasks?
To execute: `/speckit.jira.specstoissues`

You can then choose to run the hook or skip it.

Managing Extensions

List Installed Extensions

bash

specify extension list

Output:

text

Installed Extensions:

  ✓ Jira Integration (v1.0.0)
     Create Jira Epics, Stories, and Issues from spec-kit artifacts
     Commands: 3 | Hooks: 1 | Status: Enabled

Update Extensions

bash

# Check for updates (all extensions)
specify extension update

# Update specific extension
specify extension update jira

Output:

text

🔄 Checking for updates...

Updates available:

  • jira: 1.0.0 → 1.1.0

Update these extensions? [y/N]:

Disable Extension Temporarily

bash

# Disable without removing
specify extension disable jira

✓ Extension 'jira' disabled

Commands will no longer be available. Hooks will not execute.
To re-enable: specify extension enable jira

Re-enable Extension

bash

specify extension enable jira

✓ Extension 'jira' enabled

Remove Extension

bash

# Remove extension (with confirmation)
specify extension remove jira

# Keep configuration when removing
specify extension remove jira --keep-config

# Force removal (no confirmation)
specify extension remove jira --force

Configuration

Configuration Files

Extensions can have multiple configuration files:

text

.specify/extensions/jira/
├── jira-config.yml           # Main config (version controlled)
├── jira-config.local.yml     # Local overrides (gitignored)
└── jira-config.template.yml  # Template (reference)

Configuration Layers

Configuration is merged in this order (highest priority last):

Extension defaults (from extension.yml)
Project config (jira-config.yml)
Local overrides (jira-config.local.yml)
Environment variables (SPECKIT_JIRA_*)

Example: Jira Configuration

Project config (.specify/extensions/jira/jira-config.yml):

yaml

project:
  key: "MSATS"

defaults:
  epic:
    labels: ["spec-driven"]

Local override (.specify/extensions/jira/jira-config.local.yml):

yaml

project:
  key: "MYTEST"  # Override for local development

Environment variable:

bash

export SPECKIT_JIRA_PROJECT_KEY="DEVTEST"

Final resolved config uses DEVTEST from environment variable.

Project-Wide Extension Settings

File: .specify/extensions.yml

yaml

# Extensions installed in this project
installed:
  - jira
  - linear

# Global settings
settings:
  auto_execute_hooks: true

# Hook configuration
# Available events: before_specify, after_specify, before_plan, after_plan,
#                   before_tasks, after_tasks, before_implement, after_implement,
#                   before_analyze, after_analyze, before_checklist, after_checklist,
#                   before_clarify, after_clarify, before_constitution, after_constitution,
#                   before_taskstoissues, after_taskstoissues
hooks:
  after_tasks:
    - extension: jira
      command: speckit.jira.specstoissues
      enabled: true
      optional: true
      prompt: "Create Jira issues from tasks?"

Core Environment Variables

In addition to extension-specific environment variables (SPECKIT_{EXT_ID}_*), spec-kit supports core environment variables:

Variable	Description	Default
`SPECKIT_CATALOG_URL`	Override the full catalog stack with a single URL (backward compat)	Built-in default stack
`GH_TOKEN` / `GITHUB_TOKEN`	GitHub token for authenticated requests to GitHub-hosted URLs (`raw.githubusercontent.com`, `github.com`, `api.github.com`, `codeload.github.com`). Required when your catalog JSON or extension ZIPs are hosted in a private GitHub repository.	None

Example: Using a custom catalog for testing

bash

# Point to a local or alternative catalog (replaces the full stack)
export SPECKIT_CATALOG_URL="http://localhost:8000/catalog.json"

# Or use a staging catalog
export SPECKIT_CATALOG_URL="https://example.com/staging/catalog.json"

Example: Using a private GitHub-hosted catalog

bash

# Authenticate with a token (gh CLI, PAT, or GITHUB_TOKEN in CI)
export GITHUB_TOKEN=$(gh auth token)

# Search a private catalog added via `specify extension catalog add`
specify extension search jira

# Install from a private catalog
specify extension add jira-sync

The token is attached automatically to requests targeting GitHub domains. Non-GitHub catalog URLs are always fetched without credentials.

Extension Catalogs

Spec Kit uses a catalog stack — an ordered list of catalogs searched simultaneously. By default, two catalogs are active:

Priority	Catalog	Install Allowed	Purpose
1	`catalog.json` (default)	✅ Yes	Curated extensions available for installation
2	`catalog.community.json` (community)	❌ No (discovery only)	Browse community extensions

Listing Active Catalogs

bash

specify extension catalog list

Managing Catalogs via CLI

You can view the main catalog management commands using --help:

text

specify extension catalog --help

 Usage: specify extension catalog [OPTIONS] COMMAND [ARGS]...

 Manage extension catalogs
╭─ Options ────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                      │
╰──────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────╮
│ list     List all active extension catalogs.                                     │
│ add      Add a catalog to .specify/extension-catalogs.yml.                       │
│ remove   Remove a catalog from .specify/extension-catalogs.yml.                  │
╰──────────────────────────────────────────────────────────────────────────────────╯

Adding a Catalog (Project-scoped)

bash

# Add an internal catalog that allows installs
specify extension catalog add \
  --name "internal" \
  --priority 2 \
  --install-allowed \
  https://internal.company.com/spec-kit/catalog.json

# Add a discovery-only catalog
specify extension catalog add \
  --name "partner" \
  --priority 5 \
  https://partner.example.com/spec-kit/catalog.json

This creates or updates .specify/extension-catalogs.yml.

Removing a Catalog

bash

specify extension catalog remove internal

Manual Config File

You can also edit .specify/extension-catalogs.yml directly:

yaml

catalogs:
  - name: "default"
    url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"
    priority: 1
    install_allowed: true
    description: "Built-in catalog of installable extensions"

  - name: "internal"
    url: "https://internal.company.com/spec-kit/catalog.json"
    priority: 2
    install_allowed: true
    description: "Internal company extensions"

  - name: "community"
    url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json"
    priority: 3
    install_allowed: false
    description: "Community-contributed extensions (discovery only)"

A user-level equivalent lives at ~/.specify/extension-catalogs.yml. Project-level config takes full precedence when it contains one or more catalog entries. An empty catalogs: [] list falls back to built-in defaults.

Organization Catalog Customization

Why Customize Your Catalog

Organizations customize their catalogs to:

Control available extensions - Curate which extensions your team can install
Host private extensions - Internal tools that shouldn't be public
Customize for compliance - Meet security/audit requirements
Support air-gapped environments - Work without internet access

Setting Up a Custom Catalog

1. Create Your Catalog File

Create a catalog.json file with your extensions:

json

{
  "schema_version": "1.0",
  "updated_at": "2026-02-03T00:00:00Z",
  "catalog_url": "https://your-org.com/spec-kit/catalog.json",
  "extensions": {
    "jira": {
      "name": "Jira Integration",
      "id": "jira",
      "description": "Create Jira issues from spec-kit artifacts",
      "author": "Your Organization",
      "version": "2.1.0",
      "download_url": "https://github.com/your-org/spec-kit-jira/archive/refs/tags/v2.1.0.zip",
      "repository": "https://github.com/your-org/spec-kit-jira",
      "license": "MIT",
      "requires": {
        "speckit_version": ">=0.1.0",
        "tools": [
          {"name": "atlassian-mcp-server", "required": true}
        ]
      },
      "provides": {
        "commands": 3,
        "hooks": 1
      },
      "tags": ["jira", "atlassian", "issue-tracking"],
      "verified": true
    },
    "internal-tool": {
      "name": "Internal Tool Integration",
      "id": "internal-tool",
      "description": "Connect to internal company systems",
      "author": "Your Organization",
      "version": "1.0.0",
      "download_url": "https://internal.your-org.com/extensions/internal-tool-1.0.0.zip",
      "repository": "https://github.internal.your-org.com/spec-kit-internal",
      "license": "Proprietary",
      "requires": {
        "speckit_version": ">=0.1.0"
      },
      "provides": {
        "commands": 2
      },
      "tags": ["internal", "proprietary"],
      "verified": true
    }
  }
}

2. Host the Catalog

Options for hosting your catalog:

Method	URL Example	Use Case
GitHub Pages	`https://your-org.github.io/spec-kit-catalog/catalog.json`	Public or org-visible
Internal web server	`https://internal.company.com/spec-kit/catalog.json`	Corporate network
S3/Cloud storage	`https://s3.amazonaws.com/your-bucket/catalog.json`	Cloud-hosted teams
Local file server	`http://localhost:8000/catalog.json`	Development/testing

Security requirement: URLs must use HTTPS (except localhost for testing).

3. Configure Your Environment

Option A: Catalog stack config file (recommended)

Add to .specify/extension-catalogs.yml in your project:

yaml

catalogs:
  - name: "my-org"
    url: "https://your-org.com/spec-kit/catalog.json"
    priority: 1
    install_allowed: true

Or use the CLI:

bash

specify extension catalog add \
  --name "my-org" \
  --install-allowed \
  https://your-org.com/spec-kit/catalog.json

Option B: Environment variable (recommended for CI/CD, single-catalog)

bash

# In ~/.bashrc, ~/.zshrc, or CI pipeline
export SPECKIT_CATALOG_URL="https://your-org.com/spec-kit/catalog.json"

4. Verify Configuration

bash

# List active catalogs
specify extension catalog list

# Search should now show your catalog's extensions
specify extension search

# Install from your catalog
specify extension add jira

Catalog JSON Schema

Required fields for each extension entry:

Field	Type	Required	Description
`name`	string	Yes	Human-readable name
`id`	string	Yes	Unique identifier (lowercase, hyphens)
`version`	string	Yes	Semantic version (X.Y.Z)
`download_url`	string	Yes	URL to ZIP archive
`repository`	string	Yes	Source code URL
`description`	string	No	Brief description
`author`	string	No	Author/organization
`license`	string	No	SPDX license identifier
`requires.speckit_version`	string	No	Version constraint
`requires.tools`	array	No	Required external tools
`provides.commands`	number	No	Number of commands
`provides.hooks`	number	No	Number of hooks
`tags`	array	No	Search tags
`verified`	boolean	No	Verification status

Use Cases

Private/Internal Extensions

Host proprietary extensions that integrate with internal systems:

json

{
  "internal-auth": {
    "name": "Internal SSO Integration",
    "download_url": "https://artifactory.company.com/spec-kit/internal-auth-1.0.0.zip",
    "verified": true
  }
}

Curated Team Catalog

Limit which extensions your team can install:

json

{
  "extensions": {
    "jira": { "..." },
    "github": { "..." }
  }
}

Only jira and github will appear in specify extension search.

Air-Gapped Environments

For networks without internet access:

Download extension ZIPs to internal file server
Create catalog pointing to internal URLs
Host catalog on internal web server

json

{
  "jira": {
    "download_url": "https://files.internal/spec-kit/jira-2.1.0.zip"
  }
}

Development/Testing

Test new extensions before publishing:

bash

# Start local server
python -m http.server 8000 --directory ./my-catalog/

# Point spec-kit to local catalog
export SPECKIT_CATALOG_URL="http://localhost:8000/catalog.json"

# Test installation
specify extension add my-new-extension

Combining with Direct Installation

You can still install extensions not in your catalog using --from:

bash

# From catalog
specify extension add jira

# Direct URL (bypasses catalog)
specify extension add <extension-name> --from https://github.com/someone/spec-kit-ext/archive/v1.0.0.zip

# Local development
specify extension add --dev /path/to/extension

Note: Direct URL installation shows a security warning since the extension isn't from your configured catalog.

Troubleshooting

Extension Not Found

Error: `Extension 'jira' not found in catalog

Solutions:

Check spelling: specify extension search jira
Refresh catalog: specify extension search --help
Check internet connection
Extension may not be published yet

Configuration Not Found

Error: Jira configuration not found

Solutions:

Check if extension is installed: specify extension list

Create config from template:

bash

cp .specify/extensions/jira/jira-config.template.yml \
   .specify/extensions/jira/jira-config.yml

Reinstall extension: specify extension remove jira && specify extension add jira

Command Not Available

Issue: Extension command not appearing in coding agent

Solutions:

Check extension is enabled: specify extension list
Restart coding agent (Claude Code)
Check command file exists:
bash
```
ls .claude/commands/speckit.jira.*.md
```
Reinstall extension

Incompatible Version

Error: Extension requires spec-kit >=0.2.0, but you have 0.1.0

Solutions:

Upgrade spec-kit:
bash
```
uv tool upgrade specify-cli
```

Install older version of extension:

bash

specify extension add <extension-name> --from https://github.com/org/ext/archive/v1.0.0.zip

MCP Tool Not Available

Error: Tool 'jira-mcp-server/epic_create' not found

Solutions:

Check MCP server is installed
Check coding agent MCP configuration
Restart coding agent
Check extension requirements: specify extension info jira

Permission Denied

Error: Permission denied when accessing Jira

Solutions:

Check Jira credentials in MCP server config
Verify project permissions in Jira
Test MCP server connection independently

Best Practices

1. Version Control

Do commit:

.specify/extensions.yml (project extension config)
.specify/extensions/*/jira-config.yml (project config)

Don't commit:

.specify/extensions/.cache/ (catalog cache)
.specify/extensions/.backup/ (config backups)
.specify/extensions/*/*.local.yml (local overrides)
.specify/extensions/.registry (installation state)

Add to .gitignore:

gitignore

.specify/extensions/.cache/
.specify/extensions/.backup/
.specify/extensions/*/*.local.yml
.specify/extensions/.registry

2. Team Workflows

For teams:

Agree on which extensions to use
Commit extension configuration
Document extension usage in README
Keep extensions updated together

Example README section:

markdown

## Extensions

This project uses:
- **jira** (v1.0.0) - Jira integration
  - Config: `.specify/extensions/jira/jira-config.yml`
  - Requires: jira-mcp-server

To install: `specify extension add jira`

3. Local Development

Use local config for development:

yaml

# .specify/extensions/jira/jira-config.local.yml
project:
  key: "DEVTEST"  # Your test project

defaults:
  task:
    custom_fields:
      customfield_10002: 1  # Lower story points for testing

4. Environment-Specific Config

Use environment variables for CI/CD:

bash

# .github/workflows/deploy.yml
env:
  SPECKIT_JIRA_PROJECT_KEY: ${{ secrets.JIRA_PROJECT }}

- name: Create Jira Issues
  run: specify extension add jira && ...

5. Extension Updates

Check for updates regularly:

bash

# Weekly or before major releases
specify extension update

Pin versions for stability:

yaml

# .specify/extensions.yml
installed:
  - id: jira
    version: "1.0.0"  # Pin to specific version

6. Minimal Extensions

Only install extensions you actively use:

Reduces complexity
Faster command loading
Less configuration

7. Documentation

Document extension usage in your project:

markdown

# PROJECT.md

## Working with Jira

After creating tasks, sync to Jira:
1. Run `/speckit.tasks` to generate tasks
2. Run `/speckit.jira.specstoissues` to create Jira issues
3. Run `/speckit.jira.sync-status` to update status

FAQ

Q: Can I use multiple extensions at once?

A: Yes! Extensions are designed to work together. Install as many as you need.

Q: Do extensions slow down spec-kit?

A: No. Extensions are loaded on-demand and only when their commands are used.

Q: Can I create private extensions?

A: Yes. Install with --dev or --from and keep private. Public catalog submission is optional.

Q: How do I know if an extension is safe?

A: Look for the ✓ Verified badge. Verified extensions are reviewed by maintainers. Always review extension code before installing.

Q: Can extensions modify spec-kit core?

A: No. Extensions can only add commands and hooks. They cannot modify core functionality.

Q: What happens if two extensions have the same command name?

A: Extensions use namespaced commands (speckit.{extension}.{command}), so conflicts are very rare. The extension system will warn you if conflicts occur.

Q: Can I contribute to existing extensions?

A: Yes! Most extensions are open source. Check the repository link in specify extension info {extension}.

Q: How do I report extension bugs?

A: Go to the extension's repository (shown in specify extension info) and create an issue.

Q: Can extensions work offline?

A: Once installed, extensions work offline. However, some extensions may require internet for their functionality (e.g., Jira requires Jira API access).

Q: How do I backup my extension configuration?

A: Extension configs are in .specify/extensions/{extension}/. Back up this directory or commit configs to git.

Support

Extension Issues: Report to extension repository (see specify extension info)
Spec Kit Issues: https://github.com/statsperform/spec-kit/issues
Extension Catalog: https://github.com/statsperform/spec-kit/tree/main/extensions
Documentation: See EXTENSION-DEVELOPMENT-GUIDE.md and EXTENSION-PUBLISHING-GUIDE.md

Last Updated: 2026-01-28 Spec Kit Version: 0.1.0

Extension User Guide

Extension User Guide

Table of Contents

Introduction

What are Extensions?

Why Use Extensions?

Getting Started

Prerequisites

Check Your Version

First Extension

Finding Extensions

Browse All Extensions

Search by Keyword

Filter by Tag

Filter by Author

Show Verified Only

Get Extension Details

Installing Extensions

Install from Catalog

Install from URL

Install from Local Directory (Development)

Installation Output

Automatic Agent Skill Registration

Using Extensions

Using Extension Commands

Extension Configuration

Extension Hooks

Managing Extensions

List Installed Extensions

Update Extensions

Disable Extension Temporarily

Re-enable Extension

Remove Extension

Configuration

Configuration Files

Configuration Layers

Example: Jira Configuration

Project-Wide Extension Settings

Core Environment Variables

Example: Using a custom catalog for testing

Example: Using a private GitHub-hosted catalog

Extension Catalogs

Listing Active Catalogs

Managing Catalogs via CLI

Adding a Catalog (Project-scoped)

Removing a Catalog

Manual Config File

Organization Catalog Customization

Why Customize Your Catalog

Setting Up a Custom Catalog

1. Create Your Catalog File

2. Host the Catalog

3. Configure Your Environment

Option A: Catalog stack config file (recommended)

Option B: Environment variable (recommended for CI/CD, single-catalog)

4. Verify Configuration

Catalog JSON Schema

Use Cases

Private/Internal Extensions

Curated Team Catalog

Air-Gapped Environments

Development/Testing

Combining with Direct Installation

Troubleshooting

Extension Not Found

Configuration Not Found

Command Not Available

Incompatible Version

MCP Tool Not Available

Permission Denied

Best Practices

1. Version Control

2. Team Workflows

3. Local Development

4. Environment-Specific Config

5. Extension Updates

6. Minimal Extensions

7. Documentation

FAQ

Q: Can I use multiple extensions at once?