OpenSkillSpec

OpenSkillSpec 让人类与 AI 编程助手在写代码之前就通过规范驱动的流程对需求达成一致。

为何选择 OpenSkillSpec？

当需求只保存在对话中时，AI 编程助手虽然强大，却难以预测。OpenSkillSpec 引入轻量的规范流程，在实现之前锁定意图，确保输出可复查、可验证。

核心收益：

• 人与 AI 在开工前就对规范达成共识。
• 变更文件夹（proposal、tasks、spec updates）结构化呈现范围，方便审计。
• 可见性清晰：区分提案中、进行中、已归档的工作。
• 可与现有 AI 工具协作：支持的工具可用自定义斜杠命令，其余工具通过共享的上下文规则运行。

快速上手

支持的 AI 工具

原生斜杠命令

以下工具内置 OpenSkillSpec 命令，提示时直接选择 OpenSkillSpec 集成即可：

| Tool | Commands | |------|----------| | Claude Code | /openSkillSpec:proposal, /openSkillSpec:apply, /openSkillSpec:archive | | Cursor | /openspec-proposal, /openspec-apply, /openspec-archive | | Gemini CLI | /openSkillSpec:proposal, /openSkillSpec:apply, /openSkillSpec:archive | | Qwen Code | /openSkillSpec:proposal, /openSkillSpec:apply, /openSkillSpec:archive |

对话触发

以下工具支持对话触发 OpenSkillSpec 命令，需要时让它们遵循 OpenSkillSpec 工作流即可。

• openSkillSpec:proposal：创建/生成提案
• openSkillSpec:apply：实现提案变更
• openSkillSpec:archive：归档提案

对话触发命令不需要输入提案名称，系统会自动读取plans/task-template.md任务需求模板中的 Change ID 字段。

兼容 AGENTS.md 的工具

这些工具会自动读取 openskillspec/AGENTS.md 中的流程说明，需要时让它们遵循 OpenSkillSpec 工作流即可。了解更多可查看 AGENTS.md 约定。

安装与初始化

前置条件

• Node.js >= 20.19.0（使用 node --version 检查）

步骤 1：全局安装 CLI

npm install -g openSkillSpec

验证安装：

openSkillSpec --version

步骤 2：在项目中初始化

切换到项目目录：

cd my-project

执行初始化：

openSkillSpec init

初始化会完成：

• 询问你要启用的 AI 工具；其它助手使用共享的 AGENTS.md
• 自动配置所选工具的斜杠命令，并在项目根目录生成托管版 AGENTS.md
• 创建 openskillspec/ 目录结构

完成后：

• 支持的主力 AI 工具可直接触发 /openSkillSpec 系列命令
• 运行 openSkillSpec list 查看当前是否存在变更
• 如果新命令未立即出现，重启助手即可（斜杠命令在启动时加载）

可选：补充项目上下文

openSkillSpec init 结束后，可使用推荐提示语补全项目背景：

Populate your project context:
"Please read openskillspec/project.md and help me fill it out with details about my project, tech stack, and conventions"

openskillspec/project.md 用于记录项目级约定、架构模式与通用指南。

创建首个变更

下面以真实示例演示完整流程，任意 AI 工具均适用，支持斜杠命令的工具可使用快捷方式。

提示：

• 若已在 openskillspec/plans/task-template.md 中填写 Change ID，执行 /openspec-proposal、/openspec-apply、/openspec-archive 时无需手动指定 change-id，系统会自动读取模板中的值。
• 智能提案生成：若 task-template.md 已完整填写（包含背景、需求、验收标准等），执行 /openspec-proposal 时，AI 会自动读取并理解模板内容，基于模板生成完整的 proposal.md、tasks.md 和 spec deltas，无需重复描述需求。

1. 起草 proposal

让 AI 生成变更提案：

• 对话触发：帮我根据plans/task-template.md生成一个提案
• 斜杠命令：/openSkillSpec:proposal Change ID

2. 校验与评审

确认文件生成正确，并审阅提案：

$ openSkillSpec list                             # 确认变更文件夹存在
$ openSkillSpec validate add-profile-filters     # 验证 spec 格式
$ openSkillSpec show add-profile-filters         # 查看 proposal、tasks、spec delta

3. 迭代规范

不断完善规范直到满足需求：

检查spec和tasks文件，确保没有问题后，保证和需求一致。

4. 执行实现

规范确认后开始按任务实现：

• 对话触发：帮我实现提案变更
• 斜杠命令：/openSkillSpec:apply Change ID

5. 归档变更

任务完成后归档变更：

• 对话触发：帮我归档提案变更
• 斜杠命令：/openSkillSpec:archive Change ID

或直接在终端运行：

$ openSkillSpec archive Change ID --yes  # 无交互归档

