integrations/README.md
The integration catalog enables discovery, versioning, and distribution of AI agent integrations for Spec Kit.
catalog.json)Contains integrations that ship with Spec Kit. These are maintained by the core team and always installable.
catalog.community.json)Community-contributed integrations. Listed for discovery only — users install from the source repositories.
The catalog stack is resolved in this order (first match wins):
SPECKIT_INTEGRATION_CATALOG_URL overrides all catalogs with a single URL.specify/integration-catalogs.yml in the project root~/.specify/integration-catalogs.yml in the user home directorycatalog.json + catalog.community.jsonExample integration-catalogs.yml:
catalogs:
- url: "https://example.com/my-catalog.json"
name: "my-catalog"
priority: 1
install_allowed: true
# List built-in integrations (default)
specify integration list
# Browse full catalog (built-in + community)
specify integration list --catalog
# Install an integration
specify integration install copilot
# Upgrade the current integration (diff-aware)
specify integration upgrade
# Upgrade with force (overwrite modified files)
specify integration upgrade --force
integration.yml)Each integration can include an integration.yml descriptor that documents its metadata, requirements, and provided commands/scripts:
schema_version: "1.0"
integration:
id: "my-agent"
name: "My Agent"
version: "1.0.0"
description: "Integration for My Agent"
author: "my-org"
repository: "https://github.com/my-org/speckit-my-agent"
license: "MIT"
requires:
speckit_version: ">=0.6.0"
tools:
- name: "my-agent"
version: ">=1.0.0"
required: true
provides:
commands:
- name: "speckit.specify"
file: "templates/speckit.specify.md"
- name: "speckit.plan"
file: "templates/speckit.plan.md"
scripts:
- update-context.sh
- update-context.ps1
Both catalog files follow the same JSON schema:
{
"schema_version": "1.0",
"updated_at": "2026-04-08T00:00:00Z",
"catalog_url": "https://...",
"integrations": {
"my-agent": {
"id": "my-agent",
"name": "My Agent",
"version": "1.0.0",
"description": "Integration for My Agent",
"author": "my-org",
"repository": "https://github.com/my-org/speckit-my-agent",
"tags": ["cli"]
}
}
}
| Field | Type | Description |
|---|---|---|
schema_version | string | Must be "1.0" |
updated_at | string | ISO 8601 timestamp |
integrations | object | Map of integration ID → metadata |
| Field | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Unique ID (lowercase alphanumeric + hyphens) |
name | string | Yes | Human-readable display name |
version | string | Yes | PEP 440 version (e.g., 1.0.0, 1.0.0a1) |
description | string | Yes | One-line description |
author | string | No | Author name or organization |
repository | string | No | Source repository URL |
tags | array | No | Searchable tags (e.g., ["cli", "ide"]) |
See CONTRIBUTING.md for how to add integrations to the community catalog.