AGENT SKILL

issue-delivery

当已就绪 GitHub Issue 要形成可独立核验交付物时,从远端恢复范围、依赖、授权、成功条件、交付形态和所有权,按合同交付 Draft PR 或自足证据评论,并记录实际运行、未运行与缺口。已有授权不重问;不建任务图,不审查/合并自己的 PR,也不判生命周期。Use to deliver one ready Issue as its contracted Draft PR or evidence comment. Restore remote authority and ownership, validate proportionately, and return facts without task-graph, merge, or lifecycle decisions.

License 许可
MIT
最近更新
2026-08-25
Stars
★ 1
Forks
2

01 前言 Front Matter

name
issue-delivery
description
当已就绪 GitHub Issue 要形成可独立核验交付物时,从远端恢复范围、依赖、授权、成功条件、交付形态和所有权,按合同交付 Draft PR 或自足证据评论,并记录实际运行、未运行与缺口。已有授权不重问;不建任务图,不审查/合并自己的 PR,也不判生命周期。Use to deliver one ready Issue as its contracted Draft PR or evidence comment. Restore remote authority and ownership, validate proportionately, and return facts without task-graph, merge, or lifecycle decisions.

02 资源文件 1

03 SKILL.md 正文

交付一个 Issue

把一个已经存在的 GitHub Issue 从领取推进到合同指定的可独立核验交付物。GitHub 保存持久合同,本 Skill 只规定交付行为;具体命令、终端、Session 生命周期和消息由当前实际使用的工具提供,不复制进本文。

边界:本 Skill 负责哪一段

任务图与就绪 Issue  →  【本 Skill】领取 → 边界 → 实现 → 验证 → 远端交付物
                                                       ├─ Draft PR → 审查与授权合并
                                                       └─ 评论/证据 → 回收
  • 上游不属于本 Skill:长程目标对齐、父 Issue、子 Issue 拆分和依赖关系由 objective-to-issues 或负责人建立。
  • 下游不属于本 Skill:PR 的独立审查、当前 head 校验、Draft → ready、合并授权与合并后复核由 pr-integration 负责;任务图更新和回收仍归驱动者。
  • 本 Skill 不合并自己的 PR,也不把自己的交付当作已经验收。

本 Skill 是一段行为,不是驱动者。它只返回事实与段结果:本段完成后把交付事实交回 issue-workflow,由它决定进入审查、继续下一切片还是收口。本段不反向调用驱动者,不自建模式判定,也不判定父级或本 Issue 是否完成。被直接调用时同样只完成本段,并在结束时说明状态判定尚未作出、下一段归谁。

一、进入条件

进入本流程需要同时成立:

  • 当前任务已经指向一个具体 GitHub Issue,或已经授权从既有任务图中领取;
  • Issue 合同已经唯一指定交付形态;
  • 已有覆盖该形态的远端写入授权:PR 适配器至少包含推送工作分支和创建 Draft PR,评论/证据适配器至少包含向该 Issue 发布交付评论。

不进入的情况:目标尚未对齐;Issue 还只是未获准交付的想法或方案讨论;只需要一次不进入 GitHub 合同的临时回答;改动小到不需要 Issue,且当前任务没有要求走 GitHub 交付。

二、从远端 Issue 恢复合同

每次开始或恢复时重新读取远端当前状态,不从记忆、聊天上下文或本地草稿恢复。至少取得:

  1. 目标来源:父 Issue、批准来源和当前权威链接;
  2. 范围与明确不做事项;
  3. 依赖与就绪状态:blocked-by、sub-issue 关系、需要先落地的 PR;
  4. 授权:允许修改什么、允许哪些外部操作、哪些决定仍属于负责人;
  5. 成功条件与验收方式;
  6. 写入所有权:本 Issue 拥有哪些文件和资源,哪些明确属于其他执行者;
  7. 交付形态:代码/配置变更使用 PR 适配器,调研/审计/只读证据使用评论/证据适配器;不得同时保留两个候选让执行者临场选择;
  8. 既有状态:已有讨论、交付评论、分支和 PR,避免重复交付或覆盖他人工作。

