Skip to content

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

docs: publish extensions overview and navigation (#5165)

Manfred Riem3f4c5766ad59
diff --git a/docs/README.md b/docs/README.md
index 4bd3657d1..6849107b3 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -33,6 +33,7 @@ To build the documentation locally:
- `guides/assessment.md` - Idea assessment walkthrough
- `guides/customization.md` - Choosing and combining customization building blocks
- `reference/catalogs.md` - Catalog discovery, trust, private sources, and precedence
+- `extensions/overview.md` - Extension user guide
- `extensions/publishing.md` - Extension publishing and catalog submission guide
- `integrations/index.md` - Integration directory and shared setup guidance
- `integrations/cli.md` - Shared integration management CLI reference
diff --git a/extensions/EXTENSION-USER-GUIDE.md b/docs/extensions/overview.md
similarity index 90%
rename from extensions/EXTENSION-USER-GUIDE.md
rename to docs/extensions/overview.md
index 1561b3c9f..7343ce1cd 100644
--- a/extensions/EXTENSION-USER-GUIDE.md
+++ b/docs/extensions/overview.md
@@ -1,4 +1,4 @@
-# Extension User Guide
+# Extensions Overview
Complete guide for using Spec Kit extensions to enhance your workflow.
@@ -68,8 +68,8 @@ specify extension add jira
vim .specify/extensions/jira/jira-config.yml
# 5. Use it
-# (Commands are now available in Claude Code)
-/speckit.jira.specstoissues
+# (Skills are now available in GitHub Copilot)
+/speckit-jira-specstoissues
```
---
@@ -179,45 +179,25 @@ Jira Integration (v1.0.0)
Create Jira Epics, Stories, and Issues from spec-kit artifacts
Provided commands:
- β€’ speckit.jira.specstoissues - Create Jira hierarchy from spec and tasks
- β€’ speckit.jira.discover-fields - Discover Jira custom fields for configuration
- β€’ speckit.jira.sync-status - Sync task completion status to Jira
+ β€’ speckit-jira-specstoissues - Create Jira hierarchy from spec and tasks
+ β€’ speckit-jira-discover-fields - Discover Jira custom fields for configuration
+ β€’ speckit-jira-sync-status - Sync task completion status to Jira
⚠ Configuration may be required
Check: .specify/extensions/jira/
```
-Command names are listed the way your agent registers them. Skills-based integrations such as Claude Code and Codex, projects initialized with `--integration-options="--skills"`, and agents such as Cline, Forge, and Junie show hyphenated names (for example `speckit-jira-specstoissues`).
-
-### Automatic Agent Skill Registration
-
-If your project uses a skills-based integration (e.g., `--integration claude`, `--integration codex`) or was initialized with `--integration-options="--skills"`, extension commands are **automatically registered as agent skills** during installation. This ensures that extensions are discoverable by agents that use the [agentskills.io](https://agentskills.io) skill specification.
-
-```text
-βœ“ Extension installed successfully!
-
-Jira Integration (v1.0.0)
- ...
-
-βœ“ 3 agent skill(s) auto-registered
-```
-
-When an extension is removed, its corresponding skills are also cleaned up automatically. Pre-existing skills that were manually customized are never overwritten.
-
---
## Using Extensions
### Using Extension Commands
-Extensions add commands that appear in your coding agent (Claude Code):
+Extensions add skills that appear in GitHub Copilot:
```text
-# In Claude Code
-> /speckit.jira.specstoissues
-
-# Or use a namespaced alias (if provided)
-> /speckit.jira.sync
+# In GitHub Copilot
+> /speckit-jira-specstoissues
```
### Extension Configuration
@@ -243,21 +223,21 @@ vim .specify/extensions/jira/jira-config.yml
Some extensions provide hooks that execute after core commands:
-**Example**: Jira extension hooks into `/speckit.tasks`
+**Example**: Jira extension hooks into `/speckit-tasks`
```text
# Run core command
-> /speckit.tasks
+> /speckit-tasks
# Output includes:
## Extension Hooks
**Optional Hook**: jira
-Command: `/speckit.jira.specstoissues`
+Command: `/speckit-jira-specstoissues`
Description: Automatically create Jira hierarchy after task generation
Prompt: Create Jira issues from tasks?
-To execute: `/speckit.jira.specstoissues`
+To execute: `/speckit-jira-specstoissues`
```
You can then choose to run the hook or skip it.
@@ -348,7 +328,7 @@ Extensions can have multiple configuration files:
```text
.specify/extensions/jira/
β”œβ”€β”€ jira-config.yml # Main config (version controlled)
-β”œβ”€β”€ jira-config.local.yml # Local overrides (gitignored)
+β”œβ”€β”€ local-config.yml # Local overrides (gitignored)
└── jira-config.template.yml # Template (reference)
```
@@ -358,7 +338,7 @@ Configuration is merged in this order (highest priority last):
1. **Extension defaults** (from `extension.yml`)
2. **Project config** (`jira-config.yml`)
-3. **Local overrides** (`jira-config.local.yml`)
+3. **Local overrides** (`local-config.yml`)
4. **Environment variables** (`SPECKIT_JIRA_*`)
### Example: Jira Configuration
@@ -374,7 +354,7 @@ defaults:
labels: ["spec-driven"]
```
-**Local override** (`.specify/extensions/jira/jira-config.local.yml`):
+**Local override** (`.specify/extensions/jira/local-config.yml`):
```yaml
project:
@@ -805,11 +785,11 @@ specify extension add --dev /path/to/extension
**Solutions**:
1. Check extension is enabled: `specify extension list`
-2. Restart coding agent (Claude Code)
-3. Check command file exists:
+2. Restart GitHub Copilot
+3. Check the skill file exists:
```bash
- ls .claude/commands/speckit.jira.*.md
+ ls .github/skills/speckit-jira-*/SKILL.md
```
4. Reinstall extension
@@ -868,7 +848,7 @@ specify extension add --dev /path/to/extension
- `.specify/extensions/.cache/` (catalog cache)
- `.specify/extensions/.backup/` (config backups)
-- `.specify/extensions/*/*.local.yml` (local overrides)
+- `.specify/extensions/*/local-config.yml` (local overrides)
- `.specify/extensions/.registry` (installation state)
Add to `.gitignore`:
@@ -876,7 +856,7 @@ Add to `.gitignore`:
```gitignore
.specify/extensions/.cache/
.specify/extensions/.backup/
-.specify/extensions/*/*.local.yml
+.specify/extensions/*/local-config.yml
.specify/extensions/.registry
```
@@ -907,7 +887,7 @@ To install: `specify extension add jira`
Use local config for development:
```yaml
-# .specify/extensions/jira/jira-config.local.yml
+# .specify/extensions/jira/local-config.yml
project:
key: "DEVTEST" # Your test project
@@ -966,9 +946,9 @@ Document extension usage in your project:
## Working with Jira
After creating tasks, sync to Jira:
-1. Run `/speckit.tasks` to generate tasks
-2. Run `/speckit.jira.specstoissues` to create Jira issues
-3. Run `/speckit.jira.sync-status` to update status
+1. Run `/speckit-tasks` to generate tasks
+2. Run `/speckit-jira-specstoissues` to create Jira issues
+3. Run `/speckit-jira-sync-status` to update status
```
---
@@ -1020,11 +1000,13 @@ After creating tasks, sync to Jira:
## Support
- **Extension Issues**: Report to extension repository (see `specify extension info`)
-- **Spec Kit Issues**: <https://github.com/statsperform/spec-kit/issues>
-- **Extension Catalog**: <https://github.com/statsperform/spec-kit/tree/main/extensions>
-- **Documentation**: See EXTENSION-DEVELOPMENT-GUIDE.md and the [Extension Publishing Guide](https://github.github.com/spec-kit/extensions/publishing.html)
+- **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)
---
*Last Updated: 2026-01-28*
*Spec Kit Version: 0.1.0*
+
+> 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/toc.yml b/docs/toc.yml
index 31a64b61d..f1ee2c31a 100644
--- a/docs/toc.yml
+++ b/docs/toc.yml
@@ -135,6 +135,15 @@
- name: Contributing Integrations
href: integrations/contributing.md
+# Extensions
+- name: Extensions
+ href: extensions/overview.md
+ items:
+ - name: Overview
+ href: extensions/overview.md
+ - name: Publishing
+ href: extensions/publishing.md
+
# Reference
- name: Reference
items:
@@ -199,8 +208,6 @@
href: community/overview.md
- name: Extensions
href: community/extensions.md
- - name: Publishing Extensions
- href: extensions/publishing.md
- name: Presets
href: community/presets.md
- name: Bundles
diff --git a/extensions/EXTENSION-API-REFERENCE.md b/extensions/EXTENSION-API-REFERENCE.md
index 2be2f4312..3ba164183 100644
--- a/extensions/EXTENSION-API-REFERENCE.md
+++ b/extensions/EXTENSION-API-REFERENCE.md
@@ -44,7 +44,6 @@ provides:
- name: string # Required, pattern: ^speckit\.[a-z0-9-]+\.[a-z0-9-]+$
file: string # Required, relative path to command file
description: string # Required
- aliases: [string] # Optional, same pattern as name; namespace must match extension.id and must not shadow core or installed extension commands
templates: # Optional, array of declared templates. Always resolve
# as "replace" -- 'strategy' is not an authorable field here.
diff --git a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
index fb06f7230..155a50b4b 100644
--- a/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
+++ b/extensions/EXTENSION-DEVELOPMENT-GUIDE.md
@@ -41,7 +41,6 @@ provides:
- name: "speckit.my-ext.hello" # Must follow pattern: speckit.{ext-id}.{cmd}
file: "commands/hello.md"
description: "Say hello"
- aliases: ["speckit.my-ext.hi"] # Optional aliases, same pattern
config: # Optional: Config files
- name: "my-ext-config.yml"
@@ -193,7 +192,6 @@ of `provides.commands`, `provides.templates`, `provides.scripts`, `hooks`, or
- `name`: Command name (must match `speckit.{ext-id}.{command}`)
- `file`: Path to command file (relative to extension root)
- `description`: Command description (optional)
-- `aliases`: Alternative command names (optional, array; each must match `speckit.{ext-id}.{command}`)
**Template object**:
diff --git a/extensions/README.md b/extensions/README.md
index 70156a8fc..8012c8b4b 100644
--- a/extensions/README.md
+++ b/extensions/README.md
@@ -120,4 +120,4 @@ specify extension add <extension-name> --from https://github.com/<org>/<repo>/ar
specify extension list
```
-For more information, see the [Extension User Guide](EXTENSION-USER-GUIDE.md).
+For more information, see the [Extension User Guide](../docs/extensions/overview.md).
diff --git a/extensions/github/README.md b/extensions/github/README.md
index f6debdc5d..6ee2100ac 100644
--- a/extensions/github/README.md
+++ b/extensions/github/README.md
@@ -112,7 +112,7 @@ available during this deprecation period until the removal stage.
| ------------------------- | --------------------------------- |
| `/speckit.taskstoissues` | `/speckit.github.taskstoissues` |
-Apart from the core command's deprecation warning, conversion behavior is unchanged: the same feature resolution, the same `plan.md` and `tasks.md` prerequisites, the same remote validation, the same deduplication across open and closed issues, the same issue titles, and the same hook contract. This extension does **not** register `speckit.taskstoissues` as an alias, so the two commands coexist without shadowing each other while the core command still exists.
+Apart from the core command's deprecation warning, conversion behavior is unchanged: the same feature resolution, the same `plan.md` and `tasks.md` prerequisites, the same remote validation, the same deduplication across open and closed issues, the same issue titles, and the same hook contract. The extension command and deprecated core command coexist without shadowing each other while the core command still exists.
### Presets and dependent extensions
diff --git a/extensions/template/README.md b/extensions/template/README.md
index 8b4274aa4..7865144f9 100644
--- a/extensions/template/README.md
+++ b/extensions/template/README.md
@@ -70,7 +70,7 @@ Starter template for creating a Spec Kit extension.
- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md
- **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 EXTENSION-USER-GUIDE.md
+- **User Guide**: See the [Extension User Guide](https://github.github.io/spec-kit/extensions/overview.html)
## Template Version
diff --git a/tests/extensions/bug/test_bug_hooks.py b/tests/extensions/bug/test_bug_hooks.py
index 045265cb4..1e5c42530 100644
--- a/tests/extensions/bug/test_bug_hooks.py
+++ b/tests/extensions/bug/test_bug_hooks.py
@@ -83,7 +83,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 / "extensions/EXTENSION-USER-GUIDE.md",
+ ROOT / "docs/extensions/overview.md",
EXT_DIR / "README.md",
])
def test_hook_events_documented(path):