支持的工具

OpenSpec 可与多种 AI 编程助手配合使用。运行 openspec init 时，OpenSpec 会根据您选择的配置文件/工作流和交付模式来配置所选工具。

工作原理

对于每个选中的工具，OpenSpec 可以安装：

1. 技能（如果交付包含技能）：.../skills/openspec-*/SKILL.md
2. 命令（如果交付包含命令）：工具特定的 opsx-* 命令文件

Codex 仅支持技能模式：即使交付模式设置为 commands，OpenSpec 也会为 Codex 安装 .agents/skills/openspec-*/SKILL.md，并且不会生成 Codex 自定义提示文件。在写入替代文件后，位于旧版 .codex/skills 路径下的现有 OpenSpec 管理的技能会被协调处理；自定义和差异文件会被保留。

默认情况下，OpenSpec 使用 core 配置文件，其中包含：

• propose
• explore
• apply
• update
• sync
• archive

您可以通过 openspec config profile 启用扩展工作流（new、continue、ff、verify、bulk-archive、onboard），然后运行 openspec update。

如何调用

本文档使用 /opsx:propose 作为规范名称，但每个工具在加载 OpenSpec 编写的文件时，其命令格式各不相同。请在下方的工具目录参考中找到你使用的工具对应的命令路径，然后对照此处的格式。

OpenSpec 写入的命令文件	你输入的内容	工具
.../commands/opsx/<id>.* — opsx/ 文件夹作为命名空间	/opsx:<id>	Claude Code、CodeBuddy、Crush、Gemini CLI、Lingma、Qoder、ZCode
.../opsx-<id>.* — 文件名即为命令	/opsx-<id>	所有其他生成命令文件的工具，Amazon Q 和 Devin 除外
.devin/workflows/opsx-<id>.md — 仅由 Devin 的两个 agent 之一读取	Devin Desktop 上为 /opsx-<id>，Devin Local 上为 /openspec-<skill>	Devin Desktop****
.amazonq/prompts/opsx-<id>.md — 提示词，非命令	@opsx-<id>	Amazon Q Developer
无 — 仅技能	/openspec-<skill>	CodeArts、ForgeCode、Hermes、MiniMax Code、Mistral Vibe、Zed Agent、共享 .agents
无 — Kimi Code	/skill:openspec-<skill>	Kimi Code
无 — Codex CLI	$openspec-<skill>	Codex（/openspec-<skill> 不被识别）

因此 /opsx:propose 在 Cursor 中为 /opsx-propose，在 Amazon Q 中为 @opsx-propose，在 Codex 中为 $openspec-propose。

有两个因素独立变化，因此各行无法合并：

• 名称。 第 1–2 行仅在文件如何命名命令上有所不同，对于所有生成命令文件的工具，opsx-<id> / opsx:<id> 词干是相同的。
• 包装器。 Amazon Q 将其文件加载到通过 @ 调用的提示词库中。仅技能工具完全不生成命令文件，因此其后三行使用技能名称 — 列于生成的技能名称下 — 这些名称与命令 ID 并非一一对应（/opsx:apply 对应 openspec-apply-change 技能）。

上述命令路径模式有意使用扩展名无关的写法（.*）：扩展名由工具决定（Gemini CLI 为 .toml，Continue 为 .prompt，Kiro 和 GitHub Copilot 为 .prompt.md），部分工具在选择器中显示名称时会附带扩展名。请匹配目录结构，而非扩展名。

OpenSpec 生成的文件以及设置完成后打印的"快速入门"提示，已经使用了你所选工具的正确格式 — 因此最快的方式是直接阅读该提示。

工具目录参考

