ce-skill-work

CE 技能工作

此仓库中的技能定义的是目标，而不是状态机。技能会告知 Agent 目标、完成条件、安全的失败方向，以及它无法从眼前的仓库中推导出的事实，然后便不再干预。此技能所做的一切——编写、编辑、审查、回应审查——都是将同一标准应用于不同的起始状态。

**结果：**你接触的技能文件应阐明条件，而非枚举情况；不包含任何不会改变行为的内容；并将每种机制放在负责它的层级；此外，变更应根据其风险进行相应验证。

**完成：**已编写该模式的完成报告，并已运行验证（或记录确切的跳过原因）。写好一句话不算完成；只有在负责该问题的层级以最精简的机制弥补了经证实的缺口，才算完成。

**非目标：**缩短文件。精简是阐明条件的副作用；应报告变更内容，而非字数。

标准（使用任何模式前阅读）

docs/solutions/skill-design/portable-agent-skill-authoring.md 是权威依据。阅读下方模式指定的章节；不要在你正在编辑的技能中复述该指南。项目当前生效指令中的常驻规则是对它的补充；若有更具体的规则，以更具体的规则为准。

每个区块都从相同的可能要素开始，顺序如下：结果和下一个使用者、技能层级标准无法保障的任何本地完成检查、安全的失败方向、无法推导出的事实，最后才是结果本身无法保障的任何协议。如果某个区块不需要其中某项，就省略它。绝不能用一份案例清单代替本可阐明的条件，也不能规定此技能委派出去的工作应采用何种机制——这正是要指出的问题。此技能负责的具体操作流程，或是遗漏某项便会悄然导致覆盖不足的选项菜单，属于协议，应予以保留。

适用于所有模式的规则

