Agent Skills 规范

为 Claude Code、Cursor、Codex 以及其他支持 Skill 的 Agent 宿主环境部署官方 OriginAI Agent Skill 规范。

OriginAI Agent Skill 专为大语言模型与自主 Agent 注入专业的产品工程认知：指导其如何高效调用 CLI 工具、如何将已发布的 Release 快照视作单一事实准绳，以及如何编写与严密校验结构化的 RPML 规格。部署该 Skill 是将通用代码生成 Agent 转变为深度理解并融入 OriginAI 研发闭环的关键一步。

核心配置属性	规范取值
Skill 官方标识	`origin-product-spec-management`
本地部署物理路径	`.agents/skills/origin-product-spec-management/`
规则定义单一事实源（SSOT）	`packages/skills/src/setup.ts` 中的 `SKILL_MD` 常量
自动构建的发现资产	`frontend/public/.well-known/agent-skills/`（切勿进行手动修改）

Skill 规范的核心赋能价值

将 Claude Code、Cursor、Codex、Pi、Hermes 及基于 skills.sh 规范构建的各类 Agent 精准接入 OriginAI 产品规格中枢。
指导 Agent 在建立 MCP 协议连接时优先使用 MCP 工具；未连接时自动无缝回退至功能等价的 originai CLI 命令行调用。
深度内化**“默认读取权威 Release 快照”与“版本发布后写入恒定转换为变更请求”**的受控协作机制。
在 rpml/ 子目录中内聚打包完整的 RPML 原型语法规范——涵盖设计方法论、常用 UI 原语索引、结构化示例与标准 Prompt 模板。
依赖标准安全的 npx originai login 本地会话机制完成权限认证，规范正文中绝不硬编码任何敏感令牌。

部署安装 Skill 规范的途径

途径 A —— 借助 skills.sh 安装（推荐的公共发现路径）

官方开源 Skill 规范托管于 GitHub 仓库 21stware/originai-context 的 skills/origin-product-spec-management/ 路径下。

npx skills add 21stware/originai-context
# 或精准固定安装指定的单项 Skill：
npx skills add 21stware/originai-context --skill origin-product-spec-management
# 或在安装前列举该仓库提供的所有可用 Skill：
npx skills add 21stware/originai-context --list

该公共 Skill 文件不包含任何私有密钥或硬编码的项目 ID。因此在安装完成后，你仍需在本地执行标准授权与项目绑定：

npx originai login
npx originai link --project <project-id>

你也可以直接从 OriginAI 官方站点的 Well-known 端点拉取并安装（通过 HTTP 协议获取完全一致的规范正文）：

npx skills add https://getoriginai.com
# 底层解析入口为：https://getoriginai.com/.well-known/agent-skills/index.json

关于该生态规范的更多详情，请参见 skills.sh 官方文档与 skills CLI 开源仓库。

途径 B —— 借助 OriginAI CLI 直接写入本地代码仓库

npx originai login
npx originai link --project <project-id> --skill
# 若本地已存在 .origin.json 绑定配置，仅需单独部署或更新 Skill 规范时：
npx originai link --skill

途径 C —— 安装 Claude Code 官方插件

直接从同一公共仓库安装官方 Claude Marketplace 插件；该插件深度集成了 Skill 规范与本地 stdio MCP 服务器。详情参阅 MCP 与 Agent 安装参考。

部署就绪后，引导 Agent 通读本仓库中的 SKILL.md，随后即可自主执行规格的实现对齐或逆向提取。

完整的端到端接入流水线

部署 Skill 规范：通过执行 npx skills add 21stware/originai-context、originai link --skill 或安装 Claude Code 官方插件完成规范加载。
本地环境授权：执行 npx originai login，将授权凭据安全写入本地系统的 ~/.origin/settings.json。
绑定代码仓库：运行 npx originai link --project <id>，在本地仓库根目录生成轻量元数据配置文件 .origin.json。
启动 Agent 协同：在具备 MCP 工具的环境下通过 MCP 交互；在纯终端环境下由 Agent 自主调用 originai CLI 推进研发。

数据读取与协同同步机制

检索读取规范：所有读取操作默认锁定最新已发布的 Release 快照，确保 Agent 始终以经过人类签字确认的正式规格为代码实现的唯一依据，绝不受到人类动态草稿编辑的干扰。
发起规格写入：在项目完成首次发布之前，Agent 拥有直接写入动态工作区的权限；在项目完成首次发布之后，Agent 发起的所有写入会自动受控转为暂存变更请求（返回 suggested: true），由人类在 Web 界面中应用后再行发布新版本。Agent 严禁自审自批。
同步指针推进：.origin.json 负责记录当前代码仓库已对齐的 release_hash。在代码落地实现且测试验证无误后，通过执行 originai sync 命令正式向前推进同步指针。

各功能接口的详细参数与用法，请参阅 OriginAI CLI 命令行参考。

免安装的 HTTP 自动发现端点（可选扩展）

尽管推荐优先在本地部署规范，但外部 Agent 亦支持在完全不安装物理文件的场景下，直接通过 HTTP 协议实时抓取规范全文：

上述网络资源均在前端项目构建阶段基于底层常量 SKILL_MD 自动生成（执行脚本 frontend/scripts/generate-well-known-skill.ts）。严禁手动修改此类静态派生文件。

规范准确性维护准则

当遇到以下情况变动时…	应当更新的代码与文档…
CLI 底层命令行为调整或 Skill 指令逻辑升级	优先且必须更新 `packages/skills/src/setup.ts`，随后同步更新本文档页面。
Well-known 公开网络发现正文需要更新	通过前端自动化构建脚本重新编译生成——切勿进行任何手动修改。