工具（ID）	技能路径模式	命令路径模式
Amazon Q Developer (amazon-q)	.amazonq/skills/openspec-*/SKILL.md	.amazonq/prompts/opsx-<id>.md
Antigravity (antigravity)	.agent/skills/openspec-*/SKILL.md	.agent/workflows/opsx-<id>.md
Auggie (auggie)	.augment/skills/openspec-*/SKILL.md	.augment/commands/opsx-<id>.md
IBM Bob Shell (bob)	.bob/skills/openspec-*/SKILL.md	.bob/commands/opsx-<id>.md
Claude Code (claude)	.claude/skills/openspec-*/SKILL.md	.claude/commands/opsx/<id>.md
Cline (cline)	.cline/skills/openspec-*/SKILL.md	.clinerules/workflows/opsx-<id>.md
Command Code (command-code)	.commandcode/skills/openspec-*/SKILL.md	.commandcode/commands/opsx-<id>.md
CodeArts (codeartsagent)	.codeartsdoer/skills/openspec-*/SKILL.md	未生成（无命令适配器；使用基于技能的 /openspec-* 调用）
CodeBuddy (codebuddy)	.codebuddy/skills/openspec-*/SKILL.md	.codebuddy/commands/opsx/<id>.md
Codex (codex)	.agents/skills/openspec-*/SKILL.md	未生成（仅技能；使用 $openspec-*）
Devin Desktop，原 Windsurf (devin)	.devin/skills/openspec-*/SKILL.md	.devin/workflows/opsx-<id>.md****
ForgeCode (forgecode)	.forge/skills/openspec-*/SKILL.md	未生成（无命令适配器；使用基于技能的 /openspec-* 调用）
Continue (continue)	.continue/skills/openspec-*/SKILL.md	.continue/prompts/opsx-<id>.prompt
CoStrict (costrict)	.cospec/skills/openspec-*/SKILL.md	.cospec/openspec/commands/opsx-<id>.md
Crush (crush)	.crush/skills/openspec-*/SKILL.md	.crush/commands/opsx/<id>.md
Cursor (cursor)	.cursor/skills/openspec-*/SKILL.md	.cursor/commands/opsx-<id>.md
Factory Droid (factory)	.factory/skills/openspec-*/SKILL.md	.factory/commands/opsx-<id>.md
Gemini CLI (gemini)	.gemini/skills/openspec-*/SKILL.md	.gemini/commands/opsx/<id>.toml
GitHub Copilot (github-copilot)	.github/skills/openspec-*/SKILL.md	.github/prompts/opsx-<id>.prompt.md**
Hermes Agent (hermes)	.hermes/skills/openspec-*/SKILL.md***	未生成（无命令适配器；使用基于技能的 /openspec-* 调用）
iFlow (iflow)	.iflow/skills/openspec-*/SKILL.md	.iflow/commands/opsx-<id>.md
Junie (junie)	.junie/skills/openspec-*/SKILL.md	.junie/commands/opsx-<id>.md
Kilo Code (kilocode)	.kilocode/skills/openspec-*/SKILL.md	.kilocode/workflows/opsx-<id>.md
Kimi Code (kimi)	.kimi-code/skills/openspec-*/SKILL.md	未生成（无命令适配器；使用基于技能的 /skill:openspec-* 调用）
Kiro (kiro)	.kiro/skills/openspec-*/SKILL.md	.kiro/prompts/opsx-<id>.prompt.md
Lingma (lingma)	.lingma/skills/openspec-*/SKILL.md	.lingma/commands/opsx/<id>.md
MiniMax Code (minimax-code)	~/.minimax/skills/openspec-*/SKILL.md	未生成（无命令适配器；使用 MiniMax Code 技能）
Mistral Vibe (vibe)	.vibe/skills/openspec-*/SKILL.md	未生成（无命令适配器；使用基于技能的 /openspec-* 调用）
Oh My Pi (oh-my-pi)	.omp/skills/openspec-*/SKILL.md	.omp/commands/opsx-<id>.md
OpenCode (opencode)	.opencode/skills/openspec-*/SKILL.md	.opencode/commands/opsx-<id>.md
Pi (pi)	.pi/skills/openspec-*/SKILL.md	.pi/prompts/opsx-<id>.md
SourceCraft Code Assistant for VS Code (codeassistant)	.codeassistant/skills/openspec-*/SKILL.md	.codeassistant/commands/opsx-<id>.md
Qoder (qoder)	.qoder/skills/openspec-*/SKILL.md	.qoder/commands/opsx/<id>.md
Qwen Code (qwen)	.qwen/skills/openspec-*/SKILL.md	.qwen/commands/opsx-<id>.md
Rovo Dev CLI (rovodev)	.rovodev/skills/openspec-*/SKILL.md	未生成。Rovo 没有斜杠命令界面 — 它通过自动匹配技能或提示词来调用（例如"使用 openspec-propose 技能"）；/skills 仅用于管理技能。生成的内容通过名称引用技能，从不作为 /openspec-* 命令。
Zoo Code (roocode)	.roo/skills/openspec-*/SKILL.md	.roo/commands/opsx-<id>.md
Trae (trae)	.trae/skills/openspec-*/SKILL.md	.trae/commands/opsx-<id>.md
Zed Agent (zed)	.agents/skills/openspec-*/SKILL.md	未生成（仅技能；使用 /openspec-* 或 @openspec-*）
ZCode (zcode)	.zcode/skills/openspec-*/SKILL.md	.zcode/commands/opsx/<id>.md
共享 .agents 技能 (agents)	.agents/skills/openspec-*/SKILL.md	未生成（无命令适配器；使用基于技能的 /openspec-* 调用）