注意： 原生斜杠命令（Claude Code、Cursor 等）可直接使用上述快捷语句。其它工具可通过自然语言请求 “create/apply/archive the OpenSkillSpec change”。

命令速查

openSkillSpec list               # View active change folders
openSkillSpec view               # Interactive dashboard of specs and changes
openSkillSpec show <change>      # Display change details (proposal, tasks, spec updates)
openSkillSpec validate <change>  # Check spec formatting and structure
openSkillSpec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)
openSkillSpec init [path] [--framework <vue|react>]  # Initialize OpenSkillSpec with optional framework template

示例：AI 如何生成 OpenSkillSpec 文件

当你提出 “add two-factor authentication” 需求时，AI 会自动生成：

openskillspec/
├── plans/
│   └── task-template.md      # 任务需求变更模板（用于自动获取 Change ID）
├── specs/
│   └── auth/
│       └── spec.md           # Current auth spec (if exists)
└── changes/
    └── add-2fa/              # AI creates this entire structure
        ├── proposal.md       # Why and what changes
        ├── tasks.md          # Implementation checklist
        ├── design.md         # Technical decisions (optional)
        └── specs/
            └── auth/
                └── spec.md   # Delta showing additions

AI 生成的 Spec（写入 openskillspec/specs/auth/spec.md）

# Auth Specification

## Purpose
Authentication and session management.

## Requirements
### Requirement: User Authentication
The system SHALL issue a JWT on successful login.

#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned

AI 生成的 Delta（写入 openskillspec/changes/add-2fa/specs/auth/spec.md）

# Delta for Auth

## ADDED Requirements
### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required

AI 生成的任务清单（写入 openskillspec/changes/add-2fa/tasks.md）

## 1. Database Setup
- [ ] 1.1 Add OTP secret column to users table
- [ ] 1.2 Create OTP verification logs table

## 2. Backend Implementation  
- [ ] 2.1 Add OTP generation endpoint
- [ ] 2.2 Modify login flow to require OTP
- [ ] 2.3 Add OTP verification endpoint

## 3. Frontend Updates
- [ ] 3.1 Create OTP input component
- [ ] 3.2 Update login flow UI

重点： 这些文件无需手动创建，AI 会基于需求与现有代码库自动生成。

理解 OpenSkillSpec 文件结构

任务模板与 Change ID 自动获取

OpenSkillSpec 支持通过 openskillspec/plans/task-template.md 自动获取 Change ID，简化工作流程：

task-template.md 的作用：

• 提供统一的需求变更模板，包含 Change ID、Owner、优先级、背景目标、需求详情、验收标准、测试计划等完整信息
• 在执行 /openspec-proposal、/openspec-apply、/openspec-archive 时，若未明确指定 change-id，系统会自动读取模板中的 Change ID 字段
• 格式：- Change ID：<value> 或 - Change ID: <value>（支持中英文冒号）

自动获取 Change ID 的流程：

1. 创建提案（/openspec-proposal）：
   • 若未指定 change-id，自动读取 task-template.md 中的 Change ID 字段，用于创建 openskillspec/changes/<change-id>/ 目录
   • 智能理解模板内容：若模板已填写完整（非空字段），AI 会自动读取并理解整个模板内容，包括：
     • "背景与目标" → 生成 proposal.md 的 Why 和 What Changes 部分
     • "需求详情" → 生成 proposal.md 的 Impact 部分和 tasks.md 的任务清单
     • "验收标准" → 转换为 spec deltas 中的 #### Scenario: 场景
     • "测试计划" → 整合到 tasks.md 的测试相关任务
   • 基于模板内容自动生成完整的提案结构，无需重复输入
2. 执行变更（/openspec-apply）：若未指定提案名称，自动读取模板中的 Change ID，定位对应的变更目录执行任务
3. 归档变更（/openspec-archive）：若未指定提案名称，自动读取模板中的 Change ID，执行归档操作

Fallback 机制：

• 若模板中 Change ID 为空、缺失或文件不存在，系统会提示用户手动输入
• 若用户手动指定了 change-id 参数，优先使用手动值（覆盖模板值）

示例：

# 任务需求变更模板

## 0. 任务概述
- Change ID：`add-user-profile`
- Owner / Reviewer：AI 助手 / 用户
- 优先级 / 截止日期：P1 / 2025-12-31

执行 /openspec-proposal 时，系统会自动使用 add-user-profile 作为 change-id，无需手动输入。

Delta 格式

Delta 是展示规范变更的“补丁”：

• ## ADDED Requirements：新增能力
• ## MODIFIED Requirements：变更既有行为（需包含完整更新后的内容）
• ## REMOVED Requirements：移除功能

格式要求：

• 标题使用 ### Requirement: <name>
• 每个 Requirement 至少包含一个 #### Scenario:
• Requirement 文本使用 SHALL/MUST 等规范化措辞

许可证

MIT

作者

[email protected]