技能

OpenSpec 的每一项技能：参数、创建内容及其响应内容。

技能分为两个集合：

• 核心：默认安装，主规划循环。
• 可选：仅在添加时安装，通过 配置文件。

每项技能都期望一个已在使用 OpenSpec 的项目。在其首个写入步骤之前，技能会检查已解析的根目录。当没有根目录时会发生什么取决于技能的到达方式：

• 自动选择：你的代理自行选择了该技能，没有你指定 OpenSpec。它会放弃 OpenSpec 并正常回答你的请求，就像未安装 OpenSpec 时一样。
• 显式 OpenSpec 请求：你指定了 OpenSpec、指定了该技能或运行了其命令。它会在写入前停止并询问如何继续：在此处运行 openspec init、使用 --store <id> 指向存储库，或在不使用 OpenSpec 的情况下继续。它会等待你的回答。

命令始终是第二种情况。项目的 openspec/config.yaml 指定了本机无法解析的存储库（未注册或格式错误的 store: 行）时，不会被视为未初始化：技能会停止并显示存储库错误及其修复方法。两种情况下都不会有技能自行创建 openspec/ 目录。以下条目描述每项技能在根目录就位后的行为。

技能	职责	类型
openspec-explore	在想法成为变更提案之前进行思考	核心
openspec-propose	一步创建包含所有规划工件的变更提案	核心
openspec-apply-change	实施变更提案的任务	核心
openspec-update-change	修订变更提案的计划	核心
openspec-sync-specs	将变更提案的规范更新合并到 specs/	核心
openspec-archive-change	将已完成的变更提案移至归档	核心
openspec-new-change	以空脚手架启动变更提案	可选
openspec-continue-change	一次创建一个规划工件	可选
openspec-ff-change	一次性创建实施所需的每个工件的变更提案	可选
openspec-verify-change	检查实施是否与计划匹配	可选
openspec-bulk-archive-change	一次归档多个变更提案	可选
openspec-onboard	通过端到端完成一个真实变更提案来学习工作流	可选

以下每个条目都指明负责下一步的技能。当你的配置文件不包含该技能时，已安装的文件永远不会提及它：交接变为等效的 openspec 命令或对你的直接请求，仅用于指向缺失技能的那行不会被写入。因此你拥有的技能总是会交接给你拥有的其他技能。获取哪个集合由 配置文件 决定。

openspec-explore

在想法成为变更提案之前，先深入思考。

契约	描述
参数	一个主题：一个想法、一个问题、一个对比，或现有变更提案的名称，用于在上下文中探索。如果未提供任何内容，则进入探索模式。
创建	默认不创建任何内容。它只读取和调查。根据请求，它捕获洞察：在 openspec/changes/<name>/ 下创建新的变更提案，或更新现有提案的提案、设计、规格或任务。绝不编写代码。
响应	一场没有必需输出的开放对话。当思考逐渐清晰时，它会总结问题、方法、待解决问题和后续步骤，并提供捕获它们的选择。由你决定。实现绝不在此开始。

openspec-propose

创建变更提案并一步生成其所有规划工件。

契约	描述
参数	kebab-case 格式的名称（add-dark-mode）或一段简单的描述。如果两者都未提供则会询问。
创建	openspec/changes/<name>/ 及 schema 定义的每个工件，按依赖顺序排列（规格驱动：提案、规格增量、设计、任务）。绝不编写代码。
响应	已创建的工件，已准备好供审查，以及下一步。到此为止；实现等待 openspec-apply-change。

openspec-apply-change

实现变更提案的任务，逐项处理列表直到完成或受阻。

契约	描述
参数	变更提案名称（add-auth），可选。如果目标不明确，它会列出活跃的变更提案并请你选择。
创建	代码：每个任务所需的最小变更，写入你的项目文件中。在变更提案中，它在由 sourcePath 和从 1 开始的 line 标识的跟踪文件中勾选每个已完成的任务（- [ ] 到 - [x]）。一个 schema 可以跨多个文件跟踪任务。
响应	每个任务的进度，然后是总体计数（N/M 个任务已完成）。全部完成：建议 openspec-archive-change。因缺少工件而受阻：指向 openspec-continue-change，或当该 skill 未安装时指向 openspec status 和 openspec instructions（核心 profile 不包含它）。任务不明确或出现错误：暂停并询问。

openspec-update-change

修订变更提案的现有规划工件，并保持它们之间的一致性。

契约	描述
参数	变更提案名称，可选，加上你想要的修订。如果未说明修订内容，则运行一致性审查：检查各工件之间是否存在矛盾、遗漏和重复。
创建	编辑已存在的工件文件。一个例外：对于以 glob 形式编写的工件，例如 specs/**/*.md，如果已存在至少一个文件，则在确认路径后可以添加缺失的伴随文件。尚不存在文件的工件是 openspec-continue-change 的职责。如果没有该 skill（核心 profile 不包含它），则改为指向 openspec status 和 openspec instructions。绝不编写代码。
响应	显示每个提议的修订，并在你确认后逐个工件写入。最后说明修订内容和下一步；实现等待 openspec-apply-change。

