diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 04d1923b5b..2c1e35362f 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 155a50b4be..e1babe7778 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___`. Spec Kit resolves it to a `/speckit...` invocation using the active integration's `invoke_separator` (and integrations may post-process that further in skills output). +Use the token `__SPECKIT_COMMAND___`. 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=`. ``` -This renders as `/speckit.bug.fix slug=` for a slash-based agent, `/speckit-bug-fix 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=` 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 7343ce1cda..39ad4d4050 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**: - **Extension Catalog**: -- **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 8a453812b8..2fe499093f 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**: - **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 f1ee2c31a4..e71b0ad5f8 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 8012c8b4b5..de19d300d5 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 7865144f9c..8995915803 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 1e5c425309..703162143f 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", ])