Extension Publishing Guide

This guide explains how to publish your extension to the Spec Kit extension catalog, making it discoverable by specify extension search.

Table of Contents

1. Prerequisites
2. Prepare Your Extension
3. Submit to Catalog
4. Release Workflow
5. Best Practices

---

Prerequisites

Before publishing an extension, ensure you have:

1. Valid Extension: A working extension with a valid extension.yml manifest
2. Git Repository: Extension hosted on GitHub (or other public git hosting)
3. Documentation: README.md with installation and usage instructions
4. License: Open source license file (MIT, Apache 2.0, etc.)
5. Versioning: Semantic versioning (e.g., 1.0.0)
6. Testing: Extension tested on real projects

---

Prepare Your Extension

1. Extension Structure

Ensure 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/

2. extension.yml Validation

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 public
• ✅ All command files exist in the extension directory
• ✅ Tags are lowercase and descriptive

3. Create GitHub Release

Create 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

4. Test Installation

Test that users can install from your release:

# Test dev installation
specify extension add --dev /path/to/your-extension

# Test from GitHub archive