** GitHub Copilot 提示词文件在 IDE 扩展（VS Code、JetBrains、Visual Studio）中被识别为自定义斜杠命令。Copilot CLI 目前不直接消费 .github/prompts/*.prompt.md。选择 github-copilot 还可以配置 GitHub 托管的云端编码 agent — 参见下方的GitHub Copilot 云端编码 agent。

*** Hermes 默认从 ~/.hermes/skills/ 加载技能。要使用项目本地的 OpenSpec 技能，请将项目的 .hermes/skills/ 目录添加到 ~/.hermes/config.yaml 中的 skills.external_dirs；Hermes 随后将以面向用户的斜杠调用形式暴露技能，例如 /openspec-propose。

**** Windsurf 已于 2026 年 6 月 2 日更名为 Devin Desktop，其配置目录也随之迁移：.devin/ 是首选的读写位置，.windsurf/ 为遗留的只读回退。OpenSpec 遵循此次更名 — 工具 ID 为 devin，--tools windsurf 仍可解析到该工具，以确保现有设置脚本继续正常工作。如果项目中仍有 OpenSpec 文件位于 .windsurf/，下次运行 openspec update 时会提示迁移；拒绝则保留原位置，你自己编写的文件永远不会被修改。工作流通过文件名调用，因此 .devin/workflows/opsx-apply.md 对应 /opsx-apply。Devin Local agent 不支持工作流 — 仅支持技能，且完全不读取 .windsurf/ — 因此每当 OpenSpec 写入 Devin 技能时，都会保留其正文内容，并将快速入门提示指向 /openspec-* 技能调用，这在两个 agent 上均可用。在仅命令交付模式下不写入技能，两者均回退到 /opsx-*。

SourceCraft Code Assistant 支持针对其 VS Code 扩展。其自定义命令和技能仅在 VS Code 中可用。此集成不配置 SourceCraft Web 或 JetBrains。

在仅技能交付模式下，请让 Code Assistant 使用 openspec-propose 技能来处理你的想法。技能通过请求匹配激活；OpenSpec 不为该工具生成 /openspec-* 命令。

MiniMax Code 是全局仅技能集成。OpenSpec 仅在 ~/.minimax/skills/ 下写入其 openspec-* 目录；不会创建仓库本地的 .minimax 或 .mavis 目录。仅命令交付模式不会修改现有的全局 MiniMax Code 技能，以确保一个项目的交付设置不会移除另一个项目正在使用的技能。

GitHub Copilot 云端编码 agent

GitHub 的Copilot 编码 agent运行在 GitHub 的 GitHub Actions 环境中 — 与编辑器中的 Copilot 相互独立。OpenSpec 可以通过生成两个文件来配置其使用 OpenSpec CLI：

• .github/workflows/copilot-setup-steps.yml — 在 agent 环境中安装 @fission-ai/openspec
• .github/agents/openspec.agent.md — 告知 agent 如何驱动 OpenSpec

由于这会在你的仓库中写入 GitHub Actions 工作流，因此是可选启用的：

方式	行为
openspec init（交互式）	询问是否设置云端文件。默认值为否。
openspec init --copilot-cloud	不提示直接设置（适用于脚本/CI）。
openspec init --no-copilot-cloud	不提示直接跳过，并移除任何先前生成的文件。
openspec update	从不提示。仅在你已选择启用时（或项目已有这些文件）才刷新文件。如果你选择了禁用，它会移除 OpenSpec 管理的云端文件。

你的选择会保存在 openspec/config.yaml 中作为 githubCopilot.cloudAgent: true|false，因此非交互式更新会遵循该设置。OpenSpec 仅写入或移除其自身生成的文件 — 如果你自定义了 copilot-setup-steps.yml 或 openspec.agent.md，或者已有自己的版本，则不会修改（init/update 会告知你这一点）。

何时选择共享 .agents 目标

agents 是厂商中立的选项：它将技能写入 .agents/skills/，这是许多 agent 工具共同读取的共享根目录，而非工具专属目录。

场景	选择
你的工具在上方有独立行	其自身 ID — 你将获得该工具的集成，包括其支持的斜杠命令
一个仓库上有多个 agent，均读取 .agents/skills	agents — 一棵技能树而非每个工具一棵
你的工具尚未列出但读取 .agents/skills	agents

与工具专属 ID 同时选择它是可以的；每个工具通常写入各自的根目录。Codex 和 Zed Agent 是例外，因为它们使用相同的规范 .agents 根目录。如果 Codex 与 Zed 或 agents 同时被选中，OpenSpec 会保留一棵由 Codex 主导的树。其交接内容同时标注 $openspec-*（用于 Codex）和 /openspec-*（用于其他 agent），因此 --tools all 和现有的多 agent 设置无需两个写入者覆盖同一文件即可继续工作。OpenSpec 还会在项目拥有 .agents/skills/ 目录后自动提供该选项 — 仅有 .agents/ 是不够的，因为工具也使用该根目录存放规则和子 agent 定义。注意 .agents 不是 .agent：单数目录属于 Antigravity。

需要了解两点：

• 仅技能。 不存在命令适配器，因此不会写入 opsx-* 命令文件；在包含命令的交付模式下，openspec init 会在 Commands skipped for: … (no adapter) 下列出 agents。通过技能名称调用工作流 — 大多数读取 .agents/skills 的助手将其拼写为 /openspec-propose，这也是 OpenSpec 设置提示打印的格式。该目标是厂商中立的，因此如果你的助手使用其他格式，请查阅其自身文档。
• 不会创建或编辑 AGENTS.md。 目标是 .agents/ 目录。如果你的根目录 AGENTS.md 仍包含旧版本的 OpenSpec 标记块，openspec update 会将其移除 — 参见迁移指南。

此处的 Zed 支持针对内置的 Zed Agent。Zed External Agents 和 Terminal Threads 使用各自的集成。Agent Skills 需要 Zed v1.4.2 或更高版本。在未信任的工作树中，项目本地技能不可用，直到你授予信任。

由于 .agents/skills/ 由 Codex、Zed Agent 和厂商中立目标共享，了解 OpenSpec 在该目录中的声明范围是有价值的：它仅写入、刷新和移除你所选工作流对应的 openspec-* 技能目录，以及一个 .openspec-target 标记，用于记录该共享树是由 Codex、Zed Agent 还是厂商中立目标渲染的。该目录中的其他内容不会被修改。将 openspec-* 名称和标记视为 OpenSpec 的所有物 — 其中的编辑会在下次 openspec update 时被替换，与其他所有工具相同。

对于标记前的项目，OpenSpec 从管理的技能引用中推断所有权：$openspec-* 表示 Codex，/openspec-* 表示厂商中立目标。与遗留 .codex/skills 并存的通用规范树被视为旧版双目标安装，并合并到兼容的共享树中。

openspec update 也遵循此所有权规则。如果项目以厂商中立目标拥有 .agents，而仅从残留的提示词文件中检测到遗留的 Codex 安装，更新操作会保留已建立的 agents 树而非用 Codex 语法重写，并保留这些遗留提示词文件而非删除它们。要将共享树移交给 Codex，请显式运行 openspec init --tools codex。

非交互式安装

对于 CI/CD 或脚本化安装，请使用 --tools（可选搭配 --profile）：

# 配置特定工具
openspec init --tools claude,cursor

# 配置所有受支持的工具
openspec init --tools all

# 跳过工具配置
openspec init --tools none

# 覆盖本次初始化运行的配置文件
openspec init --profile core

可用工具 ID (--tools) — windsurf 也可接受，作为 devin 的别名：amazon-q, antigravity, auggie, bob, claude, cline, command-code, codeartsagent, codex, devin, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, hermes, iflow, junie, kilocode, kimi, kiro, lingma, minimax-code, vibe, oh-my-pi, opencode, pi, qoder, qwen, roocode, codeassistant, trae, zed, zcode, agents

基于工作流的安装

OpenSpec 会根据所选工作流安装相应的工作流工件：

• 核心配置（默认）： propose, explore, apply, update, sync, archive
• 自定义选择： 所有工作流 ID 的任意子集： propose, explore, new, continue, apply, update, ff, sync, archive, bulk-archive, verify, onboard

换句话说，技能/命令的数量取决于配置和交付方式，并非固定不变。

生成的技能名称

当通过配置文件的配置文件/工作流选中时，OpenSpec 会生成以下技能：

• openspec-propose
• openspec-explore
• openspec-new-change
• openspec-continue-change
• openspec-apply-change
• openspec-update-change
• openspec-ff-change
• openspec-sync-specs
• openspec-archive-change
• openspec-bulk-archive-change
• openspec-verify-change
• openspec-onboard

有关命令行为，请参阅 Commands；有关 init/update 选项，请参阅 CLI。

相关内容

• CLI Reference — 终端命令
• Commands — 斜杠命令和技能
• Getting Started — 首次设置