specify extension

Relevant source files

• extensions/EXTENSION-API-REFERENCE.md
• extensions/EXTENSION-DEVELOPMENT-GUIDE.md
• extensions/EXTENSION-PUBLISHING-GUIDE.md
• extensions/EXTENSION-USER-GUIDE.md
• extensions/README.md
• extensions/RFC-EXTENSION-SYSTEM.md
• extensions/template/extension.yml
• presets/README.md
• presets/scaffold/preset.yml
• src/specify_cli/_utils.py
• src/specify_cli/extensions/__init__.py
• src/specify_cli/extensions/_commands.py
• src/specify_cli/presets/__init__.py
• tests/integrations/test_integration_hermes.py
• tests/test_check_tool.py
• tests/test_extension_registration.py
• tests/test_extension_update_hardening.py

This page documents the specify extension CLI commands for discovering, installing, and managing extensions that add commands and functionality to spec-kit projects. Extensions are modular packages that extend the core framework without bloating the codebase src/specify_cli/extensions/__init__.py4-7

Command Overview

The specify extension command provides subcommands for the complete extension lifecycle:

Command	Purpose
extension list	List installed extensions with metadata
extension add <id>	Install an extension from catalog or URL
extension remove <id>	Uninstall an extension
extension search [query]	Search available extensions across catalogs
extension info <id>	Show detailed information about an extension
extension update <id>	Update an installed extension to latest version
extension enable <id>	Enable hooks for an extension
extension disable <id>	Disable hooks for an extension
extension catalog list	List active extension catalogs

Sources: src/specify_cli/extensions/__init__.py1-7 extensions/README.md110-125 src/specify_cli/extensions/_commands.py27-38

Core Architecture

System Component Diagram

This diagram maps Natural Language concepts to the Python classes and directory structures used in the codebase.

Key Components:

• ExtensionManager: Orchestrates installation/removal lifecycle, including zip extraction and compatibility checks src/specify_cli/extensions/__init__.py439-445
• ExtensionRegistry: Persists installed extension metadata to a .registry JSON file to track state across CLI sessions src/specify_cli/extensions/__init__.py231-236
• ExtensionCatalog: Fetches and caches catalog data from multiple sources, supporting the "Your Catalog" (catalog.json) and "Community Catalog" (catalog.community.json) split extensions/README.md5-15
• ExtensionManifest: Validates extension.yml against schema version 1.0, ensuring required fields like id, version, and provides are present src/specify_cli/extensions/__init__.py158-162
• CommandRegistrar: Handles writing command files to agent-specific directories in Markdown or TOML format src/specify_cli/agents.py22-52
• HookExecutor: Manages lifecycle hook registration (e.g., after_tasks) and execution priority src/specify_cli/extensions/__init__.py1509-1515

Sources: src/specify_cli/extensions/__init__.py158-162 src/specify_cli/extensions/__init__.py231-236 src/specify_cli/extensions/__init__.py439-445 src/specify_cli/agents.py22-52 extensions/README.md5-15

extension list

Lists all installed extensions with their metadata:

Implementation: The command queries the ExtensionRegistry to retrieve the list of installed IDs and then loads the local ExtensionManifest for each to display current status, command counts, and hook counts src/specify_cli/extensions/__init__.py626-635

Sources: src/specify_cli/extensions/__init__.py626-635 extensions/EXTENSION-USER-GUIDE.md267-282

extension search

Searches available extensions across all active catalogs:

Catalog Curation: Spec Kit uses a dual-catalog system. catalog.json is the default upstream catalog, while catalog.community.json serves as a reference for discovery extensions/README.md9-13 Organizations can override the default by setting SPECKIT_CATALOG_URL extensions/README.md15-22

Sources: src/specify_cli/extensions/__init__.py1166-1175 extensions/README.md9-22 extensions/EXTENSION-USER-GUIDE.md78-87

extension info

Shows detailed information about a specific extension:

Implementation: Retrieves metadata from either the local registry (if installed) or the catalog stack via _resolve_catalog_extension src/specify_cli/extensions/_commands.py143-160 It displays the author, repository, required speckit_version, and the list of commands/hooks provided src/specify_cli/extensions/__init__.py1221-1230

Sources: src/specify_cli/extensions/__init__.py1221-1230 src/specify_cli/extensions/_commands.py143-160 extensions/EXTENSION-USER-GUIDE.md123-138

extension add

