如何为 delegate-skills 贡献新实现者技能：4 条不变式与合并清单（开发者指南）
【免费下载链接】delegate-skillsDelegate a coding task to a separate coding agent CLI, review the diff, land the commit yourself — one per implementer.项目地址: https://gitcode.com/gh_mirrors/de/delegate-skills
delegate-skills是一个 AI 编码代理委派（delegation）技能包：由编排代理（orchestrator）把编码任务委派给独立的 CLI 编码代理（implementer），再由你自己审阅 diff、跑测试并提交。本文是贡献一个新实现者技能（implementer skill）的完整开发者指南——先看懂所有技能必须满足的4 条不变式（invariants），再照着合并清单（merge checklist）逐项落地，让你的新 relay 一次通过评审。
💡 开工前先记住项目第一条规矩：claim an implementer before you build（先认领，再动手）。这个项目已经发生过两次两人独立构建了同一技能、结果都白费的事。提交前务必查看开放认领（open claims）与开放 PR。
贡献前 2 分钟：认领与仓库准备
- 确认你要支持的 CLI尚未被认领，也没有人正在做（检查开放 issues 与 PR 列表）。
- 克隆仓库并开始开发：
git clone https://gitcode.com/gh_mirrors/de/delegate-skills- 通读两份"宪法"文件，并把它们指给你的 AI 代理一起读：
- CONTRIBUTING.md — 4 条不变式、合并清单、发布流程
- AGENTS.md — 受控词汇表（别自造新词！）与发布前检查单
核心关键词一：4 条不变式（新技能的硬门槛）
以下 4 条不变式适用于仓库里的每一个*-delegate技能，也是新技能能否被接受的验收标准：
| # | 不变式 | 一句话解释 |
|---|---|---|
| 1 | 独立 CLI 修改真实工作树，diff 即交付物 | 不是 API 包装、不是托管网关——成果必须能用git diff审阅。没有工作树就不属于这里 |
| 2 | relay 永不提交 | 提交权永远属于审阅者（你），relay 只负责派工和收集结果 |
| 3 | 仅用 Node 内置模块 | 零依赖、无自有网络调用、不读写凭据、无遥测；relay 只启动实现者 CLI 与git |
| 4 | 自治能力用 CLI 自己的术语描述 | CLI 强制不了的，就在文档里直说（如"无只读模式"）。没有只读模式的 CLI 可以合并，暗示它有只读模式的技能不行 |
⚠️ 第 4 条最容易被忽视：像 Grok 这类无法强制只读的 CLI，relay 会报告三态
readOnlyViolation触发器——这种"如实说明局限"正是可合并的做法。
标准目录结构：形状即契约
每个实现者技能是一个目录，命名<cli>-delegate（动词属于仓库名，目标代理才是技能名）。参照现有样板 skills/codex-delegate/SKILL.md：
skills/<name>-delegate/ ├── SKILL.md ├── scripts/ │ └── relay.mjs └── references/ ├── writing-the-brief.md ├── dispatch-and-poll.md ├── review-and-land.md └── multi-task-queues.md两个容易踩坑的细节：
- 正好 4 个 references，不是 3 个也不是 5 个——"the shape is the contract"（形状即契约）。可对照 skills/codex-delegate/references/writing-the-brief.md 理解每篇该写什么。
SKILL.md的description是唯一触发信号，只写"做什么 + 何时用"，且必须< 1024 字符（部分编排器如 ZCode 会硬性截断拒收）。name必须等于目录名；还要写compatibility:指明二进制与其认证步骤。
核心关键词二：合并清单（Merge Checklist）逐项过
以下是 CONTRIBUTING.md 中合并清单的完整复刻，逐项打勾再开 PR：
skills/<name>-delegate/SKILL.md—description只在该 CLI 被委派时触发；compatibility:写明二进制与认证步骤- 4 个
references/*.md：writing-the-brief、dispatch-and-poll、review-and-land、multi-task-queues - 1 个
scripts/relay.mjs（如 relay.mjs 的结构），仅 Node 内置模块，永不提交 result.json说delegate-relay.result.v1协议：status、exitCode、signal、最终报告、touchedFiles（git 无法报告时为null，工作树干净时为[]）、CLI 暴露时的会话 id- 用法错误在写结果文件之前以退出码 2 结束；二进制缺失以 127 退出并写出结果文件
- 注册进 test/harness/constants.mjs — 新 relay 像所有兄弟技能一样进入 timeout / abort 测试矩阵
- README.md 技能表格加一行，AGENTS.md 词汇表加一行（用该 CLI 自己的术语）
- skills.sh.json 增加一个条目
- README 的Verification status加一行验证记录——只声明你真实跑过的："contract-tested, live run pending" 是可合并的回答；没跑却写 "verified" 不是
✅ 好消息：测试套件会自我检查——如果你的技能目录漏登矩阵、缺一篇 reference 或没进
skills.sh.json，整个测试直接失败，不用评审人帮你抓漏。
加入冒烟矩阵：新 relay 的"第一堂课"
把技能名加入 test/harness/constants.mjs 的SKILLS数组后，你的 relay 就自动进入与所有兄弟相同的超时/中断路径验证。本地开发时不必每次跑全量：
# 只跑你新增的模块（逗号分隔可跑多个） node test/relay-smoke.mjs --only <yourskill> # 全量冒烟（提交前必须跑） node test/relay-smoke.mjs冒烟套件会用"假 CLI"驱动 relay 做端到端验证：timeout 场景要求看门狗杀掉实现者的整个进程树并写出status: "timeout"；abort 场景要求杀掉 relay 本身后仍产出status: "aborted"的结果文件。机制细节见 test/relay-smoke.mjs 头部注释。
共享 helper：字节级一致契约
所有 relay 共享一小撮 helper（如killChild、gitTouchedFiles、parseDuration），它们的契约是字节级完全相同（byte-identical）。修改前先检视每一个存在分歧的兄弟实现，把最强的行为（包括边界值与超时处理）带过来，然后运行一致性门禁：
node test/relay-parity.mjs node test/relay-smoke.mjsdocs/plans/relay-core-dedup.md 记录了这套一致性门禁的来龙去脉——它诞生于真实的漂移事故，是维护者最在意的事之一。
提交前验证（Pre-publish Checklist）
开 PR 前，按 AGENTS.md 的"Before publishing a change"走一遍：
# 本地验证包结构 npx skills add . --list # relay 帮助 + 一次性仓库上的只读/无写入运行 node skills/<name>-delegate/scripts/relay.mjs --help另外两条高频检查点：
- 改了 relay 的启动方式？在 Windows 原生 PowerShell/cmd 上也要冒烟（不只是 Git Bash/WSL）——
.cmdshim 解析问题只在那里暴露。 - 改了完成判定或
touchedFiles？先读该技能的结果契约，并对干净树、预置脏文件、子模块、git 不可用等场景断言精确的delegate-relay.result.v1字段，而不是笼统的成功/失败。
PR 描述里写明你跑了什么——维护者会逐行读 relay，并对验证声明中的每一句提出追问。
发布流程：git tag 才是版本号
安装固定（install pinning）使用git tag而非metadata.version：
- 把发布落到
master； - 将所有技能的
metadata.version提升到本次发布的 semver（如0.2.0）； - 创建带注释的 tag 并推送：
git tag -a v0.2.0 -m "v0.2.0"→git push origin v0.2.0； - 用户以
npx skills add amElnagdy/delegate-skills@v0.2.0安装固定版本。
用户可见的技能或 relay 契约变更要升 tag；纯文档或纯冒烟可以是 patch。Schema id（delegate-fleet.v1等）在 JSON 结构破坏时独立升版。
常见问题速答
Q：能不能直接复制一个现有技能改？可以——选与目标 CLI 行为最接近的兄弟作模板（如都走 stdin 派 brief 的可参考 Cline 系），但"形状即契约"：4 篇 reference、1 个 relay、字节级一致的共享 helper 一个都不能少。
Q：只想修现有 relay 的 bug？不需要认领。保持 diff 单一关注点，跑node test/relay-smoke.mjs和npx skills add . --list，在 PR 里说明你验证了什么即可。
Q：我要做的是"配置类"工具技能，和实现者技能一样吗？不一样。skills/delegate-setup/SKILL.md 是唯一的**工具技能（utility skill）**例外：它发现 CLI、写入 lane 配置，但永不派工。不要发明第二个重复 lane 配置的工具——扩展delegate-setup而不是新建。
Q：评审流程是什么样的？一名维护者逐行审查 relay；CodeRabbit 等自动评审仅供参考，其不可用时记录并继续，不等待。两个 PR 撞同一实现者时，以本清单满足度定胜负——满足更多项的先合并。
把这份清单贴在 PR 模板旁边：4 条不变式保你方向正确，合并清单保你一次通过，冒烟矩阵替你把"漏登注册"这类低级失误挡在门外。祝合并顺利 🚀
【免费下载链接】delegate-skillsDelegate a coding task to a separate coding agent CLI, review the diff, land the commit yourself — one per implementer.项目地址: https://gitcode.com/gh_mirrors/de/delegate-skills
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