GitHub Issue 只优先于聊天记忆、本地草稿和运行期协调状态:与这三者冲突时以远端 Issue 为准,并把差异写回 Issue 或升级给协调者。协调工具中的 Run、Task 和消息只帮助找回活动 Session 与执行者,不是持久合同。

Issue 不是权威本身,必须链接当前权威与批准来源。缺少这类链接,或 Issue 与当前权威、当前授权、负责人在该 Issue 之后给出的明确指令冲突时,不要用 Issue 覆盖它们:保持相关范围只读,把冲突写入 Issue 或当前任务,由协调者或负责人裁决后再继续。

第 1–7 项中会改变实现结果的内容缺失时,不要自行补写需求。

三、就绪判定与领取

一次只领取一个 Issue,且需要同时满足:

  • 依赖已解决,没有未完成的 blocked-by;
  • 范围、成功条件和文件所有权足够清楚,能在不猜测负责人偏好的前提下开始;
  • 写入授权覆盖需要修改的全部范围;
  • 没有其他执行者正在同一范围内工作。

多个就绪 Issue 需要同时推进,或者当前 Issue 实际上是一棵需要选择切片的子树时,不要在一个 Session 内串起来自行扩张:把控制权交回 issue-workflow,由它判定模式和切片顺序。

确实需要多个执行者时,分工和所有权由 orchestrated-collaboration 建立,且由驱动者决定何时进入,本段不自行派发。

不就绪时按最小动作处理:

  • 只缺可自行查明的事实 → 自己查清,把结论写回 Issue,然后继续;
  • 缺会改变结果的负责人决定 → 停止实现,在 Issue 上提出一次合并后的问题,或按当前协作关系升级;
  • 边界与另一个 Issue 重叠 → 先取得明确分区,不凭猜测缩小或扩大范围;
  • 依赖未完成 → 不领取,说明它在等什么。

停止和升级是正常结果,不是失败。不要为了推进而把未确认的假设写成需求。

四、建立执行边界

开始改动前确定并记录:

  • 执行者与 Session/终端标识;
  • PR 适配器使用基于当前远端默认分支、只服务这一个 Issue 的专用分支或 worktree;评论/证据适配器没有版本化文件改动时不为形式创建分支;
  • 允许写入的文件与资源范围,以及明确只读的范围;
  • 合同指定的唯一交付形态与停止条件(时间、成本或阶段)。

共享单点的唯一规范源是 agent-control/authority/04-collaboration.md 的“共享单点清单的唯一权威外延”,本段不复列或改写六类。本段的分支/worktree 约束只投影其中“Agent 系统的共享工作目录/分支”这一子集;若动作触及其余类别,返回规范源核对。worktree 只提供目录内文件隔离,不授予其他共享单点的写入权。所有权不明,或可能与其他活动 Session 重叠时,保持相关范围只读,并按 orchestrated-collaboration 取得明确分区后再写入。

任何两个执行者不能推送同一个分支。

五、按风险选择路径

默认直接实现。 普通、低风险、可回退的 Issue 不进入多轮 Challenge、三阶段深度规划、强制自审循环或额外调研。

已有预授权时不重复索要批准。 Issue 合同已经写明实施授权时,实现、验证和合同指定的远端交付都直接进行:PR 适配器还包括推送工作分支与创建 Draft PR,评论/证据适配器则包括发布自足评论并回读。只有合同没有覆盖的新决定才升级。把已经授权的事再问一次,是把成本转嫁给负责人。

只有出现以下信号时才升级,并且只升级到需要的程度:

  • 存在多个会显著改变结果的实现方向,且选错代价明显;
  • 关键假设不成立,或实际范围、成本明显超出 Issue 描述;
  • 需要难回退操作、共享状态修改或破坏性动作;
  • 连续尝试没有减少关键未知。

