開發擴充功能
使用 GitHub Copilot skills 配置建立 Spec Kit 擴充功能的指南。在 Copilot 聊天中以連字號名稱呼叫 skills,例如 /speckit-my-ext-hello。擴充功能資訊清單仍使用帶點的命令識別碼,例如 speckit.my-ext.hello;Spec Kit 會在安裝時將它們轉譯為 Copilot skills。
快速入門
1. 建立擴充功能目錄
mkdir my-extension
cd my-extension
2. 建立 extension.yml 資訊清單
schema_version: "1.0"
extension:
id: "my-ext" # Lowercase, alphanumeric + hyphens only
name: "My Extension"
version: "1.0.0" # SemVer recommended; PEP 440 accepted
description: "My custom extension"
author: "Your Name"
repository: "https://github.com/you/spec-kit-my-ext"
license: "MIT"
requires:
speckit_version: ">=0.1.0" # Minimum spec-kit version
tools: # Optional: External tools required
- name: "my-tool"
required: true
version: ">=1.0.0"
commands: # Optional: Core commands needed
- "speckit.tasks"
provides:
commands:
- name: "speckit.my-ext.hello" # Must follow pattern: speckit.{ext-id}.{cmd}
file: "commands/hello.md"
description: "Say hello"
config: # Optional: Config files
- name: "my-ext-config.yml"
template: "my-ext-config.template.yml"
description: "Extension configuration"
required: false
hooks: # Optional: Integration hooks
after_tasks:
command: "speckit.my-ext.hello"
optional: true
prompt: "Run hello command?"
tags: # Optional: For catalog search
- "example"
- "utility"
3. 建立命令目錄
mkdir commands
4. 建立命令檔案
檔案:commands/hello.md
---
description: "Say hello command"
tools: # Optional: AI tools this command uses
- 'some-tool/function'
scripts: # Optional: Helper scripts
sh: ../../scripts/bash/helper.sh
ps: ../../scripts/powershell/helper.ps1
---
# Hello Command
This command says hello!
## User Input
$ARGUMENTS
## Steps
1. Greet the user
2. Show extension is working
```bash
echo "Hello from my extension!"
echo "Arguments: $ARGUMENTS"
```
## Extension Configuration
Load extension config from `.specify/extensions/my-ext/my-ext-config.yml`.
5. 在本機測試
cd /path/to/spec-kit-project
specify integration install copilot --integration-options="--skills"
specify extension add --dev /path/to/my-extension
對於新專案,請以 specify init my-project --integration copilot --integration-options="--skills" 初始化。如果 Copilot 已以 commands 配置安裝,請遵循 Copilot 遷移指南,不要再次安裝。
6. 驗證安裝
specify extension list
# Should show:
# ✓ My Extension (v1.0.0)
# My custom extension
# Commands: 1 | Hooks: 1 | Status: Enabled
7. 測試 Skill
開啟 GitHub Copilot 聊天並呼叫該 skill:
/speckit-my-ext-hello world
產生的 skill 位於 .github/skills/speckit-my-ext-hello/SKILL.md。此呼叫應在 Copilot 聊天中進行,不是在終端機中。
資訊清單結構描述參考
必填欄位
schema_version
擴充功能資訊清單結構描述版本。目前為:"1.0"
extension
擴充功能後設資料區塊。
必填子欄位:
id:擴充功能識別碼(小寫、英數字元、連字號)name:方便閱讀的名稱version:PEP 440 版本(建議使用 SemVer,例如 "1.0.0")description:簡短說明
選用子欄位:
author:擴充功能作者repository:原始碼 URLlicense:SPDX 授權識別碼homepage:擴充功能首頁 URL
requires
相容性需求。
必填子欄位:
speckit_version:語意化版本指定子(例如 ">=0.1.0,<2.0.0")
選用子欄位:
tools:所需的外部工具(工具物件陣列)commands:所需的核心 spec-kit 命令(命令名稱陣列)scripts:所需的核心指令碼(指令碼名稱陣列)
provides
擴充功能提供的內容。
選用子欄位:
commands:命令物件陣列templates:範本物件陣列scripts:指令碼物件陣列
hooks 與 events 是獨立的頂層資訊清單欄位(與 provides 同層級,不巢狀於其下——見下文 hooks)。provides.commands、provides.templates、provides.scripts、hooks 或 events 至少需要一個。
命令物件:
name:命令名稱(必須符合speckit.{ext-id}.{command})file:命令檔案路徑(相對於擴充功能根目錄)description:命令說明(選用)
範本物件:
name:範本名稱(小寫、英數字元、連字號——例如myext-template)file:範本檔案路徑(相對於擴充功能根目錄)description:範本說明(選用)
指令碼物件:
name:指令碼名稱(小寫、英數字元、連字號——例如myext-collect)file:指令碼檔案路徑(相對於擴充功能根目錄)description:指令碼說明(選用)runtimes:指令碼支援的執行環境(選用,陣列;bash、powershell、python的子集——僅供資訊參考,不用於選擇或呼叫指令碼)
擴充功能提供的範本與指令碼一律解析為 replace;若資訊清單在其中一個條目上包含 strategy 鍵,將以 ValidationError 拒絕。可組合策略(wrap/prepend/append)僅供預設集使用。
選用欄位
hooks
用於自動執行的整合 hook。
可用的 hook 點:
before_specify/after_specify:規格產生之前/之後before_plan/after_plan:實作規劃之前/之後before_tasks/after_tasks:任務產生之前/之後before_implement/after_implement:實作之前/之後before_analyze/after_analyze:跨成品分析之前/之後before_checklist/after_checklist:檢核清單產生之前/之後before_clarify/after_clarify:規格釐清之前/之後before_constitution/after_constitution:憲章更新之前/之後before_converge/after_converge:收斂評估之前/之後before_bug_assess/after_bug_assess:錯誤評估之前/之後(內建bug擴充功能)before_bug_fix/after_bug_fix:錯誤修復之前/之後(內建bug擴充功能)before_bug_test/after_bug_test:錯誤驗證之前/之後(內建bug擴充功能)
每個事件可接受單一 hook 物件或 hook 物件清單(一個事件多個命令)。
Hook 物件:
command:要執行的命令(通常來自provides.commands,但可引用任何已註冊命令)priority:HookExecutor的排序中繼資料(整數 ≥ 1,預設為 10);目前的命令範本改為依設定的 YAML 順序呈現 hookoptional:若為 true,執行前提示使用者prompt:選用 hook 的提示文字description:Hook 說明condition:由HookExecutor求值的運算式;目前的命令範本會跳過條件非空的 hook,而非求值它們
所有欄位,以及 Python API 與命令範本行為之間的區別,請參閱掛鉤設定合約。
events
執行時期事件會回應程式代理的生命週期,而非 Spec Kit 命令。請在頂層宣告正式名稱,並參照帶有可執行 scripts 項目的命令範本:
events:
session_start:
command: speckit.my-ext.initialize
例如,commands/initialize.md 可以宣告:
---
description: "Initialize the extension session"
scripts:
sh: scripts/initialize.sh
ps: scripts/initialize.ps1
---
請將該命令納入 provides.commands,並在你的擴充功能中提供指令稿。執行時期事件會直接執行指令稿;它們不會將命令的 Markdown 主體傳送給程式代理。每個整合支援正式事件的子集。請參閱執行時期事件合約。
tags
用於型錄探索的標籤陣列。
defaults
擴充功能的預設設定值。
命令檔案格式
Frontmatter(YAML)
---
description: "Command description" # Recommended
tools: # Optional
- 'tool-name/function'
scripts: # Optional
sh: ../../scripts/bash/helper.sh
ps: ../../scripts/powershell/helper.ps1
---
內文(Markdown)
使用標準 Markdown 搭配特殊佔位符:
$ARGUMENTS:使用者提供的參數{SCRIPT}:註冊時替換為指令碼路徑__SPECKIT_COMMAND_<NAME>__:替換為另一個命令的呼叫方式,使用目前整合的分隔符轉譯(見引用其他命令)
範例:
## Steps
1. Parse arguments
2. Execute logic
```bash
args="$ARGUMENTS"
echo "Running with args: $args"
```
引用其他命令
命令內文是 Spec Kit 轉譯為 Copilot skill 的範本。從該內文引用另一個命令時,不要硬編碼其呼叫方式。請使用命令引用權杖,讓 Spec Kit 轉譯出正確的 skill 語法,並保持擴充功能的可攜性。
使用權杖 __SPECKIT_COMMAND_<NAME>__。在 Copilot 的 skills 配置中,Spec Kit 會將它解析為 /speckit-... 呼叫。
命令名稱以大寫編碼,省略 speckit. 前綴,並將每個以點分隔的區段分隔符轉為底線。區段內的連字號保持為連字號:
| 命令檔案 | 權杖 |
|---|---|
speckit.plan.md |
__SPECKIT_COMMAND_PLAN__ |
speckit.bug.fix.md |
__SPECKIT_COMMAND_BUG_FIX__ |
speckit.git.commit.md |
__SPECKIT_COMMAND_GIT_COMMIT__ |
speckit.agent-context.update.md |
__SPECKIT_COMMAND_AGENT-CONTEXT_UPDATE__ |
底線分隔命令區段,連字號屬於它所在的區段,因此 AGENT-CONTEXT_UPDATE 是 agent-context 與 update 兩個區段,而不是三個。Copilot 會將此轉譯為 /speckit-agent-context-update。
範例——將使用者指向下一步的命令內文:
Once the assessment exists, the next step is `__SPECKIT_COMMAND_BUG_FIX__ slug=<slug>`.
在 Copilot 聊天中,這會轉譯為 /speckit-bug-fix slug=<slug>。第一方的 bug 與 git 擴充功能專門使用此權杖;實際範例見 extensions/bug/commands/。
其他整合的呼叫格式,請參閱共用的命令呼叫參考。
指令碼路徑重寫
登錄器在渲染命令時會正規化輔助程式路徑。
含有兩個以上 ../ 區段的儲存庫根目錄參照,指向專案的核心指令稿。
在擴充功能中:
scripts:
sh: ../../scripts/bash/helper.sh
在命令主體中使用 {SCRIPT} 來呼叫選取的指令稿變體。對於此範例,產生的呼叫如下:
.specify/scripts/bash/helper.sh
裸寫的 scripts/helper.sh 則指向擴充功能自有指令稿 .specify/extensions/<extension-id>/scripts/helper.sh。產生的輸出格式可能在解析 {SCRIPT} 後省略原始的 scripts frontmatter;請勿依賴該中繼資料在已安裝的命令或技能中留存。
設定檔
設定範本
檔案:my-ext-config.template.yml
# My Extension Configuration
# Copy this to my-ext-config.yml and customize
# Example configuration
api:
endpoint: "https://api.example.com"
timeout: 30
key: "" # Set with SPECKIT_MY_EXT_API_KEY; do not commit credentials
features:
feature_a: true
feature_b: false
設定載入
在你的命令中,以分層優先順序載入設定:
- 擴充功能預設值(
extension.yml→defaults,再取config.defaults處理任何衝突的鍵) - 專案設定(
.specify/extensions/my-ext/my-ext-config.yml) - 本機覆寫(
.specify/extensions/my-ext/local-config.yml——gitignored) - 環境變數(
SPECKIT_MY_EXT_*)
對於在已安裝 specify-cli 的環境中執行的 Python 程式碼,請使用既有的載入器,而非重複實作合併:
from pathlib import Path
from specify_cli.extensions import ConfigManager
config = ConfigManager(Path.cwd(), "my-ext").get_config()
endpoint = config.get("api", {}).get("endpoint")
請從專案根目錄執行,或明確傳入該根目錄。環境變數的組成部分會成為巢狀鍵:SPECKIT_MY_EXT_API_KEY 會覆寫 api.key。值維持字串;YAML ${...} 佔位符不會被展開。以其他語言實作的命令若需要此分層,必須自行提供載入。
Spec Kit 不會使用 config_schema 來驗證設定。請在你的擴充功能命令或指令稿中驗證必要的值與類型。
以 .extensionignore 排除檔案
擴充功能作者可以在擴充功能根目錄建立 .extensionignore 檔案,排除使用者以 specify extension add 安裝擴充功能時不應複製的檔案與資料夾。這對於將僅供開發的檔案(測試、CI 設定、文件來源等)排除在安裝副本之外很有用。
格式
此檔案使用與 .gitignore 相容的模式(每行一個),由 pathspec 程式庫驅動:
- 空行會被忽略
- 以
#開頭的行是註解 *符合除/以外的任何內容(不跨目錄邊界)**符合零個或多個目錄(例如docs/**/*.draft.md)?符合除/以外的任何單一字元- 結尾的
/將模式限制為僅目錄 - 包含
/的模式(結尾斜線除外)會錨定到擴充功能根目錄 - 不含
/的模式可在樹狀結構的任何深度符合 !否定先前已排除的模式(重新包含檔案)- 模式中的反斜線會正規化為正斜線,以確保跨平台相容性
.extensionignore檔案本身一律自動排除
範例
# .extensionignore
# Development files
tests/
.github/
.gitignore
# Build artifacts
__pycache__/
*.pyc
dist/
# Documentation source (keep only the built README)
docs/
CONTRIBUTING.md
模式比對
| 模式 | 符合 | 不符合 |
|---|---|---|
*.pyc |
任何目錄中的任何 .pyc 檔案 |
— |
tests/ |
tests 目錄(及其全部內容) |
名為 tests 的檔案 |
docs/*.draft.md |
docs/api.draft.md(直接位於 docs/ 內) |
docs/sub/api.draft.md(巢狀) |
.env |
任何層級的 .env 檔案 |
— |
!README.md |
即使被先前模式符合,也重新包含 README.md |
— |
docs/**/*.draft.md |
docs/api.draft.md、docs/sub/api.draft.md |
— |
不支援的功能
以下 .gitignore 功能在此情境中不適用:
- 多個
.extensionignore檔案:僅支援擴充功能根目錄的單一檔案(.gitignore支援子目錄中的檔案) $GIT_DIR/info/exclude與core.excludesFile:這些是 Git 專屬功能,此處無對應功能- 已排除目錄內的否定:由於檔案複製使用
shutil.copytree,排除目錄會完全阻止遞迴進入。否定模式無法重新包含本身已被排除的目錄內的檔案。例如,tests/後接!tests/important.py的組合將不會保留tests/important.py——tests/目錄會在根層級被跳過,其內容永遠不會被評估。若要解決此問題,請個別排除目錄的內容,而非目錄本身(例如使用tests/*.pyc與tests/.cache/,而非tests/)。
驗證規則
擴充功能 ID
- 模式:
^[a-z0-9-]+$ - 有效:
my-ext、tool-123、awesome-plugin - 無效:
MyExt(大寫)、my_ext(底線)、my ext(空格)
擴充功能版本
- 格式:PEP 440;發行版本建議使用 SemVer(
MAJOR.MINOR.PATCH) - 有效:
1.0.0、0.1.0、2.5.3 - CLI 亦接受:
1.0、v1.0.0、1.0.0-beta - 無效:
latest、not-a-version
社群提交對發行版本有更嚴格的要求;請參閱提交驗證。
命令名稱
- 模式:
^speckit\.[a-z0-9-]+\.[a-z0-9-]+$ - 有效:
speckit.my-ext.hello、speckit.tool.cmd - 無效:
other-ext.hello(錯誤的命名空間)、speckit.my-ext.Create(大寫)
舊版的 my-ext.hello 與 speckit.hello 會正規化為 speckit.my-ext.hello,並發出警告。請在新的資訊清單中使用正式名稱。
命令檔案路徑
- 必須相對於擴充功能根目錄
- 有效:
commands/hello.md、commands/subdir/cmd.md - 無效:
/absolute/path.md、../outside.md
測試擴充功能
手動測試
在已設定 Copilot skills 的專案中建立測試擴充功能。
在本機安裝:
specify extension add --dev /path/to/extension驗證安裝:
specify extension list在 Copilot 聊天中測試 skills,例如
/speckit-my-ext-hello world。檢查 skill 註冊:
ls .github/skills/speckit-my-ext-*/SKILL.md移除擴充功能:
specify extension remove my-ext
自動化測試
為你的擴充功能建立測試:
# tests/test_my_extension.py
import pytest
from pathlib import Path
from specify_cli.extensions import ExtensionManifest
def test_manifest_valid():
"""Test extension manifest is valid."""
manifest = ExtensionManifest(Path("extension.yml"))
assert manifest.id == "my-ext"
assert len(manifest.commands) >= 1
def test_command_files_exist():
"""Test all command files exist."""
manifest = ExtensionManifest(Path("extension.yml"))
for cmd in manifest.commands:
cmd_file = Path(cmd["file"])
assert cmd_file.exists(), f"Command file not found: {cmd_file}"
發佈
選項 1:GitHub 儲存庫
建立儲存庫:
spec-kit-my-ext加入檔案:
spec-kit-my-ext/ ├── extension.yml ├── commands/ ├── scripts/ ├── docs/ ├── README.md ├── LICENSE └── CHANGELOG.md建立發行版本:以版本標記(例如
v1.0.0)從儲存庫安裝:
git clone https://github.com/you/spec-kit-my-ext specify extension add --dev spec-kit-my-ext/
選項 2:ZIP 封存檔
建立 ZIP 封存檔並託管在 GitHub Releases:
zip -r spec-kit-my-ext-1.0.0.zip extension.yml commands/ scripts/ docs/
使用者以下列方式安裝:
specify extension add <extension-name> --from https://github.com/.../spec-kit-my-ext-1.0.0.zip
選項 3:社群參考型錄
提交到社群型錄供公開探索:
- 為你的擴充功能建立 GitHub 發行版本
- 使用 Extension Submission 範本建立 issue
- 審查後,維護者會更新型錄,你的擴充功能即可用:
- 使用者可瀏覽
catalog.community.json探索你的擴充功能 - 使用者在直接安裝或加入自己信任的型錄之前,會先審查發行封存檔
- 使用者以
--from <archive-url>安裝,或從他們審查過的型錄安裝
- 使用者可瀏覽
詳細提交說明請參閱擴充功能發佈指南。
最佳實務
命名慣例
- 擴充功能 ID:使用具描述性的連字號名稱(
jira-integration,而非ji) - 命令:使用動詞-名詞模式(
create-issue、sync-status) - 設定檔:與擴充功能 ID 相符(
jira-config.yml)
文件
- README.md:概覽、安裝、使用
- CHANGELOG.md:版本歷史
- docs/:詳細指南
- 命令說明:清晰、簡潔
版本管理
- 遵循 SemVer:
MAJOR.MINOR.PATCH - MAJOR:破壞性變更
- MINOR:新功能
- PATCH:錯誤修正
- 每次內容變更都要提升版本:
specify extension update的更新提供由版本驅動,因此未提升版本就出貨的內容變更,永遠不會自動交付給已安裝的副本。對於此儲存庫中的內建擴充功能,提升版本由 CI 強制執行(extension-version-guard.yml):變更extensions/<id>/下檔案的 PR,也必須提升該擴充功能的extension.yml版本,並保持extensions/catalog.json同步。
安全性
- 絕不提交機密:使用環境變數
- 驗證輸入:清理使用者參數
- 記錄權限:會存取哪些檔案/API
相容性
- 指定版本範圍:不要要求精確版本
- 以多個版本測試:確保相容性
- 優雅降級:處理缺少的功能
擴充功能範例
最小擴充功能
最小可行的擴充功能:
# extension.yml
schema_version: "1.0"
extension:
id: "minimal"
name: "Minimal Extension"
version: "1.0.0"
description: "Minimal example"
requires:
speckit_version: ">=0.1.0"
provides:
commands:
- name: "speckit.minimal.hello"
file: "commands/hello.md"
<!-- commands/hello.md -->
---
description: "Hello command"
---
# Hello World
```bash
echo "Hello, $ARGUMENTS!"
```
附設定的擴充功能
使用設定的擴充功能:
# extension.yml
# ... metadata ...
provides:
config:
- name: "tool-config.yml"
template: "tool-config.template.yml"
required: true
# tool-config.template.yml
api_endpoint: "https://api.example.com"
timeout: 30
<!-- commands/use-config.md -->
# Use Config
Load config:
```bash
config_file=".specify/extensions/tool/tool-config.yml"
endpoint=$(yq eval '.api_endpoint' "$config_file")
echo "Using endpoint: $endpoint"
```
附 Hook 的擴充功能
自動執行的擴充功能:
# extension.yml
hooks:
after_tasks:
command: "speckit.auto.analyze"
optional: false # Always run
description: "Analyze tasks after generation"
一個事件多個命令,依目前命令範本的 YAML 順序呈現(HookExecutor 則改為依 priority 排序,數字越小越先):
# extension.yml
hooks:
after_plan:
- command: "speckit.my-ext.verify"
priority: 5
optional: false
description: "Verify the plan"
- command: "speckit.my-ext.report"
priority: 10
optional: true
prompt: "Generate the report?"
description: "Generate a report from the plan"
疑難排解
擴充功能無法安裝
錯誤:Invalid extension ID
- 修正:僅使用小寫、英數字元加連字號
錯誤:Extension requires spec-kit >=0.2.0
- 修正:使用升級指南升級 Spec Kit。
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git仍可作為從原始碼安裝的備援方式。如果你是從 PyPI 安裝並希望沿用該路徑,請遵循 PyPI 升級指南。
錯誤:Command file not found
- 修正:確保命令檔案存在於資訊清單指定的路徑
Skills 未註冊
症狀:Skills 未出現在 GitHub Copilot 聊天中
檢查:
產生的 skill 存在於
.github/skills/speckit-my-ext-hello/SKILL.md擴充功能安裝成功
命令已在登錄中註冊:
cat .specify/extensions/.registry
修正:確認 Copilot 已設定為 skills 配置,然後重新安裝擴充功能以觸發註冊。
設定未載入
檢查:
- 設定檔存在:
.specify/extensions/{ext-id}/{ext-id}-config.yml - YAML 語法有效:
yq eval '.' config.yml - 環境變數設定正確
取得協助
後續步驟
- 依本指南建立你的擴充功能
- 以
--dev旗標在本機測試 - 與社群分享(GitHub、型錄)
- 根據回饋迭代
祝擴充愉快!🚀
本頁的代理呼叫範例使用 GitHub Copilot 的預設 skills 語法(
/speckit-*)。其他整合與模式,請參閱命令呼叫。