extensions/EXTENSION-PUBLISHING-GUIDE.md
This guide explains how to publish your extension to the Spec Kit extension catalog, making it discoverable by specify extension search.
Before publishing an extension, ensure you have:
extension.yml manifestEnsure your extension follows the standard structure:
your-extension/
├── extension.yml # Required: Extension manifest
├── README.md # Required: Documentation
├── LICENSE # Required: License file
├── CHANGELOG.md # Recommended: Version history
├── .gitignore # Recommended: Git ignore rules
│
├── commands/ # Extension commands
│ ├── command1.md
│ └── command2.md
│
├── config-template.yml # Config template (if needed)
│
└── docs/ # Additional documentation
├── usage.md
└── examples/
Verify your manifest is valid:
schema_version: "1.0"
extension:
id: "your-extension" # Unique lowercase-hyphenated ID
name: "Your Extension Name" # Human-readable name
version: "1.0.0" # Semantic version
description: "Brief description (one sentence)"
author: "Your Name or Organization"
repository: "https://github.com/your-org/spec-kit-your-extension"
license: "MIT"
homepage: "https://github.com/your-org/spec-kit-your-extension"
requires:
speckit_version: ">=0.1.0" # Required spec-kit version
provides:
commands: # List all commands
- name: "speckit.your-extension.command"
file: "commands/command.md"
description: "Command description"
tags: # 2-5 relevant tags
- "category"
- "tool-name"
Validation Checklist:
id is lowercase with hyphens only (no underscores, spaces, or special characters)version follows semantic versioning (X.Y.Z)description is concise (under 100 characters)repository URL is valid and publicCreate a GitHub release for your extension version:
# Tag the release
git tag v1.0.0
git push origin v1.0.0
# Create release on GitHub
# Go to: https://github.com/your-org/spec-kit-your-extension/releases/new
# - Tag: v1.0.0
# - Title: v1.0.0 - Release Name
# - Description: Changelog/release notes
The release archive URL will be:
https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
Test that users can install from your release:
# Test dev installation
specify extension add --dev /path/to/your-extension
# Test from GitHub archive
specify extension add <extension-name> --from https://github.com/your-org/spec-kit-your-extension/archive/refs/tags/v1.0.0.zip
Spec Kit uses a dual-catalog system. For details about how catalogs work, see the main Extensions README.
For extension publishing: All community extensions are listed in extensions/catalog.community.json. Users browse this catalog and copy extensions they trust into their own catalog.json.
To submit your extension to the community catalog, file a new issue using the Extension Submission template. The template collects all required metadata, including:
[!IMPORTANT] Do not open a pull request directly to edit
extensions/catalog.community.json. All community extension submissions must go through the issue template so a maintainer can review the entry and update the catalog.
extensions/catalog.community.json and the Community Extensions table in the READMEspecify extension searchextension.yml manifest[!NOTE] Maintainers do not review, audit, or test the extension code itself.
To update an extension that is already in the catalog (e.g., for a new version), file a new Extension Submission issue with the updated version, download URL, and any other changed fields. Mention in the issue that this is an update to an existing entry.
When releasing a new version:
Update version in extension.yml:
extension:
version: "1.1.0" # Updated version
Update CHANGELOG.md:
## [1.1.0] - 2026-02-15
### Added
- New feature X
### Fixed
- Bug fix Y
Create GitHub release:
git tag v1.1.0
git push origin v1.1.0
# Create release on GitHub
File an update submission using the Extension Submission template with the new version and download URL. Mention in the issue that this is an update to an existing entry.
README.md Structure:
Command Documentation:
Configuration:
A: The main catalog is for public extensions only. For private extensions:
specify extension add-catalog https://your-domain.com/catalog.jsonA: Typically 3-7 business days. Updates to existing extensions are usually faster.
A: You'll receive feedback on what needs to be fixed. Make the changes and resubmit.
A: Yes, file a new Extension Submission issue with the updated version and download URL. Mention that it is an update to an existing entry.
A: No. All community extensions are listed in the catalog once their submission is reviewed and accepted.
A: Extensions should be free and open-source. Commercial support/services are allowed, but core functionality must be free.
{
"name": "string (required)",
"id": "string (required, unique)",
"description": "string (required, <200 chars)",
"author": "string (required)",
"version": "string (required, semver)",
"download_url": "string (required, valid URL)",
"repository": "string (required, valid URL)",
"homepage": "string (optional, valid URL)",
"documentation": "string (optional, valid URL)",
"changelog": "string (optional, valid URL)",
"license": "string (required)",
"requires": {
"speckit_version": "string (required, version specifier)",
"tools": [
{
"name": "string (required)",
"version": "string (optional, version specifier)",
"required": "boolean (default: false)"
}
]
},
"provides": {
"commands": "integer (optional)",
"hooks": "integer (optional)"
},
"tags": ["array of strings (2-10 tags)"],
"verified": "boolean (default: false, set by maintainers)",
"downloads": "integer (auto-updated)",
"stars": "integer (auto-updated)",
"created_at": "string (ISO 8601 datetime)",
"updated_at": "string (ISO 8601 datetime)"
}
Recommended tag categories:
Use 2-5 tags that best describe your extension.
Last Updated: 2026-01-28 Catalog Format Version: 1.0