- 人工智能
- AI Agent
- 代码智能体
- Agent 编排
- CLI
- AI 应用
【免费下载链接】gsd-2
A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture
导读
GSD（GitHub 加速计划 / gsd-2）内置的spike-wrap-up技能解决了一个真实痛点：一次性的技术调研（spike）产出了高质量结论，却往往在完成后被遗忘。本指南完整拆解该技能的工作流——读取.gsd/workflows/spikes/下的研究产物，与用户确认可复用价值，然后写入.claude/skills/<name>/SKILL.md，让下次同类任务触发时 Agent 自动加载。读完本文，你将掌握 GSD 技能发现机制的底层原理、六步打包流程、技能文件的最小规范结构，以及一套可复用的"研究→资本"沉淀方法。
一、背景：spike 产出什么，又为什么需要打包
GSD 的 spike 工作流定义在 src/resources/extensions/gsd/workflow-templates/spike.md，其核心定位是：
Investigate a question, evaluate options, prototype if needed, and produce a clear recommendation. No production code is shipped — the output is knowledge.
它面向技术评估、架构决策、"我们应该用 X 吗？"这类问题，分为三个阶段：
| 阶段 | 目标 | 产出物 |
|---|---|---|
| Phase 1: scope | 明确问题与成功标准 | 在 artifact 目录写入SCOPE.md |
| Phase 2: research | 从多个角度深入调研 | research/ANGLE-1.md、research/ANGLE-2.md等 |
| Phase 3: synthesize | 汇总证据给出推荐 | RECOMMENDATION.md（含执行摘要、对比矩阵、推荐理由、后续步骤） |
这些文档统一落在.gsd/workflows/spikes/<slug>/目录下。正如spike-wrap-up技能文档所指出的："Those documents are useful once and then forgotten unless something packages them for reuse."——文档被用一次就遗忘，除非有人把它们打包复用。
在 spike 工作流的 Phase 3 末尾，模板明确给出两条分流路径（workflow-templates/spike.md）：
- 若调研结论对未来工作有可复用指导价值，运行
spike-wrap-up技能，打包为.claude/skills/<name>/SKILL.md，后续通过skill-discovery.ts自动加载； - 若只是一次性决策（没有可复用指导），则建议在
.gsd/DECISIONS.md追加一行记录即可。
这就是spike-wrap-up的使命：它是一座桥，把"spike 已完成"变成"技能已可用"，也是 GSD v1 中/gsd-spike-wrap-up命令在该版本中的对应物。
二、核心原则：打包前必须理解的三个约束
spike-wrap-up的<core_principle>定义了三条不可妥协的准则，是整套流程的"宪法"：
不是每个 spike 都值得做成技能（NOT EVERY SPIKE DESERVES A SKILL）如果调研结论是"不要做 X"，那可能没有任何可复用的指导价值。必须先问用户，答案是否定就直接退出、不写任何文件。
项目本地，而非用户全局（PROJECT-LOCAL, NOT USER-GLOBAL）写入仓库内的
.claude/skills/，而不是~/.claude/skills/。技能编码的是项目特定的选择，不应泄漏到无关项目中。description 是可发现性信号（DESCRIPTION IS THE DISCOVERABILITY SIGNAL）frontmatter 中的
description字段是 Agent 判断相关性与是否加载技能的首要信号——它是启发式匹配，不是确定性触发。要用未来 Agent 很可能遇到的关键词来写，而不是写一段摘要。
第三条原则直接决定了技能的"曝光率"，后文会在源码层面印证它的重要程度。
三、Step 1：找到要打包的 spike
流程的第一步是定位研究产物：
- 列出
.gsd/workflows/spikes/下的所有目录，按修改时间（mtime）排序，最新在前； - 若存在多个 spike，询问用户要打包哪一个；默认取最近的一个；
- 若一个都不存在，告知用户并停止——该技能必须基于一个已完成的 spike。
找到目录后，读取三份核心文件：
<spike>/SCOPE.md—— 当初提出的问题<spike>/research/*.md—— 被调查的各角度<spike>/RECOMMENDATION.md—— 最终结论
这三份文件共同构成了技能的内容素材来源。
四、Step 2：判断它是否值得变成技能
技能要求只做一轮用户访谈，问两个问题：
结论对未来工作可复用，还是只针对某一次决策？若发现包含可复用的指导（"如何评估 X"、"一个值得遵循的模式"、"某库的坑"），打包是值得的；若 spike 止步于"我们选了库 Y，没有然后"，它更适合放进
.gsd/DECISIONS.md而非做成技能。触发时机是什么？未来 Agent 应在什么情况下加载这个技能？给出具体关键词，例如"新增一个 webhook handler""写一条 SQL migration"。
如果用户认为不值得打包，则改为建议把摘要追加到.gsd/DECISIONS.md并停止。
.gsd/DECISIONS.md在 GSD 中有明确的格式约束，其模板见 src/resources/extensions/gsd/templates/decisions.md：
Append-only. Never edit or remove existing rows. To reverse a decision, add a new row that supersedes it. Read this file at the start of any planning or research phase.
该文件是一个只追加、不可编辑已有行的决策登记表（含序号、时间、范围、决策、选择、理由、可否修订、决策人各列），因此技能流程中"追加一行"的操作是安全且符合规范的。
五、Step 3：设计技能——先草稿后反馈
在动笔写文件之前，先在对话中完成技能设计草图，包含六个要素：
- 名称（Name）：kebab-case，简短无歧义。必要时以项目领域作前缀，例如
auth-webhook-setup优于webhook； - description（frontmatter）：一句话，120–1024 字符，富含关键词，必须说清"Agent 何时应加载它"；定稿前至少重写两遍；
- Objective：一段话，说明技能做什么、产出什么工件；
- Process：编号步骤。可以引用 spike 的发现作为来源，但技能本身必须不依赖重读 spike 就能执行；
- Anti-patterns：spike 暴露出的坑——那些看似正确却行不通的做法；
- Success criteria：技能使用者可以对照核验的清单。
把草图展示给用户，进行一轮反馈，迭代后再进入写作。这保证了打包的不是 Agent 的自嗨，而是用户真正认可的可复用知识。
六、Step 4：编写技能文件——最小规范结构
将技能写入.claude/skills/<name>/SKILL.md（目录不存在则创建），并匹配 GSD 内建技能采用的frontmatter + XML 标签结构。技能的规范范本（canonical shape）参见 src/resources/skills/review/SKILL.md。
技能文档给出的最小结构如下（可直接复制使用）：
--- name: <skill-name> description: <one sentence with trigger keywords> --- <objective> <one paragraph — what this skill does> </objective> <context> <when to invoke, what produced it (cite the spike), assumptions> </context> <process> ## Step 1: <action> <instructions> ## Step 2: <action> <instructions> </process> <anti_patterns> - <gotcha from the spike> - <another gotcha> </anti_patterns> <success_criteria> - [ ] <observable confirmation> - [ ] <observable confirmation> </success_criteria>若 spike 产出了可复用的模板（如配置文件、启动脚本），将它们复制进.claude/skills/<name>/templates/或.claude/skills/<name>/references/，并在技能正文中引用。
关于结构约定，仓库中另一个技能 src/resources/skills/create-skill/SKILL.md 给出了进一步的印证：frontmatter 必填name（小写连字符，与目录同名）和description（"做什么 + 何时用"、第三人称），复杂技能可采用 router 模式（SKILL.md+workflows/+references/+templates/+scripts/五个目录分工），并建议SKILL.md 控制在 500 行以内、正文使用纯 XML 语义标签而不用 markdown 标题。
七、Step 5：归档 spike，并从技能中建立溯源链接
打包完成后需要做三件事：
- 在新 SKILL.md 中引用来源 spike："Derived from
.gsd/workflows/spikes/<slug>/RECOMMENDATION.md(dated YYYY-MM-DD)."； - 不要删除 spike 目录——spike 是研究工件，对事后取证（forensics）仍有价值；
- 在
.gsd/DECISIONS.md追加一行：- YYYY-MM-DD [spike]: packaged "<slug>" findings as skill <name>。
这一步骤把"技能、研究产物、决策记录"三者串成一条可追溯的链，既保证技能可独立执行，又保留了完整的研究证据。
八、Step 6：确认技能被拾取——源码层的自动发现机制
打包的最后一步是确认技能会在下次会话被自动发现。这背后是 GSD 的技能发现机制，实现在 src/resources/extensions/gsd/skill-discovery.ts。关键实现事实如下：
1. 技能目录：同时监视两个位置（用户级）——
const SKILLS_DIR = join(homedir(), ".agents", "skills"); const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");即~/.agents/skills/（skills.sh 生态目录）与~/.claude/skills/（Claude Code 官方目录），两者都按"目录名 / SKILL.md"的结构解析。
2. 快照对比发现新技能：auto-mode 启动时调用snapshotSkills()记录基线，之后detectNewSkills()对比当前目录与基线，找出新增技能目录，并通过parseSkillFrontmatter()读取 frontmatter 中的name与description。
3. description 是匹配依据：parseSkillFrontmatter用正则提取name:和description:两行，新技能最终以<newly_discovered_skills>XML 块的形式注入系统提示词，并明确指示：当任务匹配其 description 时，用 read 工具加载该技能文件。这正是前面核心原则第三条"description 是可发现性信号"的源码级落地——description 写得越贴合未来任务关键词，被命中的概率越高。
4. 触发注册：spike-wrap-up本身也被注册为系统上下文中的技能触发器，见 src/resources/extensions/gsd/bootstrap/system-context.ts：
{ trigger: "Package spike findings into a reusable project-local skill at .claude/skills/", skill: "spike-wrap-up" }并且它位列 GSD 捆绑技能清单（src/resources/extensions/gsd/tests/bundled-skill-triggers.test.ts），受到测试守护。
完成打包后，告知用户：技能将在下一次会话通过skill-discovery.ts被自动呈现；如果想立即使用，可以直接Read .claude/skills/<name>/SKILL.md。
九、反模式清单：打包过程中最容易犯的五个错误
<anti_patterns>给出了五个经过实战总结的坑：
- 写入
~/.claude/skills/—— 那是用户全局目录。项目 spike 产出项目技能，必须保持作用域隔离； - 冗长的 frontmatter description—— description 是索引条目，不是教程。关键词优先于散文；
- 每个 spike 都打包—— 若结论只是"一次性定了 X"，追加到 DECISIONS.md 就够了；
- 把 spike 原样复制进技能—— spike 是研究，技能是可执行指导，必须重新撰写（re-author）；
- 删除源 spike 目录—— 研究工件应当持久保留。
这五条与核心原则一一呼应，尤其第 4 条提醒了"研究文档"与"可执行技能"在文体上的本质差异。
十、成功标准：如何判断一次打包真正完成
技能定义了一份可核验的检查清单（<success_criteria>）：
- 新
.claude/skills/<name>/SKILL.md存在，且 frontmatter 格式良好； description字段使用能匹配未来 Agent 工作的关键词；- 技能正文可独立执行，无需重读来源 spike；
- 技能中引用了来源 spike；
.gsd/DECISIONS.md中有一行记录本次打包；- spike 目录本身保持原样未动。
这六条同时覆盖了"产物正确性、可发现性、独立性、可追溯性、记录完整性和证据保留"六个维度，可作为任何一次 spike 打包的验收基准。
结语：从"一次性研究"到"持久资本"
spike-wrap-up揭示的是一套完整的知识沉淀方法论：spike 工作流负责产出知识（workflow-templates/spike.md），本技能负责包装知识（六步流程 + 最小结构模板），skill-discovery.ts负责分发知识（快照对比 + frontmatter 解析 + 系统提示注入），而.gsd/DECISIONS.md负责记录知识。四者环环相扣，让一次调研的结论真正变成下次同类任务的自动加载能力——这就是 GSD 中"throwaway spikes become durable capital"（一次性 spike 变成持久资本）的完整落地路径。
- 人工智能
- AI Agent
- 代码智能体
- Agent 编排
- CLI
- AI 应用
【免费下载链接】gsd-2
A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture
相关推荐
plannotator Guide Provider 模式落地：以 Code Tour 为模板的端到端 SPIKE 研究
plannotator Guide Provider 模式落地：以 Code Tour 为模板的端到端 SPIKE 研究 导读 本文基于 plannotator
ECC 项目专属 Skill 模板实战：用 project-guidelines-template 为单一项目沉淀开发指南
ECC 项目专属 Skill 模板实战：用 project guidelines template 为单一项目沉淀开发指南 导读 本文以 ECC 仓库中的 pr
人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具WeChatFerry 快速上手指南：如何搭建一个免费开源的微信自动化机器人
WeChatFerry 快速上手指南：如何搭建一个免费开源的微信自动化机器人 每天被不同的人问同一类问题，或者手动往十几个群里挨个发通知，这样的重复劳动你大概都
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