不要因为“看起来复杂”或“想更稳妥”就升级:升级要指出命中了上面哪一条具体信号。全链共用的三级风险判据在 issue-workflow,本节只覆盖叶子段;两处出现分歧时以那张表为准,不在本 Skill 复制它。

升级路径:

  • 问题界定、方向、方法或投入产出不清 → adaptive-problem-solving;
  • 需要多个执行者、跨 Session 协作,或已出现共享写入碰撞 → orchestrated-collaboration;
  • 需要可复用的当前知识或多来源调研 → knowledge-maintenance。

发现值得做但超出本 Issue 范围的工作时,把它留给任务图或在 Issue 中登记,不在本次 PR 里顺手扩张。

六、实现并做相称验证

实现只覆盖本 Issue 分配的范围。发现范围外的问题时记录并报告,不顺手修改其他执行者拥有的文件。

评论/证据适配器同样需要“实现”:完成合同要求的读取、实验、核验与综合,并把事实、推断、未运行项和证据等级分开;“没有改文件”不等于可以跳过验证。交付评论必须能让新 Session 不读聊天或终端就逐条复核成功条件。

先服从仓库自己的规范、类型系统和风险门,再按改动相关性裁剪下面的通用正确性扫描;低风险改动不需要机械跑完整清单,但任何被跳过的相关维度都要进入验证缺口:

  • 正确性与边界输入:主路径、空值/空集合、上下界、无效输入、编码、时区与精度等是否符合合同;
  • 异步/错误路径:并发、取消、超时、重试、部分失败、回退和错误传播是否保持一致;
  • API 与兼容性:公开接口、配置、序列化格式、schema 与既有调用方是否被有意兼容或迁移;
  • 测试真实性:测试是否真正经过改动路径、能在缺陷存在时失败,并避免只验证 mock、快照或实现细节;
  • IO/数据/迁移:输入输出、持久化、事务、幂等、迁移和回滚是否保全数据;
  • 权限/安全/隐私:授权边界、秘密、日志、敏感数据和最小权限是否守住;
  • 性能/资源:复杂度、延迟、内存、句柄、连接、并发上限和清理是否与使用规模相称;
  • 可维护性:命名、结构、重复、错误可诊断性和必要文档是否让下一位执行者能安全修改。

验证报告使用同一组可恢复字段,至少做到:

  • 发现:按严重度排列可定位、可复查的问题与证据;没有可执行发现时明确写“无”,不让空白承担含义;
  • 能实际运行或检查的改动要真正运行,不用“应该可以”代替;
  • 纯文档、配置或清单类改动,至少做格式、必需字段、相对引用和边界自检;
  • 实际运行:命令或检查、预期结果和真实结果;
  • 未运行:没有执行的相关检查及原因,不用“无”掩盖环境或权限限制;
  • 剩余验证缺口:当前证据尚未覆盖的风险和它对交付结论的影响;
  • 开放问题:需要后续证据、负责人决定或另一个所有者处理的未知;
  • 检查是否产生了范围外的副作用。

不要为了让检查通过而放宽验收条件或改写 Issue 的成功条件。

七、发布合同指定的远端交付物

PR 适配器

  1. 提交前确认改动范围与写入所有权一致,且不包含其他执行者的未提交改动;
  2. 推送到本 Issue 专用的分支;普通交付推送不使用强制更新。已推送分支确因变基需要改写时,只能按 pr-integration 的分支安全链核验同一特性分支和远端旧 head,并使用 lease 保护;lease 拒绝后停止并重新读取远端,不改用无保护强推;
  3. 创建 Draft PR;本 Issue 已有对应 PR 时更新同一个 PR,不再开新的;
  4. 创建或更新后重新读取远端 PR,确认目标分支、当前 head、链接和正文是实际状态。本地命令成功不等于远端合同已经建立。