openspec-sync-specs

将变更提案的规格更新合并到 specs/ 中，而不归档它。

契约	描述
参数	变更提案名称，可选。你也可以指定其增量规格的一个子集，仅同步这些规格。
创建	为每个增量规格编辑或创建 openspec/specs/<capability-path>/spec.md，将新增、修改、删除和重命名的需求合并到主规格中。绝不编写代码。
响应	更新后的规格验证通过后，按能力汇总新增、修改、删除或重命名的需求。变更提案保持活跃；归档等待 openspec-archive-change。

openspec-archive-change

将已完成的变更提案移至归档。

契约	描述
参数	变更提案名称，可选。
创建	将变更提案文件夹移至 openspec/changes/archive/YYYY-MM-DD-<name>/（如果名称已以日期开头则不添加日期）。经你批准，它会先同步未完成的增量规格。当 openspec-sync-specs 已安装时，它运行该工作流。否则，它自己将增量规格合并到主规格中。绝不编写代码。
响应	在工件或任务不完整时发出警告并询问后再归档，并在存在增量规格时询问是否同步。最后给出摘要：名称、schema、归档位置、规格同步状态以及任何警告。

openspec-new-change

以空脚手架开始一个变更提案。

契约	描述
参数	kebab-case 格式的名称（add-user-auth）或一段简单的描述，以及仅用于非默认工作流的 schema 名称。如果两者都未提供，它会询问你要构建什么。
创建	openspec/changes/<name>/ 作为空脚手架：尚无任何工件，绝不编写代码。
响应	脚手架的名称和位置、工作流的工件序列、状态（0/N 完成）以及第一个工件的模板。起草工件等待 openspec-continue-change。

openspec-continue-change

在变更提案中逐个创建下一个规划工件。

契约	描述
参数	变更提案名称，可选。如果仍然不明确，它会要求你从最近修改的中选择。
创建	schema 序列中下一个就绪的单个工件，写入变更提案文件夹。每次运行一个工件，绝不编写代码。
响应	已创建的工件、进度（N/M 完成）以及解锁了哪些工件。当规划完成时它会说明；实现转到 openspec-apply-change。

openspec-ff-change

一次性创建变更提案及其实现所需的每个规划工件。

契约	描述
参数	kebab-case 格式的名称或一段简单的描述。如果两者都未提供则会询问。如果指定的变更提案已存在，它会建议继续该提案。
创建	openspec/changes/<name>/ 及实现所需的每个规划工件，按依赖顺序排列（规格驱动：提案、规格、设计、任务），仅排除标记为跳过或条件性的工件。绝不编写代码。
响应	变更提案的名称和位置、创建的每个工件以及任何被跳过的条件性工件及其原因。到此为止；实现等待 openspec-apply-change。

openspec-verify-change

检查实现是否与变更提案的工件匹配。

契约	描述
参数	变更提案名称，可选。当不明确时它会询问，列出具有 tasks 工件的变更提案。
创建	不创建任何内容。它读取变更提案的工件和代码库。验证仅生成报告。
响应	一份报告：完整性、正确性和一致性的计分卡，然后是 CRITICAL、WARNING 和 SUGGESTION 级别的问题及建议，以及最终的归档就绪评估。它不更改任何内容，也不执行归档。

openspec-bulk-archive-change

一次性归档多个变更提案。

契约	描述
参数	无。它列出活跃的变更提案并要求你选择任意数量，同时提供全选选项。如果没有活跃的提案，它会说明并停止。
创建	每个已归档的变更提案对应 openspec/changes/archive/YYYY-MM-DD-<name>/（已包含日期的名称保留其前缀）。每个提案的规格增量先通过 openspec-sync-specs 同步。绝不编写代码。
响应	每个变更提案的状态表以及整批的一次确认，然后是已归档、已跳过和已失败的摘要，以及规格同步结果。当两个变更提案涉及同一规格时，它会检查代码库并按从旧到新的顺序同步已实现的增量。

openspec-onboard

通过端到端完成一个真实的变更提案来学习工作流。

契约	描述
参数	无。它扫描你的代码库寻找小的入门任务，并要求你选择一个或描述自己的任务。
创建	为所选任务创建一个真实的变更提案，逐个创建工件，然后在确认实现后编写真实代码。最后归档变更提案。
响应	对完整周期的讲解式演示，在关键时刻暂停等待你的输入：探索、创建、构建每个工件、实现、归档。最后以回顾和指向 openspec-propose 的提示结束。大约需要 15 到 20 分钟。