• 条件，而非情况。 如果你发现自己在一条规则后面加上“以及 X 时”，就说清楚 X 代表什么条件，并直接写明。需要枚举各种情况的规则，表述就是错的。
• 只在本技能负责的范围内规定机制。 命令、退出码和状态转换属于负责该机制的技能（ce-commit-push-pr 负责检测 PR），或属于成本低且确定的工作。委派型技能应说明条件、安全方向，以及无法推导出的被调用方事实。
• 先清理沉积物。 在向一个区块添加内容前，先删除标准规定不应存在的内容。来源决定要查得多仔细，而非决定内容去留：查找断言该行的测试、记录该内容的 docs/solutions/ 学习记录，或为修复某个明确 bug 而添加该行的提交。找到来源 → 该行是在保护某项内容；除非使用方已不存在，否则就保留，并说明它保护什么。未找到 → 按准入标准处理（它是否陈述了可证伪的约束、纠正了已证实的倾向，或提供了无法推导的事实？）；如果某行可能是在为较弱的模型或其他 harness 提供保险，应先验证再删，而不是想当然。说明哪些删除是基于缺乏证据。
• 删除每条强制要求时，都要说明现在由什么来决定。 如果答案是“由模型自行决定是否执行某个必需步骤”，那么这条强制要求就是必需的关卡，应予以保留。删除“必须”一词，并不会消除这项决策。
• 一行内容只有在以下情况下才值得保留： 陈述可证伪的约束、纠正已证实的默认倾向，或提供 Agent 无法推导的事实。独立指令后面的理由、描述投入程度的措辞，以及重复说明能力，都不值得保留。
• 面向用户的调用按 harness 规范呈现——规则及其位置见项目的有效指令（“User-Facing Skill Invocations”）；凡是技能会打印或复制调用内容之处，都要遵循该规则。
• 描述是上下文指针。 对于由模型调用的技能，每轮中 frontmatter 都会进入上下文窗口，且比正文更容易被裁剪。第一句应点明独特机制（同类技能不会产出的内容），并以引导提示词开头。之后，每个真正不同的分支各写一条正向触发条件，采用“Use when...”或“Use for...”形式，并描述可观察到的工作状态。优先使用“Use for ”；只有当相同措辞会触发两个技能时，才保留“Not for”。如果技能用于错误任务会造成危害，就在描述中写明“Use only when”或“Skip when”。身份套话、同一分支的网站／同义词／能力清单、由模型调用的技能中的引述语句和斜杠名称堆砌、工作流、标志及阶段清单，都应移出描述。可以保留独特的工作方式。引述语句和 /name 别名只能放在由用户调用或设置了 disable-model-invocation 的技能中，并且要放在机制说明之后。
• 先明确一个完成标准。 每项技能都需要一个技能级别的完成条件。只有在跳过检查可能导致不安全操作、脆弱的状态转换、范围扩大、变更、授权错误或静默交接失败时，才添加本地完成检查。
• 为当前强模型编写精简提示词。 每条指令只写一次。如果一条简短指令能决定一类行为，就用它代替逐条枚举行为。如果两套操作步骤共享相同的命令骨架，就写一套带参数或差异项的步骤；若骨架相同，重复完整命令就是缺陷。
• 使用朴素句式；通过结构而非句法节省篇幅。 用普通英语表达，每句一个意思。在需要时说明由谁采取行动、做什么，以及为何重要。将自创标签和内部工作流行话替换为其所指的行动或后果；保留必要的技术术语，并在读者需要时解释不熟悉的术语。谨慎的工程师需要读两遍的句子——用破折号拼接从句、省略冠词和连接词、将三条规则塞进一句话——即使能省字数，也仍是缺陷，而且会影响 Agent 面向用户时的语气。正文需要缩短时，应将连贯的内容块移至其使用位置所指向的参考文档，或删除真正冗余的内容；绝不要靠压缩措辞来凑字数，并应留出余量，避免下次修复时无处可删。
• 本组织多模型技能优先采用 Sol 方案以确保可移植性。 当 Fable 关于删减步骤或添加简洁性要求的指导，与 Sol 关于保留已验证有效的命令、必需的报告内容或不添加一刀切简洁口号的指导冲突时，采用 Sol 形式。对 Fable 而言，指令稍多但清晰可以接受；省略 Sol 关键的确定性要求则不可接受。真正的噪声仍应删除。
• 可移植的长度控制要保留内容。 跨模型技能中绝不要加入一刀切的“简洁点”／“保持简短”口号。应说明简短报告必须包含什么、可以省略什么；对于 CLI 封装器，应保留命令、退出状态、输出路径／大小，以及 stderr 或阻塞因素。
• 长时间运行的技能要说明节奏。 负责长循环或调度工作线程的技能，应说明批处理方式（在同一回复中发出相互独立的调用和调度；仅在确有依赖时串行执行）、进度说明（用户在开始、过程中和结束时会看到什么），以及如实说明完成情况（只有实际执行后步骤才算完成；不能仅描述了尚未完成的工作就结束本轮）。只运行少量调用并返回的技能，不需要包含这三项——参见指南中的长时间运行执行章节。
• 将自主性合并为一项精简策略。 指明安全的本地操作，并允许继续执行用户请求所涵盖的工作，包括属于所请求任务或技能授权范围内的外部写入操作。只有当外部写入、破坏性操作、购买或实质性范围扩展超出该授权范围，或只有用户才能提供所需输入时，才请求确认。不要在每个步骤中重复“先询问”“不要更改”或“等待批准”。
• 根据脆弱程度匹配自由度。 有多种有效做法时，给予较高自由度；存在首选模式或参数化命令时，给予中等自由度；只有一条已验证有效的命令或序列，且 Agent 自行编写就会出错时，给予较低自由度。将脆弱命令完整写一次；将简单变体合并为一套骨架加差异项。
• 按风险进行验证。 每次编辑后，运行 bun run test:skill-guards，它会在约一秒内运行机械检查，包括 tests/codex-skill-prompt-budget.test.ts 中对 8,000 字节 SKILL.md 的预算检查。机械契约（frontmatter、路径、可 grep 的不变量）应放入 bun test。承载行为的正文发生变化时，应按照 references/evaluate.md 针对 Claude 和 Codex 进行定向评估，或在报告中明确说明跳过理由。绝不要将未经测试的行为更改作为“参考”发布。

模式

根据要求选择模式；一个请求可以串联多种模式（例如，将审查转为编辑）。

你的角色	阅读	完成条件
创建新技能	references/new-skill.md	在编写任何工作流之前，先明确结果主线；写好激活场景；更新仓库清单；并运行评估，或记录确切的跳过原因
更改现有技能	references/edit-skill.md	修改的内容块符合标准；不存在与你的修改相矛盾的内容；并已运行验证
审查技能变更	references/review-skill.md	每条发现都归为 Change / Verify / Consider，并附上该类别要求的证据；每条 Change 都指出具体条件或应由哪一层负责处理
根据技能审查反馈采取行动	references/respond-to-review.md	每项都有结论；每条 Change 都在其所属层级弥补了缺口；且没有重复修补任何内容块

完成报告

每种模式结束时都要提交与该模式相符的报告。会修改内容的模式（new、edit、respond）：逐个列出修改过的内容块，说明其现在表达的目标、删除了什么及其来源核查结果；说明哪些内容有意未达到标准，以及为何不在范围内；说明运行了哪些验证及其结果，或记录确切的跳过原因；说明任何可能实质性改变技能约定但你没有作出的决定。**审查模式：**按类别列出发现及其所附证据；如果调用方提供了摘要通道，还要列出你检查过的路径，以确认重述仍然有用，并说明哪些内容无法核实。报告应发送到调用方指定的通道；如果调用方只接受发现列表，该列表本身就是报告，足以满足完成条件。审查不会修改内容，因此绝不会包含已修改内容块的条目。