This page provides a technical guide for creating Spec Kit extensions. It covers the extension.yml manifest structure, command file format, hook definitions, and the configuration system. For information about installing and using extensions, see 7.1 Using Extensions For catalog submission and distribution, see 7.2 Extension Catalogs For architectural details about the extension system implementation, see 7.4 Extension Architecture
Every extension requires an extension.yml manifest file in its root directory. The ExtensionManifest class src/specify_cli/extensions.py142 validates this file against a strict schema.
Title: Extension Manifest Components
Sources: src/specify_cli/extensions.py142-208 extensions/EXTENSION-DEVELOPMENT-GUIDE.md16-61
The ExtensionManifest class enforces these required top-level fields src/specify_cli/extensions.py185-188:
| Field | Type | Validation | Example |
|---|---|---|---|
schema_version | string | Must be "1.0" src/specify_cli/extensions.py191-195 | "1.0" |
extension.id | string | Lowercase alphanumeric + hyphens: ^[a-z0-9-]+$ src/specify_cli/extensions.py204-209 | "jira" |
extension.name | string | Human-readable name src/specify_cli/extensions.py199 | "Jira Integration" |
extension.version | string | Semantic version (X.Y.Z) src/specify_cli/extensions.py211-214 | "1.0.0" |
extension.description | string | Brief description src/specify_cli/extensions.py199 | "Create Jira issues from specs" |
requires.speckit_version | string | Version specifier (e.g., >=0.1.0) src/specify_cli/extensions.py146 | ">=0.1.0" |
provides.commands | array | At least one command or hook required src/specify_cli/extensions.py146 | See Commands section |
Sources: src/specify_cli/extensions.py142-214 extensions/EXTENSION-DEVELOPMENT-GUIDE.md136-190
All command names must follow the pattern speckit.{extension-id}.{command-name} src/specify_cli/extensions.py49:
The system validates this pattern with regex: ^speckit\.([a-z0-9-]+)\.([a-z0-9-]+)$ src/specify_cli/extensions.py49
Sources: src/specify_cli/extensions.py49 extensions/template/extension.yml51-60
Extension commands are markdown files with YAML frontmatter that get registered in AI agent directories by the CommandRegistrar src/specify_cli/agents.py43-49
Title: Extension Command Registration Logic
Sources: src/specify_cli/agents.py100-130 src/specify_cli/agents.py172-195 extensions/EXTENSION-USER-GUIDE.md190-203
The frontmatter section uses YAML src/specify_cli/agents.py100-128:
The description field is required for the agent to understand the command purpose. Scripts can reference core spec-kit scripts via relative paths that are rewritten by rewrite_project_relative_paths to point to .specify/scripts/ src/specify_cli/agents.py172-195
Sources: src/specify_cli/agents.py100-195 extensions/EXTENSION-DEVELOPMENT-GUIDE.md231-287
Use $ARGUMENTS in markdown-based commands. This placeholder is handled by the AI agent at runtime to pass user input to the scripts extensions/EXTENSION-DEVELOPMENT-GUIDE.md246-265
Sources: extensions/EXTENSION-DEVELOPMENT-GUIDE.md246-265 extensions/template/extension.yml89-98
Hooks allow extensions to execute commands at specific lifecycle events in the core workflow. The HookExecutor class manages these triggers tests/test_extensions.py32
Extensions can register hooks for these events extensions/EXTENSION-DEVELOPMENT-GUIDE.md197-207:
| Event | Triggered After | Use Case |
|---|---|---|
after_tasks | /speckit.tasks completes | Create project management tickets extensions/template/extension.yml77-81 |
after_implement | /speckit.implement completes | Run quality checks |
after_specify | /speckit.specify completes | Validate specification format |
after_plan | /speckit.plan completes | Sync design to external tools |
after_analyze | /speckit.analyze completes | Update external analysis dashboards |
after_checklist | /speckit.checklist completes | Post-process generated checklists |
after_clarify | /speckit.clarify completes | Sync clarifications to external systems |
after_constitution | /speckit.constitution completes | Update external governance docs |
after_taskstoissues | /speckit.taskstoissues completes | Link external issues back to Spec Kit |
Sources: extensions/EXTENSION-DEVELOPMENT-GUIDE.md197-207 extensions/template/extension.yml75-81
Title: Hook Registration Architecture
Sources: src/specify_cli/extensions.py128-134 extensions/EXTENSION-DEVELOPMENT-GUIDE.md52-57
A hook event can be a single mapping or a list of mappings src/specify_cli/extensions.py128-134
| Field | Required | Description |
|---|---|---|
command | Yes | Command to execute (typically from provides.commands) extensions/EXTENSION-DEVELOPMENT-GUIDE.md211-212 |
priority | No | Execution order (lower runs first, default 10) src/specify_cli/extensions.py53 |
optional | No | If true, prompt user before executing extensions/EXTENSION-DEVELOPMENT-GUIDE.md213 |
prompt | No | Prompt text for optional hooks extensions/EXTENSION-DEVELOPMENT-GUIDE.md214 |
Sources: src/specify_cli/extensions.py53 src/specify_cli/extensions.py128-134 extensions/EXTENSION-DEVELOPMENT-GUIDE.md209-217
Extensions use a layered configuration hierarchy to merge settings. The ConfigManager handles the merging of these layers extensions/EXTENSION-DEVELOPMENT-GUIDE.md307-314
Title: Extension Configuration Priority
Sources: extensions/EXTENSION-DEVELOPMENT-GUIDE.md307-314 extensions/template/extension.yml105-113
Define defaults in extension.yml to provide baseline settings extensions/EXTENSION-DEVELOPMENT-GUIDE.md221-223:
Sources: extensions/template/extension.yml105-113 extensions/EXTENSION-DEVELOPMENT-GUIDE.md221-223
Extensions should follow a standard directory structure to ensure compatibility with ExtensionManager extensions/EXTENSION-PUBLISHING-GUIDE.md31-52
Sources: extensions/EXTENSION-PUBLISHING-GUIDE.md31-52 extensions/EXTENSION-DEVELOPMENT-GUIDE.md63-81
The ExtensionManifest class validates manifests on installation src/specify_cli/extensions.py183-214:
schema_version, extension, requires, and provides src/specify_cli/extensions.py185-188extension.id against lowercase alphanumeric with hyphens src/specify_cli/extensions.py204-209extension.version is a valid semantic version src/specify_cli/extensions.py211-214SCHEMA_VERSION = "1.0" src/specify_cli/extensions.py191-195Sources: src/specify_cli/extensions.py142-214 extensions/EXTENSION-PUBLISHING-GUIDE.md84-92
Spec Kit validates version requirements during installation src/specify_cli/extensions.py146:
This ensures the extension is compatible with the installed version of the CLI extensions/EXTENSION-DEVELOPMENT-GUIDE.md30-31
Sources: src/specify_cli/extensions.py142-146 extensions/EXTENSION-DEVELOPMENT-GUIDE.md162-173
Install from a local directory during development to test changes immediately using the --dev flag extensions/EXTENSION-DEVELOPMENT-GUIDE.md105-110 This bypasses the catalog download process.
Check the status of your installed extension using the CLI extensions/EXTENSION-DEVELOPMENT-GUIDE.md112-121:
Verify that the commands are correctly registered and visible to the agent. If using Claude, commands will be available in .claude/commands/speckit.ext.hello.md extensions/EXTENSION-DEVELOPMENT-GUIDE.md123-132
Sources: extensions/EXTENSION-DEVELOPMENT-GUIDE.md105-134 extensions/EXTENSION-USER-GUIDE.md166-171
Refresh this wiki