Skill Repository Protocol

本文档定义接入本工作区的 skill 子仓需要满足的额外工程要求。

本文档只描述 Skill 规范之外的要求。它不规定 skill 的内部实现方式，不重复定义 Skill 规范，也不规定 SKILL.md 的格式或内容结构。

目标

子仓协议用于保证：

• 主仓可以验证 skill 的运行依赖。
• Agent 可以通过脚本化入口判断 skill 是否可用。
• skill 生成的可检查产物有明确的校验方式。
• skill 子仓不依赖未声明的本机环境。

依赖自检入口

每个 skill 子仓根目录必须提供：

python verify_dependencies.py

该脚本是主仓判断 skill 运行环境是否可用的统一入口。

脚本要求：

• 能检查该 skill 运行所需的 Python 包、系统工具、浏览器运行时或外部服务。
• 对必需依赖缺失返回非零退出码。
• 对可选能力缺失给出警告，不应误报为必然失败。
• 能在 Windows Agent 工作流中运行。
• 输出应足够明确，便于 Agent 判断缺失项和修复方向。

如果 skill 依赖外部服务，建议提供跳过服务检查的参数，用于离线依赖复核。例如：

python verify_dependencies.py --skip-services

如果 skill 依赖可选硬件能力，应在输出中说明降级路径。

校验脚本要求

如果 skill 生成可检查的最终产物，子仓应提供脚本化校验入口。校验入口可以是 verify_dependencies.py 之外的独立脚本。

校验脚本应满足：

• 能由 Agent 从主仓根目录稳定调用。
• 通过命令行参数接收输入文件或输出目录。
• 对校验失败返回非零退出码。
• 输出失败原因，而不是只输出笼统的失败状态。
• 不要求 Agent 手工打开 IDE 或图形界面才能判断是否通过。

校验脚本不要求统一命名，但必须能在 SKILL.md 或主仓注册说明中被明确找到。

Codex 原生子 Agent

如果 skill 子仓提供 Codex 原生子 agent，应把稳定定义放在：

.codex/agents/*.toml

每个 agent TOML 必须包含：

• name
• description
• developer_instructions

name 必须在整个工作区内唯一。主仓会通过 scripts/check_codex_agents_config.py 扫描所有 skill 子仓的 .codex/agents/*.toml，并要求根目录 .codex/config.toml 中存在一致的 [agents.<name>] 登记。

子仓不应要求主仓复制 developer_instructions 正文；主仓只登记 description 和指向子仓 TOML 的 config_file。

依赖声明要求

skill 子仓不应依赖未声明的外部环境。

如果 skill 需要以下能力，应能被 verify_dependencies.py 检查，并由主仓登记到 docs/skill-dependencies.yml：

• Python 包。
• Node 或其他语言运行时依赖。
• 浏览器运行时。
• 系统命令行工具。
• 外部服务。
• IDE 插件。
• 可选硬件能力。

当前主仓以 Windows Agent 工作流为主要运行环境。skill 子仓应尽量保持跨平台；若某平台暂不可用，必须能被主仓在依赖登记中显式标记。

路径说明应避免写死个人机器路径。示例命令应优先使用相对路径，或明确说明需要从主仓根目录执行。

临时产物边界

skill 子仓不应要求把运行时中间产物写回子仓自身目录。

如果 skill 需要临时目录，应把目录规则设计为可挂载到主仓 .tmp/ 下。主仓会把 skill 的相对临时目录解释为 .tmp/ 的子路径。

正式产物是否进入主仓正式目录，由用户请求和主仓约定决定；子仓不应默认把中间产物视为可提交内容。

验收标准

一个 skill 子仓可被主仓接入，至少应满足：

• 子仓根目录存在 verify_dependencies.py。
• python verify_dependencies.py 能在 Windows Agent 工作流中运行。
• 必需依赖缺失时返回非零退出码。
• 可选依赖缺失时给出明确警告。
• 若存在可检查最终产物，提供脚本化校验入口。
• 若提供 .codex/agents/*.toml，agent TOML 字段完整、名称唯一，并可被主仓 .codex/config.toml 引用。
• 不要求临时产物写入 skill 子仓。
• 不依赖未声明的外部环境。