Skip to content

Commit 076bb40

Browse files
mnriemmnriem
authored
docs: add extensions reference page and integrations FAQ (#2242)
- New docs/extensions.md: command reference for all 9 specify extension commands and 3 specify extension catalog commands, plus catalog resolution order, extension configuration, and FAQ - docs/integrations.md: add FAQ section covering single-integration limit, file preservation, key discovery, CLI vs IDE requirements, upgrade vs switch - docs/toc.yml: add Extensions under Reference section - README.md: update integration and extension links to published docs site
1 parent 530d1ce commit 076bb40

File tree

4 files changed

+227
-2
lines changed

4 files changed

+227
-2
lines changed

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -316,7 +316,7 @@ Community projects that extend, visualize, or build on Spec Kit:
316316

317317
## 🤖 Supported AI Coding Agent Integrations
318318

319-
Spec Kit works with 30+ AI coding agents — both CLI tools and IDE-based assistants. See the full list with notes and usage details in the [Supported AI Coding Agent Integrations](docs/integrations.md) guide.
319+
Spec Kit works with 30+ AI coding agents — both CLI tools and IDE-based assistants. See the full list with notes and usage details in the [Supported AI Coding Agent Integrations](https://github.github.io/spec-kit/integrations.html) guide.
320320

321321
Run `specify integration list` to see all available integrations in your installed version.
322322

@@ -510,7 +510,7 @@ specify extension add <extension-name>
510510

511511
For example, extensions could add Jira integration, post-implementation code review, V-Model test traceability, or project health diagnostics.
512512

513-
See the [Extensions README](./extensions/README.md) for the full guide and how to build and publish your own. Browse the [community extensions](#-community-extensions) above for what's available.
513+
See the [Extensions reference](https://github.github.io/spec-kit/extensions.html) for the full command guide. Browse the [community extensions](#-community-extensions) above for what's available.
514514

515515
### Presets — Customize Existing Workflows
516516

‎docs/extensions.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
# Extensions
2+
3+
Extensions add new capabilities to Spec Kit — domain-specific commands, external tool integrations, quality gates, and more. They introduce new commands and templates that go beyond the built-in Spec-Driven Development workflow.
4+
5+
## Search Available Extensions
6+
7+
```bash
8+
specify extension search [query]
9+
```
10+
11+
| Option | Description |
12+
| ------------ | ------------------------------------ |
13+
| `--tag` | Filter by tag |
14+
| `--author` | Filter by author |
15+
| `--verified` | Show only verified extensions |
16+
17+
Searches all active catalogs for extensions matching the query. Without a query, lists all available extensions.
18+
19+
## Install an Extension
20+
21+
```bash
22+
specify extension add <name>
23+
```
24+
25+
| Option | Description |
26+
| --------------- | -------------------------------------------------------- |
27+
| `--dev` | Install from a local directory (for development) |
28+
| `--from <url>` | Install from a custom URL instead of the catalog |
29+
| `--priority <N>`| Resolution priority (default: 10; lower = higher precedence) |
30+
31+
Installs an extension from the catalog, a URL, or a local directory. Extension commands are automatically registered with the currently installed AI coding agent integration.
32+
33+
> **Note:** All extension commands require a project already initialized with `specify init`.
34+
35+
## Remove an Extension
36+
37+
```bash
38+
specify extension remove <name>
39+
```
40+
41+
| Option | Description |
42+
| --------------- | ---------------------------------------------- |
43+
| `--keep-config` | Preserve configuration files during removal |
44+
| `--force` | Skip confirmation prompt |
45+
46+
Removes an installed extension. Configuration files are backed up by default; use `--keep-config` to leave them in place or `--force` to skip the confirmation.
47+
48+
## List Installed Extensions
49+
50+
```bash
51+
specify extension list
52+
```
53+
54+
| Option | Description |
55+
| ------------- | -------------------------------------------------- |
56+
| `--available` | Show available (uninstalled) extensions |
57+
| `--all` | Show both installed and available extensions |
58+
59+
Lists installed extensions with their status, version, and command counts.
60+
61+
## Extension Info
62+
63+
```bash
64+
specify extension info <name>
65+
```
66+
67+
Shows detailed information about an installed or available extension, including its description, version, commands, and configuration.
68+
69+
## Update Extensions
70+
71+
```bash
72+
specify extension update [<name>]
73+
```
74+
75+
Updates a specific extension, or all installed extensions if no name is given.
76+
77+
## Enable / Disable an Extension
78+
79+
```bash
80+
specify extension enable <name>
81+
specify extension disable <name>
82+
```
83+
84+
Disable an extension without removing it. Disabled extensions are not loaded and their commands are not available. Re-enable with `enable`.
85+
86+
## Set Extension Priority
87+
88+
```bash
89+
specify extension set-priority <name> <priority>
90+
```
91+
92+
Changes the resolution priority of an extension. When multiple extensions provide a command with the same name, the extension with the lowest priority number takes precedence.
93+
94+
## Catalog Management
95+
96+
Extension catalogs control where `search` and `add` look for extensions. Catalogs are checked in priority order (lower number = higher precedence).
97+
98+
### List Catalogs
99+
100+
```bash
101+
specify extension catalog list
102+
```
103+
104+
Shows all active catalogs in the stack with their priorities and install permissions.
105+
106+
### Add a Catalog
107+
108+
```bash
109+
specify extension catalog add <url>
110+
```
111+
112+
| Option | Description |
113+
| ------------------------------------ | -------------------------------------------------- |
114+
| `--name <name>` | Required. Unique name for the catalog |
115+
| `--priority <N>` | Priority (default: 10; lower = higher precedence) |
116+
| `--install-allowed / --no-install-allowed` | Whether extensions can be installed from this catalog |
117+
| `--description <text>` | Optional description |
118+
119+
Adds a catalog to the project's `.specify/extension-catalogs.yml`.
120+
121+
### Remove a Catalog
122+
123+
```bash
124+
specify extension catalog remove <name>
125+
```
126+
127+
Removes a catalog from the project configuration.
128+
129+
### Catalog Resolution Order
130+
131+
Catalogs are resolved in this order (first match wins):
132+
133+
1. **Environment variable** — `SPECKIT_CATALOG_URL` overrides all catalogs
134+
2. **Project config** — `.specify/extension-catalogs.yml`
135+
3. **User config** — `~/.specify/extension-catalogs.yml`
136+
4. **Built-in defaults** — official catalog + community catalog
137+
138+
Example `.specify/extension-catalogs.yml`:
139+
140+
```yaml
141+
catalogs:
142+
- name: "my-org-catalog"
143+
url: "https://example.com/catalog.json"
144+
priority: 5
145+
install_allowed: true
146+
description: "Our approved extensions"
147+
```
148+
149+
## Extension Configuration
150+
151+
Most extensions include configuration files in their install directory:
152+
153+
```text
154+
.specify/extensions/<ext>/
155+
├── <ext>-config.yml # Project config (version controlled)
156+
├── <ext>-config.local.yml # Local overrides (gitignored)
157+
└── <ext>-config.template.yml # Template reference
158+
```
159+
160+
Configuration is merged in this order (highest priority last):
161+
162+
1. **Extension defaults** (from `extension.yml`)
163+
2. **Project config** (`<ext>-config.yml`)
164+
3. **Local overrides** (`<ext>-config.local.yml`)
165+
4. **Environment variables** (`SPECKIT_<EXT>_*`)
166+
167+
To set up configuration for a newly installed extension, copy the template:
168+
169+
```bash
170+
cp .specify/extensions/<ext>/<ext>-config.template.yml \
171+
.specify/extensions/<ext>/<ext>-config.yml
172+
```
173+
174+
## FAQ
175+
176+
### Why can't I find an extension with `search`?
177+
178+
Check the spelling of the extension name. The extension may not be published yet, or it may be in a catalog you haven't added. Use `specify extension catalog list` to see which catalogs are active.
179+
180+
### Why doesn't the extension command appear in my AI coding agent?
181+
182+
Verify the extension is installed and enabled with `specify extension list`. If it shows as installed, restart your AI coding agent — it may need to reload for it to take effect.
183+
184+
### How do I set up extension configuration?
185+
186+
Copy the config template that ships with the extension:
187+
188+
```bash
189+
cp .specify/extensions/<ext>/<ext>-config.template.yml \
190+
.specify/extensions/<ext>/<ext>-config.yml
191+
```
192+
193+
See [Extension Configuration](#extension-configuration) for details on config layers and overrides.
194+
195+
### How do I resolve an incompatible version error?
196+
197+
Update Spec Kit to the version required by the extension.
198+
199+
### Who maintains extensions?
200+
201+
Most extensions are independently created and maintained by their respective authors. The Spec Kit maintainers do not review, audit, endorse, or support extension code. Review an extension's source code before installing and use at your own discretion. For issues with a specific extension, contact its author or file an issue on the extension's repository.

‎docs/integrations.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,3 +116,25 @@ Example:
116116
```bash
117117
specify integration install generic --integration-options="--commands-dir .myagent/cmds"
118118
```
119+
120+
## FAQ
121+
122+
### Can I use multiple integrations at the same time?
123+
124+
No. Only one AI coding agent integration can be installed per project. Use `specify integration switch <key>` to change to a different AI coding agent.
125+
126+
### What happens to my changes when I uninstall or switch?
127+
128+
Files you've modified are preserved automatically. Only unmodified files (matching their original SHA-256 hash) are removed. Use `--force` to override this.
129+
130+
### How do I know which key to use?
131+
132+
Run `specify integration list` to see all available integrations with their keys, or check the [Supported AI Coding Agents](#supported-ai-coding-agents) table above.
133+
134+
### Do I need the AI coding agent installed to use an integration?
135+
136+
CLI-based integrations (like Claude Code, Gemini CLI) require the tool to be installed. IDE-based integrations (like Windsurf, Cursor) work through the IDE itself. Some agents like GitHub Copilot support both IDE and CLI usage. `specify integration list` shows which type each integration is.
137+
138+
### When should I use `upgrade` vs `switch`?
139+
140+
Use `upgrade` when you've upgraded Spec Kit and want to refresh the same integration's templates. Use `switch` when you want to change to a different AI coding agent.

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@
1717
items:
1818
- name: Integrations
1919
href: integrations.md
20+
- name: Extensions
21+
href: extensions.md
2022

2123
# Development workflows
2224
- name: Development

0 commit comments

Comments
 (0)