SDD 基于规范编程实战：用 OpenSpec 与 SuperPowers 搭一套可复用的 Skill 骨架

1. 从「规范写在哪」到「规范能跑起来」SDD 落地的真实卡点SDDSpec-Driven Development规范驱动开发这两年被讨论得很多但真正落到团队里问题往往不是「要不要写规范」而是规范写完放在哪、谁来读、怎么变成可执行的动作。我见过不少团队把规范写在 Confluence 里结果开发不看、AI 也读不到最后规范变成一份没人维护的文档。OpenSpec 解决的是「规范怎么结构化定义」的问题SuperPowers 解决的是「能力怎么组织编排」的问题而 Skill核心是 SKILL.md解决的是「规范怎么沉淀成可被调用的能力」的问题。这三者串起来才是一套能跑通的 SDD 骨架。这篇文章聚焦一件事用 OpenSpec 定义规范、用 SuperPowers 组织能力围绕 SKILL.md 设计一套可复用的 Skill 骨架并完整演示一次「规范 → Skill 生成 → 校验」的动作。适合已经在用 Claude Code 或类似 Agent 工具、想把团队规范沉淀成可调用能力的开发者。读完之后你应该能自己搭出一个目录结构清晰、SKILL.md 配置规范、能被 Agent 正确触发的 Skill 骨架。需要说明的是Skill 的本质是「给 Agent 的入职指南」——它把通用型 Agent 变成特定领域的专业型 Agent。所以骨架设计的核心不是写多少文档而是让 Agent 在正确的时机加载正确的信息。下面从环境准备开始一步步搭起来。2. 前置准备TaoToken 接入与 OpenSpec / SuperPowers 环境在动手写 SKILL.md 之前先把调用链路打通。Skill 本身是静态文件但要验证它是否被正确触发、生成结果是否符合预期需要一个能稳定调用模型的入口。我这边用的是 TaoToken 的 API 来做验证它的接口兼容主流格式接入成本低适合在 Skill 开发阶段反复调试。2.1 获取 API Key 并配置环境变量先到控制台创建 API Key然后写进环境变量避免硬编码到脚本里export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 这类工具可以在其配置里指定 base_url 和 api_key指向上面的地址即可。注意 API 地址不带任何查询参数保持干净。2.2 安装 OpenSpec 与 SuperPowersOpenSpec 负责规范的结构化定义SuperPowers 负责能力的组织。两者都可以通过包管理器安装npm install -g openspec pip install superpowers安装完成后验证版本openspec --version superpowers --version如果命令找不到检查一下全局 bin 目录是否在 PATH 里。这一步踩过的坑通常是 Node 版本过低导致 openspec 安装失败建议 Node 18 以上。2.3 初始化项目骨架目录建一个干净的项目目录把规范、Skill、资源分开存放mkdir -p sdd-demo/{specs,skills,references,scripts,assets} cd sdd-demo openspec initopenspec init会生成一个基础的规范目录结构。到这里前置环境就绪接下来进入核心的 SKILL.md 骨架设计。3. 可复用 Skill 骨架目录结构与 SKILL.md 配置Skill 的目录结构决定了它的可维护性。一个规范的 Skill 应该只包含 Agent 执行任务真正需要的东西多余的 README、安装指南、变更日志只会造成干扰。下面是推荐的骨架结构。3.1 目录结构设计skill-name/ ├── SKILL.md (必需) │ ├── YAML frontmatter (必需) │ │ ├── name: (必需) │ │ └── description: (必需) │ └── Markdown 正文 (必需) └── 捆绑资源 (可选) ├── scripts/ 可执行代码 (Python/Bash) ├── references/ 按需加载的文档 └── assets/ 输出用文件 (模板/图标/字体)这个结构的关键在于「渐进式展开」元数据name description始终在上下文里约 100 字SKILL.md 正文只在技能触发时加载控制在 500 行以内捆绑资源按需加载脚本甚至可以不读入上下文直接执行。三级加载系统让上下文窗口这个公共资源被高效利用。3.2 SKILL.md 的 YAML frontmatter 配置frontmatter 是 Agent 判断「何时使用这个技能」的唯一依据所以 description 必须写清楚功能和使用场景。下面是一个规范生成类 Skill 的配置骨架--- name: spec-to-skill description: 将 OpenSpec 规范文件转换为可调用的 Skill 骨架。当用户需要把规范沉淀为 Agent 能力、生成 SKILL.md 模板、或校验 Skill 结构是否符合规范时使用。支持从 specs/ 目录读取规范、生成对应 Skill 目录、并执行结构校验。 ---注意这里只放 name 和 description 两个字段不要加 version、author 之类的额外字段。所有「何时使用」的信息都放在 description 里因为正文只在触发后才加载写在正文里的触发条件对 Agent 没有帮助。3.3 正文的写作准则正文用祈使句/不定式直接告诉 Agent 怎么做。核心原则是「简洁至上」——Claude 本身已经很聪明只添加它不知道的内容。对每条信息都要问这段内容的 token 成本值得吗正文里应该包含核心工作流、选择指引、以及指向 references/ 的引用说明。详细的架构图、示例、配置变体都移到参考文件里。如果某个参考文件很大超过 1 万字在 SKILL.md 里加上 grep 搜索模式方便 Agent 定位。4. 实战从 OpenSpec 规范生成 Skill 并校验前面搭好了骨架现在演示一次完整的「规范 → Skill 生成 → 校验」动作。这个流程本身就是 SDD 的缩影规范是源头Skill 是产物校验是质量门。4.1 用 OpenSpec 定义一条规范先在 specs/ 目录下写一条规范。OpenSpec 的规范文件通常是结构化的 YAML 或 Markdown描述一个能力的输入、输出和约束# specs/pdf-rotate.yaml name: pdf-rotate intent: 旋转 PDF 页面 inputs: - file: PDF 文件路径 - angle: 旋转角度 (90/180/270) outputs: - rotated_file: 旋转后的 PDF 路径 constraints: - 保持原始分辨率 - 不修改其他页面 examples: - 把 report.pdf 顺时针旋转 90 度 - 旋转这个 PDF 的每一页 180 度这条规范定义了「旋转 PDF」这个能力的完整契约。接下来把它转成 Skill。4.2 生成 Skill 目录与 SKILL.md用前面配置的 spec-to-skill 能力或者手动按骨架生成。手动生成时先建目录mkdir -p skills/pdf-rotate/{scripts,references,assets}然后写 SKILL.md--- name: pdf-rotate description: 旋转 PDF 页面并保持原始分辨率。当用户需要旋转 PDF、调整页面方向、或批量处理 PDF 页面角度时使用。支持 90/180/270 度旋转不修改其他页面内容。 --- # PDF 旋转 ## 工作流 1. 确认输入文件路径和旋转角度 2. 运行 scripts/rotate_pdf.py 执行旋转 3. 校验输出文件的分辨率与页数 ## 脚本 运行 scripts/rotate_pdf.py file angle 完成旋转。 脚本参数固定不要修改旋转逻辑除非用户明确要求。 ## 参考 需要了解 PDF 处理库的细节时查阅 references/pdf-lib.md。对应的脚本放在 scripts/rotate_pdf.pyimport sys from pypdf import PdfReader, PdfWriter def rotate(input_path, angle): reader PdfReader(input_path) writer PdfWriter() for page in reader.pages: page.rotate(int(angle)) writer.add_page(page) output_path input_path.replace(.pdf, f_rotated_{angle}.pdf) with open(output_path, wb) as f: writer.write(f) return output_path if __name__ __main__: result rotate(sys.argv[1], sys.argv[2]) print(f生成: {result})4.3 校验 Skill 结构生成之后要校验结构是否符合规范。写一个简单的校验脚本检查必需文件和 frontmatter 字段#!/bin/bash SKILL_DIR$1 test -f $SKILL_DIR/SKILL.md || { echo 缺少 SKILL.md; exit 1; } grep -q ^name: $SKILL_DIR/SKILL.md || { echo 缺少 name; exit 1; } grep -q ^description: $SKILL_DIR/SKILL.md || { echo 缺少 description; exit 1; } echo 校验通过: $SKILL_DIR运行校验chmod x scripts/validate_skill.sh ./scripts/validate_skill.sh skills/pdf-rotate输出校验通过: skills/pdf-rotate就说明骨架结构没问题。这一步是 SDD 里「规范到能力」的质量门建议纳入 CI。5. 本篇常见错排查实际搭这套骨架时报错集中在几个地方这里逐个说清楚。SKILL.md 未被触发最常见的原因是 description 写得太笼统比如只写「处理 PDF」。Agent 判断是否加载技能完全依赖 description所以要写清楚功能 使用时机 触发条件。改成「旋转 PDF 页面并保持原始分辨率当用户需要旋转 PDF 或调整页面方向时使用」就能被正确识别。frontmatter 解析失败YAML 格式对缩进敏感name:和description:后面要有空格冒号不能漏。如果 description 里包含冒号要用引号包起来否则 YAML 解析会报错。脚本执行报错scripts/rotate_pdf.py依赖 pypdf先pip install pypdf。另外脚本参数要固定不要设计成需要 Agent 临时拼参数的形式容易出错的任务应该用低自由度的脚本封装。上下文膨胀如果 SKILL.md 超过 500 行说明内容该拆分了。把详细示例、配置变体移到 references/正文只保留核心工作流和选择指引。信息只放一处不要 SKILL.md 和参考文件里重复。校验脚本找不到文件确认执行时的工作目录或者用绝对路径。validate_skill.sh里的$SKILL_DIR如果是相对路径要在项目根目录执行。6. 把规范沉淀成能力下一步怎么走骨架搭起来之后真正的工作是持续迭代。Skill 不是一次写完就完事的它需要基于实际使用反馈不断调整。建议的做法是每次 Agent 触发技能后观察它是否加载了正确的参考文件、是否按预期执行了脚本把不符合预期的案例记下来反过来优化 description 和正文。如果你想把这条链路跑得更顺可以到模型对话页面直接测试 Skill 的触发效果观察 Agent 在不同 prompt 下是否加载了正确的技能。需要长期做编码和 Agent 编排的团队Coding Plan 会更适合能覆盖多轮调试和批量生成 Skill 的场景。接入过程中遇到 API 调用问题先到 API Keys 页面确认 key 状态再对照接入文档检查 base_url 和请求格式。规范定义、能力组织、Skill 生成这三步串起来SDD 才算真正落地而不是停留在文档层面。