My Extension

Brief description of what your extension does and why it's useful.

标题使用扩展的人类可读名称（对应清单 [extension.yml](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/extensions/template/extension.yml?utm_source=gitcode_repo_files) 中 `extension.name` 字段，如 "My Extension"），紧跟一句"做什么 + 为什么有用"的简介。注意简介中不必重复 ID——ID（如 `my-extension`）是机器标识，遵循 `^[a-z0-9-]+$` 的小写短横线命名规则（见 [EXTENSION-DEVELOPMENT-GUIDE.md](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/extensions/EXTENSION-DEVELOPMENT-GUIDE.md?utm_source=gitcode_repo_files) 的 Validation Rules 一节），而 README 面向的是人。

### 2.2 Features（功能列表）

```markdown
## Features

- Feature 1: Description
- Feature 2: Description
- Feature 3: Description

示例采用"名称: 说明"的列表形式，列出 3 条左右的核心功能。这一节的价值在于让读者在进入安装步骤前 10 秒内判断该扩展是否值得引入。

2.3 Installation（安装）

示例给出了两条安装路径：

# Install from catalog
specify extension add my-extension

# Or install from local development directory
specify extension add --dev /path/to/my-extension

• 从目录（catalog）安装：适用于已发布到扩展目录的正式版本；
• --dev 本地安装：适用于开发阶段的本地目录调试，这也是 extensions/template/README.md 第 6 步"Test locally"所采用的方式（specify extension add --dev /path/to/my-extension）。

README 中把两种入口都写出来，既服务终端用户，也方便其他开发者做本地联调。

2.4 Configuration（配置）

示例将配置流程拆成三步，强调"从模板拷贝，而不是从零创建"：

1. 创建配置文件：

   cp .specify/extensions/my-extension/config-template.yml \
      .specify/extensions/my-extension/my-extension-config.yml
   

2. 编辑配置文件：

   vim .specify/extensions/my-extension/my-extension-config.yml
   

3. 填入必需值（示例中的占位 YAML）：

   connection:
     url: "https://api.example.com"
     api_key: "your-api-key"
   
   project:
     id: "your-project-id"
   

这与模板中的配置文件声明一一对应：extension.yml 的 provides.config 段声明了 my-extension-config.yml 及其模板来源 config-template.yml，并标记 required: true：

provides:
  config:
    - name: "my-extension-config.yml"
      template: "config-template.yml"
      description: "Extension configuration"
      required: true # Set to false if config is optional

而 config-template.yml 本身就是文档的"配置字典"：它用注释标出了每个键是否 REQUIRED（如 connection.url、connection.api_key、project.id）、可选项（如 project.workspace）、功能开关（features.enabled/auto_sync/verbose）、默认值示例（defaults.priority: "medium"）以及高级项（advanced.timeout: 30、retry_count: 3、cache_duration: 3600）。因此 README 的 Configuration 一节只需要引导用户完成"拷贝—编辑—填值"，详细键位说明交给模板文件与下一节的参考表即可，避免两处维护。

2.5 Usage（命令用法）

示例文档为每个命令建立独立小节，固定包含三要素：功能说明、调用方式、前置条件与输出：

### Command: example

Description of what this command does.

# In Claude Code
> /speckit.my-extension.example

**Prerequisites**:
- Prerequisite 1
- Prerequisite 2

**Output**:
- What this command produces
- Where results are saved

命令名 /speckit.my-extension.example 遵循命名空间规则 speckit.{extension-id}.{command-name}，与 extension.yml 中 provides.commands 的声明保持一致：

provides:
  commands:
    - name: "speckit.my-extension.example"
      file: "commands/example.md"
      description: "Example command that demonstrates functionality"
      aliases: ["speckit.my-extension.example-short"]

命令正文文件（commands/example.md）则用 $ARGUMENTS 占位符接收用户参数，并在文档中列出 Prerequisites（如 MCP server 已配置、配置文件存在、API 凭据有效）。README 与命令文件、清单三者之间形成"声明—文档—实现"的闭环，这也是官方在 Troubleshooting 一节建议"命令不可用先查安装状态"的底气所在。

2.6 Configuration Reference（配置参考表）

示例为每个配置段建立一张"设置 | 类型 | 是否必需 | 说明"表格：

### Connection Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| `connection.url` | string | Yes | API endpoint URL |
| `connection.api_key` | string | Yes | API authentication key |

### Project Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| `project.id` | string | Yes | Project identifier |
| `project.workspace` | string | No | Workspace or organization |

这张表与 config-template.yml 中 REQUIRED/OPTIONAL 注释完全对应，让读者无需打开模板即可确认必填项。写 README 时，建议直接从 config template 的注释反推这张表，保证两处一致。

2.7 Environment Variables（环境变量覆盖）

示例给出了覆盖连接的写法：

# Override connection settings
export SPECKIT_MY_EXTENSION_CONNECTION_URL="https://custom-api.com"
export SPECKIT_MY_EXTENSION_CONNECTION_API_KEY="custom-key"

命名模式为 SPECKIT_{扩展ID大写}_{SECTION}_{KEY}：扩展 ID 中的短横线替换为下划线，配置路径中的点号也替换为下划线（config-template.yml 末尾的注释也重复了这条规则）。

这一约定并非只是文档惯例，而是 Spec Kit CLI 的真实实现。在 src/specify_cli/extensions/init.py 的 _get_env_config 中可以看到：

ext_id_upper = self.extension_id.replace("-", "_").upper()
prefix = f"SPECKIT_{ext_id_upper}_"
# ...
remainder = key[len(prefix) :]
config_path = [p for p in remainder.lower().split("_") if p]

即 CLI 会扫描所有以 SPECKIT_MY_EXTENSION_ 开头的环境变量，把剩余部分按下划线拆分为配置路径并重建为嵌套字典（如 SPECKIT_MY_EXTENSION_CONNECTION_URL → {"connection": {"url": ...}}）。源码中还处理了一个容易踩坑的细节：当同时安装 git 和 git-hooks 两个扩展时，SPECKIT_GIT_HOOKS_URL 同时以两者的前缀开头，解析会把它归属给"更长的、更具体的"扩展 ID，避免配置串门（见 src/specify_cli/extensions/init.py 中关于 cross-extension prefix collision 的注释）。对扩展作者的启示是：扩展 ID 尽量不要成为其他扩展 ID 的前缀（如 git 与 git-hooks），否则 README 中声明的环境变量约定可能被同名前缀干扰。

2.8 Examples（示例工作流）

示例把扩展命令嵌入标准 Spec Kit 工作流，形成三步演示：

# Step 1: Create specification
> /speckit.spec

# Step 2: Generate tasks
> /speckit.tasks

# Step 3: Use extension
> /speckit.my-extension.example

这种写法展示了扩展与核心命令（specify → tasks）的衔接位置。若扩展注册了钩子（如 extension.yml 中 hooks.after_tasks 声明的 "Run example command?" 提示），README 的 Examples 一节就是解释"为什么执行完 /speckit.tasks 后会弹出提示"的最佳位置。

2.9 Troubleshooting（故障排查）

示例列出了两个最常见问题的处置路径：

• Configuration not found：按 Configuration 一节从模板重新拷贝配置文件；
• Command not available：三步排查——① specify extension list 确认扩展已安装；② 重启 AI agent；③ 重新安装扩展。

这套排查顺序与安装验证流程一致：extensions/template/README.md 的 Quick Start 同样以 specify extension add --dev 作为本地验证手段。对 AI agent 驱动的场景而言，"重启 agent"这一步尤为关键，因为命令文件是在扩展注册/安装时写入 agent 命令目录的，安装后不重启不会出现在会话中。

2.10 License、Support 与版本尾注

示例的结尾部分固定包含：

• License：声明 MIT（对应模板中的 LICENSE 文件，清单中 license: "MIT"）；
• Support：指向问题跟踪入口与 Spec Kit 主项目文档（示例中的占位 URL 需替换为自己的仓库地址）；
• Changelog：链接版本历史，示例中写作 [CHANGELOG.md](https://gitcode.com/GitHub_Trending/sp/spec-kit/blob/9f19be9cad6e83d8b293041d8dbb1b7787c3ed54/extensions/template/CHANGELOG.md?utm_source=gitcode_repo_files)——注意模板自带的 CHANGELOG.md 采用 Keep a Changelog 格式 + 语义化版本，并预留了 [Unreleased] 段落；
• 版本尾注：

*Extension Version: 1.0.0*
*Spec Kit: >=0.1.0*