PR 保持 Draft。本段和交付者都不执行 Draft → ready;唯一执行者是持有当前 PR 整合写入所有权的 pr-integration 执行者,且必须先通过其当前 head、合同、验证、反馈与授权前置门,转换后再重读远端。转换不等于合并授权。不要自行开启自动合并或合并自己的 PR。

评论/证据适配器

  1. 在目标 Issue 发布一条自足交付评论;不得把多条零散进度评论拼成只有原执行者才能解释的结果。
  2. 评论至少逐条对应成功条件,区分事实、推断与未知,并列出证据链接、实际运行、未运行及原因、剩余验证缺口、开放问题和下一责任人。
  3. 发布后重新读取评论,确认稳定 URL、作者、目标 Issue 与正文都是实际远端状态;本地输出或写入响应不能代替该复核。
  4. 合同只要求评论/证据时,不创建空提交或占位 Draft PR;稳定评论 URL 就是交付来源,随后把事实交回 issue-workflow 回收。

八、交付物与 Issue 必须说明什么

PR 正文或评论/证据交付至少包含:

  • 使用安全引用链接对应 Issue,以及父 Issue(如果存在);
  • 实际完成的结果,与 Issue 成功条件的对应关系;
  • 做过的验证:命令或检查、预期、真实结果;
  • 失败项、未执行的检查及其原因;
  • 副作用,包括范围外发现和已经产生的外部影响;
  • 剩余项、已知未知和下一步所有者;
  • 需要负责人决定的内容(如果有)。

入口批尚未落地全局不变量前,PR 正文引用其他 Issue 的规则只引用 objective-to-issues 第三节第 4 项:统一写 关联 #N,不在本段重列或变造规则。评论/证据交付也使用同一安全渲染。

同一批信息要让 Issue 本身可恢复:PR 适配器至少在 Issue 留下指向 PR 的来源,评论/证据适配器以稳定评论 URL 作为来源。不要把交付说明只留在聊天、终端输出或本地文件中。

九、停止、升级与恢复

遇到以下情况停止实现并升级,而不是继续猜测:

  • 需要负责人决定;
  • 需要超出授权的写入或外部操作;
  • 与另一个执行者的范围发生冲突;
  • 达到本次的停止条件。

升级时说明:当前状态、已经存在的交付评论或已推送的分支/提交/Draft PR、已验证和未验证的内容、阻塞点和建议。

中断后恢复:交付状态只从远端 Issue、交付评论、PR 和分支恢复;PR 适配器重新读取当前 head,评论/证据适配器重新读取稳定评论 URL,不假设本地工作区仍然代表远端状态。当前权威、当前授权和负责人的最新明确指令仍按第二节优先,不被 Issue 上的旧记录覆盖。

收到纠偏时先判断它推翻了哪条假设:本 Issue 的结论依赖那条假设,或与受影响范围共享写入时,停止并等待裁决;本 Issue 有独立合同和独立写入所有权、结论不依赖被推翻假设时,继续交付并记录这次判断。不要因为同一批次里另一条分支被纠正就整体停摆。冻结范围的完整判据在 issue-workflow。

十、完成本段

本段完成的判据按合同交付形态唯一确定:

  • PR 适配器:Draft PR 已存在于远端、用安全引用关联对应 Issue、正文说明结果与验证,且分支当前 head 就是被说明的内容;
  • 评论/证据适配器:自足评论已存在于目标 Issue、稳定 URL 可重读、逐条覆盖成功条件与验证缺口,且合同没有要求版本化资产变更。

“实现完成”不等于“验收通过”,也不等于“产品决定成立”。三者不能互相替代。PR 的审查与合并授权、所有交付的任务图更新和父目标重新验收属于下一段。

04 同仓库更多 Skills

zaurakworks
zaurakworks/agent-system

skill-maintenance

