SDD 规范编程实战：OpenSpec 与 SuperPowers 的 Skill 配置骨架

1. 为什么 SDD 规范编程需要先解决 Skill 配置问题SDDSpecification-Driven Development规范驱动开发的核心思路是先把需求写成可执行的规范再让 AI 按规范产出代码。落到 OpenSpec 与 SuperPowers 这类工具链上规范不再是散落在对话里的提示词而是被封装成一个个 Skill由 AI 编程工具在合适的时机自动加载。问题也随之而来Skill 本身要调用模型模型请求要经过统一的通道而通道配置一旦散落在每个 Skill 的 settings.json 或 config.toml 里就会出现同一个项目里三个 Skill 走三条通道的混乱局面。我见过最常见的翻车场景是这样的你在 OpenSpec 里定义了一个spec-writerSkill 负责生成规范文档又在 SuperPowers 里挂了一个code-reviewerSkill 负责审查实现两个 Skill 各自维护一份模型配置。某天你换了模型或调整了参数只改了其中一个另一个还在用旧配置于是规范文档和代码审查的结论开始对不上。SDD 强调规范即事实来源可配置本身却成了事实来源之外的黑盒这显然违背了规范编程的初衷。所以这篇内容要解决的不是怎么写一个 Skill而是怎么让 OpenSpec 与 SuperPowers 的 Skill 共享同一套可复制的通道配置骨架。适合谁看正在用 AI 编程工具做规范驱动开发、需要把模型调用统一收口到 TaoToken 的开发者。读完你能拿到两份可直接复制的配置文件骨架以及一套逐步验证调用是否生效的动作清单。下面所有配置都以 TaoToken 作为统一通道来演示官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。2. TaoToken 前置把通道配置从 Skill 里抽出来在动手改 Skill 之前先把一个概念理清楚Skill 是能力封装通道是能力出口。OpenSpec 的 Skill 负责把规范拆解成任务SuperPowers 的 Skill 负责把任务映射到具体工具调用但它们最终都要发一次模型请求。如果每个 Skill 各自持有 API Key 和 base_url你就失去了统一观测和统一切换的能力。TaoToken 在这里扮演的角色是统一出口所有 Skill 的模型请求都指向同一个 API 基址Key 只在环境变量或顶层配置里出现一次。这样做的好处很直接——换模型只改一处加 Skill 不用重复填 Key排查问题时也能在一个地方看请求日志。你需要先准备两样东西一个可用的 API Key以及确认你的工具链支持自定义 base_url。Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建时建议按用途命名比如sdd-openspec和sdd-superpowers分开方便后续按 Skill 维度做额度隔离。注意不要把 Key 硬编码进 SKILL.md 或提交到 Git 仓库。Skill 文件通常会被工具链读取并可能被其他协作者看到Key 应该放在环境变量或本地未跟踪的配置文件里。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面列出了兼容的请求格式和参数说明。如果你用的是 Claude Code 这类工具Anthropic 兼容接入的说明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 配置方式与下面要讲的骨架基本一致只是字段名不同。3. 可复制配置settings.json 与 config.toml 骨架这一节给两份骨架。第一份是 OpenSpec 侧常用的settings.json第二份是 SuperPowers 侧常用的config.toml。两份都遵循同一个原则通道信息集中在顶层Skill 只引用不重复定义。3.1 OpenSpec 侧 settings.json 骨架OpenSpec 的 Skill 配置通常放在项目根目录的.openspec/下或者用户级的配置目录里。下面这份骨架把通道配置放在provider节点Skill 通过providerRef引用它。{ provider: { name: taotoken, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: claude-sonnet-4-20250514, timeoutMs: 60000, maxRetries: 2 }, skills: { spec-writer: { providerRef: taotoken, model: claude-sonnet-4-20250514, temperature: 0.2, systemPromptFile: ./prompts/spec-writer.md }, task-decomposer: { providerRef: taotoken, model: claude-sonnet-4-20250514, temperature: 0.1 } } }几个字段值得说明。apiKeyEnv指向环境变量名而不是 Key 本身这样配置文件可以安全提交。providerRef让每个 Skill 显式声明自己走哪个通道将来要加第二个通道比如本地模型时只需在provider下新增一个节点Skill 改一行引用即可。temperature在规范生成类 Skill 里建议压低0.1 到 0.2 之间能让输出更稳定符合 SDD 对确定性的要求。3.2 SuperPowers 侧 config.toml 骨架SuperPowers 的配置习惯用 TOML结构上可以和上面保持一致。下面这份骨架把通道放在[providers.taotoken]Skill 放在[[skills]]数组里。[providers.taotoken] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY default_model claude-sonnet-4-20250514 timeout_ms 60000 max_retries 2 [[skills]] name code-reviewer provider taotoken model claude-sonnet-4-20250514 temperature 0.0 system_prompt_file ./prompts/code-reviewer.md [[skills]] name test-generator provider taotoken model claude-sonnet-4-20250514 temperature 0.3temperature 0.0用在代码审查上是有意为之审查结论需要可复现同样的代码两次审查不应该给出矛盾的判断。测试生成可以稍微放开到 0.3让它在用例设计上有一点发散空间。3.3 环境变量与目录结构两份配置都依赖TAOTOKEN_API_KEY这个环境变量。在项目根目录建一个.env文件记得加进.gitignore内容只有一行TAOTOKEN_API_KEYsk-你的实际Key然后在启动工具链前加载它。如果你用的是 shell可以这样export $(grep -v ^# .env | xargs)推荐的目录结构如下让配置、提示词、Skill 定义各归其位project/ ├── .openspec/ │ └── settings.json ├── .superpowers/ │ └── config.toml ├── prompts/ │ ├── spec-writer.md │ ├── code-reviewer.md │ └── test-generator.md ├── skills/ │ ├── spec-writer/ │ │ └── SKILL.md │ └── code-reviewer/ │ └── SKILL.md └── .envSKILL.md 里只写这个 Skill 做什么、什么时候触发通道和模型参数全部留在 settings.json 和 config.toml 里。这样职责清晰改能力改 SKILL.md改通道改配置文件两者互不干扰。4. 验证请求确认 Skill 调用真的生效配置写完不代表生效。这一节给一套逐步验证动作从最小请求开始逐层确认通道、Skill、参数都按预期工作。4.1 第一步直接验证通道连通性先绕开 Skill直接用 curl 打一次 API确认 Key 和 base_url 没问题。curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [ {role: user, content: 只回复两个字连通} ] }如果返回里能看到content字段且文本是连通说明通道本身没问题。如果返回 401检查 Key 是否加载正确返回 404检查 base_url 是否漏了/api或多了斜杠。4.2 第二步验证 OpenSpec Skill 加载在 OpenSpec 里触发spec-writerSkill让它生成一段最小规范。你可以准备一个input.md内容是一句需求描述然后运行openspec run spec-writer --input ./input.md --output ./spec-out.md运行后检查两件事spec-out.md是否生成以及 OpenSpec 的日志里是否出现指向https://taotoken.net/api的请求记录。如果 Skill 没触发多半是 SKILL.md 的description写得不够具体工具链判断不出该在什么时候加载它。4.3 第三步验证 SuperPowers Skill 与参数生效SuperPowers 侧用code-reviewer做验证。准备一个故意有问题的代码文件比如一个没有边界检查的数组访问然后运行superpowers run code-reviewer --target ./src/buggy.js预期结果是审查意见里明确指出越界风险。如果它没提可能是temperature没生效或模型没按配置走。你可以在 SuperPowers 的调试日志里确认实际使用的 model 和 temperature 是否与 config.toml 一致。4.4 第四步交叉验证两个 Skill 走同一通道最后一步是确认 OpenSpec 和 SuperPowers 的 Skill 确实共享同一个通道。方法很简单在 TaoToken 控制台的请求记录里看这两次调用是否都出现在同一个 Key 或同一个项目下。如果它们分属不同 Key说明你的providerRef或provider字段没对齐需要回到配置文件检查引用名是否拼写一致。5. 本篇常见错排查配置类问题往往不是能不能跑而是跑得对不对。下面这几个坑是我在实际项目里反复遇到的按出现频率排序。5.1 Skill 不触发description 写成了功能说明最常见的错误是把 SKILL.md 的description写成这个 Skill 用于生成规范文档这是功能描述不是触发条件。工具链判断是否加载 Skill靠的是用户说了什么话、当前处于什么任务阶段。正确的写法应该包含触发场景比如当用户要求把需求拆解为可执行规范或当前任务处于规范编写阶段时使用。5.2 配置不生效环境变量没加载apiKeyEnv指向的变量在运行时不存在是最隐蔽的问题。表现是请求返回 401但你明明在.env里写了 Key。原因是工具链启动时没有加载.env。解决办法是在启动脚本里显式 source或者用工具链自带的 env 加载选项。验证方法是先echo $TAOTOKEN_API_KEY确认输出非空再启动。5.3 模型参数被覆盖Skill 级配置优先级搞反有些工具链里Skill 级的model会覆盖 provider 级的defaultModel有些则相反。如果你在 provider 里设了 A 模型在 Skill 里设了 B 模型实际用的是哪个取决于工具链的合并策略。稳妥做法是provider 里只放通道信息模型和温度全部在 Skill 级显式声明避免依赖隐式优先级。5.4 base_url 拼接错误多写或少写路径段https://taotoken.net/api和https://taotoken.net/api/在多数客户端里等价但https://taotoken.net/api/v1和https://taotoken.net/api不等价。前者会让客户端再拼一次/v1变成/api/v1/v1/messages直接 404。配置时只写到/api路径段交给客户端处理。5.5 超时与重试长规范生成被截断规范生成类 Skill 的输出往往较长默认 30 秒超时容易触发截断。把timeoutMs提到 60000 或更高maxRetries设 2 次。但要注意重试会带来重复计费所以只在超时和 5xx 错误上重试不要在 4xx 上重试。提示排查时优先看工具链的调试日志而不是猜。日志里会显示实际请求的 URL、model 和耗时比对着配置文件看快得多。6. 把配置收口之后SDD 才真正可复现回到开头那个问题SDD 强调规范即事实来源而配置是规范得以执行的前提。当 OpenSpec 和 SuperPowers 的 Skill 共享同一份通道骨架你换模型、调参数、加 Skill 都只动一处规范编程的确定性才从文档层面延伸到执行层面。如果你还在逐个 Skill 填 Key 的阶段建议先从 API Keys 页面建一个专用 Key再按第 3 节的骨架把配置收口。接入过程中遇到字段对不上或请求报错接入文档里有完整的参数对照表。需要长期跑编码和 Agent 任务的可以看 Coding Plan 的说明它针对高频调用场景做了额度规划。想先确认模型输出是否符合预期模型对话页面可以直接试。配置这件事一次收口后面每个 Skill 都省心。