Installs an extension from a catalog, URL, or local directory:

Installation Flow

Automatic Agent Skill Registration

If the project has AI skills enabled, extension commands are automatically registered as agent skills extensions/EXTENSION-USER-GUIDE.md190-193 The ExtensionManager checks for skill support via is_ai_skills_enabled, is_dollar_skills_agent, and is_slash_skills_agent before writing skill files into the agent's skills directory src/specify_cli/extensions/__init__.py476-485

Sources: src/specify_cli/extensions/__init__.py476-485 extensions/EXTENSION-USER-GUIDE.md190-204 src/specify_cli/extensions/__init__.py30-32

extension remove

Uninstalls an extension and cleans up agent directories:

Removal Process:

1. Unregister Commands: Removes command files from agent-specific directories (e.g., .claude/skills/) src/specify_cli/extensions/__init__.py581-584
2. Backup/Cleanup: Removes the extension directory. If --keep-config is not provided, it attempts to backup configuration files to .specify/extensions/.backup/ src/specify_cli/extensions/__init__.py586-600
3. Unregister Hooks: Cleans up hook entries from the project's extensions.yml src/specify_cli/extensions/__init__.py611-615
4. Registry Update: Removes the entry from .registry src/specify_cli/extensions/__init__.py618-620

Sources: src/specify_cli/extensions/__init__.py559-620 extensions/EXTENSION-DEVELOPMENT-GUIDE.md113-122

extension update

Updates an installed extension to the latest version found in the catalog:

Implementation: The update process is a composite operation that performs a removal followed by a new installation. The system utilizes a rollback mechanism where it attempts to restore the previous version from backup if the update fails src/specify_cli/extensions/__init__.py272-280

Sources: src/specify_cli/extensions/__init__.py272-280 extensions/EXTENSION-USER-GUIDE.md283-304

Catalog Stack System

Extension catalogs are resolved through a stack with precedence rules. Spec Kit provides CatalogEntry to manage these entries src/specify_cli/extensions/__init__.py154-156

Layer	Source	Precedence
1	SPECKIT_CATALOG_URL	Highest (Overrides all)
2	.specify/extension-catalogs.yml	Project-level
3	~/.specify/extension-catalogs.yml	User-level
4	Built-in Defaults	Lowest (Official + Community)

Catalog Entry Schema

Each entry in the catalog stack is represented by the CatalogEntry dataclass src/specify_cli/extensions/__init__.py154-156:

Sources: src/specify_cli/extensions/__init__.py154-156 extensions/README.md15-23

Command Registration System

The CommandRegistrar is responsible for translating extension commands (stored as Markdown with YAML frontmatter) into agent-specific formats.

Agent-Code Association Diagram

This diagram shows how the CLI maps extension commands to specific file formats and directories based on the detected agent integration.

Key Registration Logic:

• Path Rewriting: Extension commands use relative paths that get rewritten during registration to project-relative paths (e.g., .specify/scripts/) extensions/EXTENSION-DEVELOPMENT-GUIDE.md271-286
• Frontmatter Parsing: The registrar extracts YAML frontmatter to determine command metadata and script requirements src/specify_cli/_utils.py58-65
• Placeholders: The registrar handles substitution of $ARGUMENTS (Markdown) or {SCRIPT} based on the target agent's requirements extensions/EXTENSION-DEVELOPMENT-GUIDE.md251-255

Sources: src/specify_cli/agents.py46-52 extensions/EXTENSION-DEVELOPMENT-GUIDE.md251-286 src/specify_cli/_utils.py58-65

Configuration System

Extensions use a 4-layer configuration system managed by ConfigManager src/specify_cli/extensions/__init__.py1310-1320

1. Defaults: Defined in the extension.yml manifest extensions/EXTENSION-DEVELOPMENT-GUIDE.md224-227
2. Project Config: .specify/extensions/<id>/<id>-config.yml.
3. Local Config: .specify/extensions/<id>/local-config.yml (gitignored for sensitive data).
4. Environment Variables: SPECKIT_<EXT_ID>_<KEY> (highest precedence).

Priority Normalization: Priority values used for sorting hooks are normalized to positive integers (default: 10) to handle corrupted registry data src/specify_cli/extensions/__init__.py122-141

Sources: src/specify_cli/extensions/__init__.py122-141 src/specify_cli/extensions/__init__.py1310-1320 extensions/EXTENSION-DEVELOPMENT-GUIDE.md224-227