Spec Kit CN 扩展开发完整指南:从0到1发布你的 extension.yml、Hooks 与目录上架
Spec Kit CN 扩展开发完整指南:从0到1发布你的 extension.yml、Hooks 与目录上架
Spec Kit CN 扩展开发入门:本教程带你从 0 到 1 发布属于自己的扩展,逐步讲解 extension.yml 清单字段、命令文件编写、after_tasks 等 Hooks 钩子配置,以及如何将扩展上架到社区目录(catalog),让任何人都能用一条命令安装你的扩展。
一、认识扩展:不用改核心就能加功能
Spec Kit 通过**扩展(Extension)**机制实现功能扩展:每个扩展是一个独立的小目录,包含一个 extension.yml 清单、若干个 Markdown 命令文件,以及可选的钩子和配置模板。扩展安装后会注册到项目里,AI 代理(如 Claude Code)即可调用形如 /speckit.你的扩展.命令名 的新命令。
核心好处:
- ✅ 核心保持轻量:不需要的功能不安装
- ✅ 独立版本管理:扩展可以单独发布、单独迭代
- ✅ 可分享:上架目录后,用户通过
specify-cn extension search即可发现并按名称安装
二、扩展目录结构:照着模板抄就行
官方已经内置了一份可复制的扩展模板,直接复制后改名就能开工:
cp -r extensions/template my-extension
cd my-extension
一个标准扩展的目录结构如下:
my-extension/
├── extension.yml # 必填:扩展清单(扩展的"身份证")
├── README.md # 必填:安装与使用说明
├── LICENSE # 必填:开源许可证(推荐 MIT)
├── CHANGELOG.md # 推荐:版本历史
├── config-template.yml # 可选:配置模板
└── commands/ # 扩展命令(Markdown 文件)
└── example.md
各文件的作用可对照模板了解:extensions/template/README.md、清单模板 extensions/template/extension.yml、示例命令 extensions/template/commands/example.md。
三、extension.yml 清单:逐字段速查
extension.yml 是扩展的"身份证",CLI 靠它完成校验、安装和注册。必填字段只有 4 个,其余按需添加:
| 字段 | 必填 | 说明 | 示例 |
|---|---|---|---|
schema_version |
✅ | 清单模式版本,固定写 "1.0" |
"1.0" |
extension.id |
✅ | 小写字母、数字、连字符,不能带下划线 | jira-sync |
extension.name |
✅ | 人类可读名称 | Jira Sync |
extension.version |
✅ | 语义化版本 X.Y.Z |
1.0.0 |
extension.description |
✅ | 一句话简介(建议 100 字符内) | 同步任务到 Jira |
requires.speckit_version |
✅ | 兼容的 Spec Kit 版本范围 | ">=0.1.0" |
provides.commands |
✅ | 至少 1 个命令 | 见下 |
hooks |
❌ | 集成钩子,见第五节 | — |
provides.config |
❌ | 配置文件模板 | — |
tags |
❌ | 目录搜索标签(推荐 2~5 个) | jira、issue-tracking |
命令命名必须遵循 speckit.{扩展id}.{命令名} 规则,例如扩展 id 是 my-ext,命令名就不能叫 hello,而要叫 speckit.my-ext.hello。一个最小可用的清单长这样:
schema_version: "1.0"
extension:
id: "my-ext"
name: "My Extension"
version: "1.0.0"
description: "My custom extension"
requires:
speckit_version: ">=0.1.0"
provides:
commands:
- name: "speckit.my-ext.hello"
file: "commands/hello.md"
description: "Say hello"
tags:
- "example"
完整的字段参考(含 requires.tools 外部依赖、defaults 默认配置、config_schema 等)请查阅官方文档:extensions/EXTENSION-DEVELOPMENT-GUIDE.md。
四、命令文件:一个 Markdown 就是 AI 能执行的命令
命令文件放在 commands/ 下,格式 = YAML frontmatter + Markdown 正文。frontmatter 里必须写 description,正文里用 $ARGUMENTS 占位符接收用户输入:
---
description: "Say hello command"
tools:
- 'some-tool/function' # 可选:命令用到的 MCP 工具
scripts:
sh: ../../scripts/bash/helper.sh # 可选:辅助脚本
---
# Hello Command
## User Input
$ARGUMENTS
## Steps
1. 向用户问好
2. 演示扩展工作正常
安装后,这个文件会被复制到 AI 代理的命令目录(如 Claude Code 的 .claude/commands/speckit.my-ext.hello.md),用户直接在对话框里输入 /speckit.my-ext.hello world 即可触发。
五、Hooks 钩子:让扩展"自动跑"
命令是用户手动触发的,而 Hooks(钩子) 让扩展能在核心命令执行完后自动介入,这是扩展最有价值的功能之一。目前可用的钩子点:
after_tasks:/speckit.tasks生成任务列表之后after_implement:/speckit.implement完成之后(规划中)
配置非常简单,在 extension.yml 中加一段:
hooks:
after_tasks:
command: "speckit.my-ext.check" # 必须是 provides.commands 里声明的命令
optional: true # true=执行前询问用户,false=自动执行
prompt: "运行检查命令?"
description: "任务生成后自动做合规检查"
典型玩法:生成任务后自动同步到 Jira、自动跑一次质量检查、自动打标签……社区目录里不少成熟扩展(如 jira、cleanup、plan-review-gate)都依赖 after_tasks 钩子实现工作流自动化,可以参考 extensions/catalog.community.json 里的真实条目。
六、本地测试扩展:一条命令搞定
开发过程中无需打包,用 --dev 指向本地目录即可在真实项目里验证:
# 在你的 Spec Kit 项目中(含 .specify/ 目录)
specify-cn extension add --dev /path/to/my-extension
specify-cn extension list # 应显示:✓ My Extension (v1.0.0)
specify-cn extension remove my-ext # 卸载
验证命令是否注册成功,可以看 AI 代理的命令目录是否出现了 speckit.my-ext.*.md 文件。常见的安装报错(如 Invalid extension ID、Command file not found)及修复方式,官方指南的"故障排除"一节都有对照表:extensions/EXTENSION-DEVELOPMENT-GUIDE.md。
七、上架目录:让你的扩展被全世界搜到
本地测试通过后,分两步发布:
第 1 步:打发布版本。 在扩展仓库中创建语义化版本标签(如 v1.0.0)并发布 Release,生成可下载的 ZIP 归档地址,例如:
https://<你的仓库平台>/<你的组织>/spec-kit-my-ext/archive/refs/tags/v1.0.0.zip
第 2 步:提交目录 PR。 Spec Kit 采用"双目录"机制:
- extensions/catalog.community.json:社区参考目录,你的扩展提交到这里
- extensions/catalog.json:CLI 的默认上游目录(上游为空,由组织自行策划)
具体操作:Fork 仓库 → 在 catalog.community.json 的 extensions 对象中按条目模式添加你的扩展(name、id、version、download_url、requires、provides、tags 等)→ 提交 Pull Request 等待维护者审查。目录条目的完整字段模式见 extensions/EXTENSION-PUBLISHING-GUIDE.md 的"附录:目录模式"。
提交前请过一遍官方检查清单:
- ✅ 有效的
extension.yml清单 - ✅ 包含安装和使用说明的 README
- ✅ 包含 LICENSE 文件
- ✅ 已创建带语义化版本号的 Release(如 v1.0.0)
- ✅ 在真实项目中测试过,所有命令可用
八、审查、验证与后续维护
PR 提交后,维护者会做格式与策略审查(通常 3~7 个工作日),通过后即可被 specify-cn extension search 搜到;通过更严格的功能、安全、质量审查后,扩展还会获得 verified: true 标记,出现在 specify-cn extension search --verified 结果中,获得更多信任与曝光。
后续版本更新流程:
- 更新
extension.yml中的version和CHANGELOG.md - 打新标签、发布新 Release
- 再提交一个 PR,更新目录条目中的
version、download_url和updated_at
总结:从 0 到 1 的路径图
| 步骤 | 动作 | 关键产出 |
|---|---|---|
| 1 | 复制 extensions/template/ 模板 | 扩展骨架目录 |
| 2 | 编写 extension.yml + 命令文件 |
可安装的最小扩展 |
| 3 | 配置 hooks.after_tasks(可选) |
自动化能力 |
| 4 | specify-cn extension add --dev 本地验证 |
测试通过的扩展 |
| 5 | 打 Release → PR 到 catalog.community.json |
目录上架 |
想深入学习,还可以阅读这些官方文档:
- 开发指南:extensions/EXTENSION-DEVELOPMENT-GUIDE.md
- 发布指南:extensions/EXTENSION-PUBLISHING-GUIDE.md
- API 参考:extensions/EXTENSION-API-REFERENCE.md
- 用户视角指南:extensions/EXTENSION-USER-GUIDE.md
- 设计背景:extensions/RFC-EXTENSION-SYSTEM.md
现在,复制模板、填好 extension.yml、跑通第一个 --dev 安装——你的 Spec Kit CN 扩展离上架只差一个 PR 的距离。🚀


