This document describes the Extension Catalog system, which provides centralized discovery and distribution of Spec Kit extensions. The catalog enables users to search for, browse, and install extensions without needing to know their repository URLs or local paths.
For information about installing and managing extensions after discovery, see Extension Management Commands. For the internal architecture of extensions themselves, see Extension Architecture.
The Extension Catalog is a centralized registry that maps extension identifiers to their metadata, installation sources, and verification status. It enables remote discovery of extensions while supporting local caching for performance.
Sources: CHANGELOG.md30-39
The catalog is stored as extensions/catalog.json in the Spec Kit repository and follows a JSON schema that defines extension metadata.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique extension identifier (lowercase, hyphens) |
name | string | Yes | Human-readable extension name |
version | string | Yes | Semantic version (e.g., "1.0.0") |
description | string | Yes | Brief description of functionality |
author | string | Yes | Extension author or organization |
source | string | Yes | Installation source (URL or path) |
tags | array[string] | No | Searchable tags (e.g., ["jira", "integration"]) |
verified | boolean | No | Indicates official verification status |
min_specify_version | string | No | Minimum required Spec Kit version |
Sources: CHANGELOG.md30-39 CHANGELOG.md41-49
The ExtensionCatalog class in src/specify_cli/extensions.py manages catalog operations including fetching, caching, and querying.
| Method | Parameters | Returns | Description |
|---|---|---|---|
fetch_catalog() | None | dict | Retrieves catalog from cache or downloads from GitHub |
search() | query, tag, author, verified | list[dict] | Filters extensions by criteria |
get_extension_info() | extension_id: str | dict or None | Returns metadata for specific extension |
_is_cache_valid() | None | bool | Checks if cache is less than 1 hour old |
_download_catalog() | None | dict | Downloads catalog from GitHub |
Sources: CHANGELOG.md32-36
Users discover extensions through two primary operations: search and info retrieval.
| Parameter | Type | Description | Example |
|---|---|---|---|
--query | string | Text search in name/description | --query "jira integration" |
--tag | string | Filter by tag | --tag integration |
--author | string | Filter by author | --author GitHub |
--verified | flag | Show only verified extensions | --verified |
The specify extension info <extension-id> command retrieves detailed metadata for a specific extension:
Output includes:
Sources: CHANGELOG.md23-24 CHANGELOG.md32-36
The catalog is distributed through the Spec Kit GitHub repository and fetched on-demand with intelligent caching.
The catalog is fetched from the main branch of the Spec Kit repository:
https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json
Sources: CHANGELOG.md32-36
The caching system improves performance by storing the catalog locally and revalidating only after expiry.
.specify/extensions/.cache/
├── catalog.json # Cached catalog data
└── cache_timestamp.txt # Last update timestamp (ISO 8601)
2025-01-28T14:30:00)Sources: CHANGELOG.md34 CHANGELOG.md37
Extensions can be installed from multiple sources, not just the catalog. The catalog serves as a discovery mechanism, but installation supports flexible sourcing.
| Source Type | Format | Command Example | Description |
|---|---|---|---|
| Catalog | Extension ID | specify extension add jira | Install from catalog by ID |
| URL | HTTP/HTTPS URL | specify extension add --from https://github.com/user/ext | Install from remote repository |
| Local Path | File path | specify extension add --from ./my-extension | Install from local directory |
| Development Mode | Local path + flag | specify extension add --dev --from ./ext | Symlink for active development |
The catalog's primary role is discovery, not enforcement:
--from--dev) bypasses catalog entirelySources: CHANGELOG.md21-22 CHANGELOG.md32-36
The catalog integrates with the broader extension management system:
| Operation | Catalog Usage | Fallback Behavior |
|---|---|---|
specify extension search | Required | Fails if catalog unavailable |
specify extension info | Required | Fails if catalog unavailable |
specify extension add <id> | Required | Prompts for --from if ID not found |
specify extension add --from | Optional | Bypasses catalog completely |
specify extension update | Required | Checks catalog for version comparison |
When checking for updates with specify extension update, the system:
.specify/extensions/.registrySources: CHANGELOG.md60-66
The catalog is maintained in the Spec Kit repository and updated when new extensions are published or existing extensions are updated.
For extension authors publishing to the catalog, see Creating Extensions for the publishing guide reference.
The catalog file (extensions/catalog.json) is version-controlled and follows these update patterns:
version field for existing entrydescription, tags, or other fieldsverified: true after official reviewSources: CHANGELOG.md30-39
Refresh this wiki