Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs: publish extension development guide on docs site (#5166)

Manfred Riem521498d5be6c
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 04d1923b5..2c1e35362 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -7,7 +7,7 @@ contact_links:
url: https://github.com/github/spec-kit/blob/main/README.md
about: Read the Spec Kit documentation and guides
- name: πŸ› οΈ Extension Development Guide
- url: https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
+ url: https://github.github.io/spec-kit/extensions/developing.html
about: Learn how to develop and publish Spec Kit extensions
- name: 🀝 Contributing Guide
url: https://github.com/github/spec-kit/blob/main/CONTRIBUTING.md
diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/docs/extensions/developing.md
similarity index 86%
rename from extensions/EXTENSION-DEVELOPMENT-GUIDE.md
rename to docs/extensions/developing.md
index 155a50b4b..e1babe777 100644
--- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
+++ b/docs/extensions/developing.md
@@ -1,6 +1,10 @@
-# Extension Development Guide
+# Developing extensions
-A guide for creating Spec Kit extensions.
+A guide for creating Spec Kit extensions using GitHub Copilot's skills layout.
+Invoke skills in Copilot chat with hyphenated names such as
+`/speckit-my-ext-hello`. Extension manifests still use dotted command identifiers
+such as `speckit.my-ext.hello`; Spec Kit renders them as Copilot skills during
+installation.
---
@@ -69,7 +73,7 @@ mkdir commands
**File**: `commands/hello.md`
-```markdown
+````markdown
---
description: "Say hello command"
tools: # Optional: AI tools this command uses
@@ -100,14 +104,22 @@ echo "Arguments: $ARGUMENTS"
## Extension Configuration
Load extension config from `.specify/extensions/my-ext/my-ext-config.yml`.
+````
### 5. Test Locally
```bash
cd /path/to/spec-kit-project
+specify integration install copilot --integration-options="--skills"
specify extension add --dev /path/to/my-extension
```
+For a new project, initialize it with
+`specify init my-project --integration copilot --integration-options="--skills"`.
+If Copilot is already installed in a commands layout, follow the
+[Copilot migration guidance](../integrations/copilot.md#commands-layout)
+instead of installing it again.
+
### 6. Verify Installation
```bash
@@ -119,16 +131,17 @@ specify extension list
# Commands: 1 | Hooks: 1 | Status: Enabled
```
-### 7. Test Command
+### 7. Test Skill
-If using Claude:
+Open GitHub Copilot chat and invoke the skill:
-```bash
-claude
-> /speckit.my-ext.hello world
+```text
+/speckit-my-ext-hello world
```
-The command will be available in `.claude/commands/speckit.my-ext.hello.md`.
+The generated skill is available in
+`.github/skills/speckit-my-ext-hello/SKILL.md`. This invocation belongs in
+Copilot chat, not in your terminal.
---
@@ -293,9 +306,13 @@ echo "Running with args: $args"
### Referencing other commands
-A command body is a *template* that Spec Kit renders once per agent. Different agents invoke commands with different surface syntax β€” for example `/speckit.plan` (dot separator) or `/speckit-plan` (hyphen separator). Some agents also use different prefixes in skills mode (e.g. Kimi `/skill:speckit-plan`, Codex/ZCode `$speckit-plan`). So when you reference a sibling command from a body, **do not hard-code a literal invocation** like `/speckit.my-ext.prepare`. A literal is correct for exactly one agent and breaks on the rest.
+A command body is a *template* that Spec Kit renders as a Copilot skill.
+When referencing another command from that body, **do not hard-code its
+invocation**. Use a command-reference token so Spec Kit renders the correct
+skill syntax and the extension remains portable.
-Instead use the agent-neutral token `__SPECKIT_COMMAND_<NAME>__`. Spec Kit resolves it to a `/speckit<separator>...` invocation using the active integration's `invoke_separator` (and integrations may post-process that further in skills output).
+Use the token `__SPECKIT_COMMAND_<NAME>__`. In Copilot's skills layout,
+Spec Kit resolves it to a `/speckit-...` invocation.
Encode the command name in upper case, dropping the `speckit.` prefix and turning each dotted segment separator into an underscore. A hyphen inside a segment is kept as a hyphen:
@@ -306,7 +323,10 @@ Encode the command name in upper case, dropping the `speckit.` prefix and turnin
| `speckit.git.commit.md` | `__SPECKIT_COMMAND_GIT_COMMIT__` |
| `speckit.agent-context.update.md` | `__SPECKIT_COMMAND_AGENT-CONTEXT_UPDATE__` |
-The resolver maps each underscore back to the active agent's separator. An underscore separates segments and a hyphen belongs to the segment it sits in, so `AGENT-CONTEXT_UPDATE` is the two segments `agent-context` and `update` rather than three.
+An underscore separates command segments and a hyphen belongs to the segment
+it sits in, so `AGENT-CONTEXT_UPDATE` is the two segments `agent-context` and
+`update` rather than three. Copilot renders this as
+`/speckit-agent-context-update`.
**Example** β€” a command body that points the user at the next step:
@@ -314,21 +334,12 @@ The resolver maps each underscore back to the active agent's separator. An under
Once the assessment exists, the next step is `__SPECKIT_COMMAND_BUG_FIX__ slug=<slug>`.
```
-This renders as `/speckit.bug.fix slug=<slug>` for a slash-based agent, `/speckit-bug-fix slug=<slug>` for a skills-based agent, and so on β€” the author writes it once and it stays portable. The first-party `bug` and `git` extensions use this token exclusively; see `extensions/bug/commands/` for working examples.
-
-> **Skills mode.** Token resolution runs in both paths, so the token is safe to
-> use either way. Command files go through the command-rendering path
-> (`CommandRegistrar`). Skill bodies go through `_resolve_command_ref_tokens` in
-> `_register_extension_skills`, which resolves the same token shape against the
-> active skill style, so `__SPECKIT_COMMAND_BUG_FIX__` renders as:
->
-> | Agent | Rendered |
-> | --- | --- |
-> | Codex, ZCode, Command Code | `$speckit-bug-fix` |
-> | Claude, Copilot, Cursor, Devin, Droid, Grok and the other slash agents | `/speckit-bug-fix` |
-> | Kimi | `/skill:speckit-bug-fix` |
->
-> Anything else falls through to the integration's own `build_command_invocation`.
+This renders as `/speckit-bug-fix slug=<slug>` in Copilot chat. The first-party
+`bug` and `git` extensions use this token exclusively; see
+`extensions/bug/commands/` for working examples.
+
+For other integrations' invocation formats, see the shared
+[command invocation reference](../integrations/cli.md#command-invocation).
### Script Path Rewriting
@@ -498,7 +509,8 @@ The following `.gitignore` features are **not applicable** in this context:
### Manual Testing
-1. **Create test extension**
+1. **Create test extension** in a project configured for
+ [Copilot skills](../integrations/copilot.md#setup).
2. **Install locally**:
```bash
@@ -511,11 +523,11 @@ The following `.gitignore` features are **not applicable** in this context:
specify extension list
```
-4. **Test commands** with your AI agent
-5. **Check command registration**:
+4. **Test skills** in Copilot chat, for example `/speckit-my-ext-hello world`.
+5. **Check skill registration**:
```bash
- ls .claude/commands/speckit.my-ext.*
+ ls .github/skills/speckit-my-ext-*/SKILL.md
```
6. **Remove extension**:
@@ -601,7 +613,7 @@ Submit to the community catalog for public discovery:
- Users copy the entry to their own `catalog.json`
- Users install with: `specify extension add my-ext` (from their catalog)
-See the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html) for detailed submission instructions.
+See the [Extension Publishing Guide](publishing.md) for detailed submission instructions.
---
@@ -757,19 +769,19 @@ hooks:
**Error**: `Extension requires spec-kit >=0.2.0`
-- **Fix**: Upgrade Spec Kit using the [Upgrade Guide](../docs/upgrade.md). `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git` remains available as a source-install fallback. If you installed from PyPI and want to stay on that route, follow the [PyPI upgrade guidance](../docs/install/pypi.md#upgrade).
+- **Fix**: Upgrade Spec Kit using the [Upgrade Guide](../upgrade.md). `uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git` remains available as a source-install fallback. If you installed from PyPI and want to stay on that route, follow the [PyPI upgrade guidance](../install/pypi.md#upgrade).
**Error**: `Command file not found`
- **Fix**: Ensure command files exist at paths specified in manifest
-### Commands not registered
+### Skills not registered
-**Symptom**: Commands don't appear in AI agent
+**Symptom**: Skills don't appear in GitHub Copilot chat
**Check**:
-1. `.claude/commands/` directory exists
+1. The generated skill exists at `.github/skills/speckit-my-ext-hello/SKILL.md`
2. Extension installed successfully
3. Commands registered in registry:
@@ -777,7 +789,9 @@ hooks:
cat .specify/extensions/.registry
```
-**Fix**: Reinstall extension to trigger registration
+**Fix**: Confirm Copilot is configured for the
+[skills layout](../integrations/copilot.md#default-skills-layout), then
+reinstall the extension to trigger registration.
### Config not loading
@@ -805,3 +819,5 @@ hooks:
4. **Iterate** based on feedback
Happy extending! πŸš€
+
+> Agent invocation examples on this page use GitHub Copilot's default skills syntax (`/speckit-*`). For other integrations and modes, see [Command invocation](../integrations/cli.md#command-invocation).
diff --git a/docs/extensions/overview.md b/docs/extensions/overview.md
index 7343ce1cd..39ad4d405 100644
--- a/docs/extensions/overview.md
+++ b/docs/extensions/overview.md
@@ -1002,7 +1002,7 @@ After creating tasks, sync to Jira:
- **Extension Issues**: Report to extension repository (see `specify extension info`)
- **Spec Kit Issues**: <https://github.com/github/spec-kit/issues>
- **Extension Catalog**: <https://github.com/github/spec-kit/tree/main/extensions>
-- **Documentation**: See the [Extension Development Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md) and [Extension Publishing Guide](publishing.md)
+- **Documentation**: See [Developing extensions](developing.md) and [Extension Publishing Guide](publishing.md)
---
diff --git a/docs/extensions/publishing.md b/docs/extensions/publishing.md
index 8a453812b..2fe499093 100644
--- a/docs/extensions/publishing.md
+++ b/docs/extensions/publishing.md
@@ -303,7 +303,7 @@ A: Extensions should be free and open-source. Commercial support/services are al
- **Catalog Issues**: <https://github.com/statsperform/spec-kit/issues>
- **Extension Template**: <https://github.com/statsperform/spec-kit-extension-template> (coming soon)
-- **Development Guide**: See the [Extension Development Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md)
+- **Development Guide**: See [Developing extensions](developing.md)
- **Community**: Discussions and Q&A
---
diff --git a/docs/toc.yml b/docs/toc.yml
index f1ee2c31a..e71b0ad5f 100644
--- a/docs/toc.yml
+++ b/docs/toc.yml
@@ -141,6 +141,8 @@
items:
- name: Overview
href: extensions/overview.md
+ - name: Developing
+ href: extensions/developing.md
- name: Publishing
href: extensions/publishing.md
diff --git a/extensions/README.md b/extensions/README.md
index 8012c8b4b..de19d300d 100644
--- a/extensions/README.md
+++ b/extensions/README.md
@@ -87,7 +87,7 @@ For the raw catalog data, see [`catalog.community.json`](catalog.community.json)
To add your extension to the community catalog:
-1. **Prepare your extension** following the [Extension Development Guide](EXTENSION-DEVELOPMENT-GUIDE.md)
+1. **Prepare your extension** following the [Extension Development Guide](https://github.github.io/spec-kit/extensions/developing.html)
2. **Create a GitHub release** for your extension
3. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with all required metadata
4. **Wait for review** β€” a maintainer will review the submission, update the catalog, and close the issue
diff --git a/extensions/template/README.md b/extensions/template/README.md
index 7865144f9..899591580 100644
--- a/extensions/template/README.md
+++ b/extensions/template/README.md
@@ -67,7 +67,7 @@ Starter template for creating a Spec Kit extension.
## Need Help?
-- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md
+- **Development Guide**: See [Extension Development Guide](https://github.github.io/spec-kit/extensions/developing.html)
- **API Reference**: See EXTENSION-API-REFERENCE.md
- **Publishing Guide**: See the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html)
- **User Guide**: See the [Extension User Guide](https://github.github.io/spec-kit/extensions/overview.html)
diff --git a/tests/extensions/bug/test_bug_hooks.py b/tests/extensions/bug/test_bug_hooks.py
index 1e5c42530..703162143 100644
--- a/tests/extensions/bug/test_bug_hooks.py
+++ b/tests/extensions/bug/test_bug_hooks.py
@@ -82,7 +82,7 @@ def test_assess_ensures_bug_directory_before_hook_checks():
@pytest.mark.parametrize("path", [
ROOT / "extensions/EXTENSION-API-REFERENCE.md",
- ROOT / "extensions/EXTENSION-DEVELOPMENT-GUIDE.md",
+ ROOT / "docs/extensions/developing.md",
ROOT / "docs/extensions/overview.md",
EXT_DIR / "README.md",
])