创建、审计、修正、拆分、升级、迁移或退役 Skill,或其合同/入口已漂移时,先恢复行为、授权与预算,再同步正文、调用者、版本、生成物和验证。普通业务维护、纯格式修正、承载位置未定的纠正不触发。Use for explicit Skill maintenance, not carrier choice.

★ 1
zaurakworks
zaurakworks/agent-system

skill-appraisal

判定一个 Skill 组该不该进当前装配、归哪些事项、与谁重叠,或对已判定过的组按节拍复核。三种进入:首次判定新候选、补判早已在用但从未判定过的组、按失效条件复核。判定单位是组不是单个 Skill;产出必须留下失效条件与下次最少复核步骤。用于外部来源、他人所写、疑似重复或从未被判定过的组。从零设计新 Skill 用 agent-skill-design;已定下后的改造、迁移、退役用 skill-maintenance;只要外部标准与版本事实用 capability-lifecycle;对象是 knowledge 用 knowledge-maintenance。本 Skill 只产出判定,不安装、不写配置、不改 profile。Appraise a Skill group, or recheck an adopted one. Judgement only, never installs.

★ 1
zaurakworks
zaurakworks/agent-system

self-improvement

当用户指出 Agent 漂移、误解、重复犯错,要求把任务经验固化为系统改进,或讨论只增概念却不减关键未知、形成决定或可检验资产时,只暂停依赖被推翻假设的路径,重锚原问题、持久记录纠正、诊断原因,并在授权内改进入口提示词或 Skill。最小实验不能验收产品交付;普通一次性错误、偏好或任务内修复不触发完整自我优化。Use for reported drift, misunderstanding, repeated mistakes, durable Agent improvement, or abstraction loops without decisions or testable assets. Freeze only affected paths and avoid a full detour for ordinary one-off corrections.

★ 1
zaurakworks
zaurakworks/agent-system

resource-observability

当用户查询 Codex/Claude 账户额度、重置时间、Codex 重置券、单 Session Token,或高成本/多 Agent 工作要决定启动、并行、降级、延后或停止时,按需读取 Orca 账户快照与固定 ccusage 回执,区分状态、来源、可信度和未知值。不要用于低风险任务、轮询、自动调度/消费权益、账单推断或长期保存快照。Use for account capacity, reset times, credits, session tokens, or consequential resource decisions. Skip routine work, polling, scheduling, automatic credit use, billing inference, and durable snapshot storage.

★ 1
zaurakworks
zaurakworks/agent-system

orchestrated-collaboration

当用户明确要求多 Agent/多 Session/跨 Provider 协作、任务已授权委派,或活动 Session 发生共享写入碰撞时,建立目标来源、排他所有权、可追踪交付、独立验收与综合;按共享资源和 Issue 子树确定唯一协调者,只冻结重叠或受推翻假设影响的路径。协调者参与高价值多交付件能力的拆分或设计时,由未参与者复核父目标;使用已选后端,选 Orca 时动态读 orchestration 指南。不要因复杂、额度或空闲 Agent 擅自并行,也不把试用变成长期依赖。Use for authorized multi-agent work, cross-session delegation, or shared-write collisions. Establish exclusive ownership, traceable delivery, independent acceptance, and bounded synthesis; add parent-goal review when required and avoid invented coordination or permanent platform commitments.

★ 1
zaurakworks
zaurakworks/agent-system

knowledge-maintenance

用于多来源调研、可重复实验、会影响权威/Agent 配置/重要决定的研究,或用户要求复用、复核、更新当前知识时:先找已认可知识和失效条件,只补变化、冲突与缺口,再经价值门和可信门更新。不用于低成本一次性事实、原始材料/研发过程留存、私域结构设计、定时全量重查或旧仓导入。Use before multi-source research, repeatable experiments, consequential authority/configuration decisions, or explicit knowledge reuse. Skip cheap one-off facts, raw retention, private architecture, scheduled full re-research, and bulk legacy imports.

★ 1