大模型/agent提交pr时可用的skill前言问题这个 Skill 解决的几个问题skill文件正文前言问题最近在让 Codex 帮我整理 PR 说明时我反复遇到一个很有意思的问题它要么写得太短为了把文章写的短用了一堆奇怪的ai味压缩语法或者干脆把必要的因果关系也压缩掉要么为了追求完整为了复杂而复杂把调查过程中掌握的各种细节全部塞进去最后反而抓不住重点或者干脆写的偏离了我们提pr时想表达的解决掉的问题。也就是说“太长”或“太复杂”通常不是字数问题而是结构问题它没有抓住重点所以解释范围过大因果主线没有先出现背景知识出现得太早多个根因混在一起比喻和代码没有共用同一套角色。因此当我们说“太复杂”时不能让他机械的删字和精炼我们觉得他写的太短时也不能只让他机械扩写。也就是说它不需要过分复杂复杂不是目标也不需要为了简单过分简短短不是目标它写的应该足够精准。比如一个补丁真正需要向维护者说明的可能只是哪里有问题为什么会出现这个问题修改了什么什么证据说明这个修改有效。如果这四件事情本身讲得足够准确文章往往自然就会变得简洁、清楚而且不会丢失必要信息。同时我理解的“精准”是只保留维护者理解和判断这个具体修改所必需的信息同时把每个必要的信息解释到刚好足够。不是少写也不是多写而是只写真正需要写的东西并把它说准确。这个 Skill 解决的几个问题抓主线不乱扩展背景不为了短而压缩不为了完整而穷举证据证明到哪里结论写到哪里不重复解释已经自解释的信息。用自然、直接的工程语言表达避免模板化、证明式和防御式的“报告腔”。skill文件正文--- name: explain-patch description: Write or revise a precise maintainer-facing explanation of a concrete code change. --- # Explain Patch Write as the engineer who made the patch to the maintainer reviewing it. Before drafting, identify the one thing the explanation must establish: problem → why it happens → change → decisive verification This is the spine. Every sentence should either support this spine or help the maintainer judge the change. 1. Lead with the concrete code path, behavior, and change. Do not begin with generic background. 2. Be precise, not intentionally short or exhaustive. Explain each necessary point once, with enough detail to understand it. 3. Prefer concrete code entities, ordinary technical verbs, and observed results over abstract, formal, or defensive framing. State what happened directly. 4. Explain background only when it is required to follow the spine. Introduce a prerequisite before relying on it. 5. Do not claim more than the evidence establishes. 6. State the relevant scope positively. Do not enumerate everything the patch does not change or disclaim claims that were never made. 7. Do not explain what is already self-evident from the code, data, or table. Present the evidence and state its decision-relevant takeaway once. Use the smallest structure that communicates the change clearly. Do not add sections merely to make the explanation look complete. Before finishing, ask: - Can the maintainer explain why this change is needed, what changed, and why it should work? - Does every paragraph help review this patch? - Is anything important repeated? - Is any claim stronger than its evidence? - Am I explaining something the maintainer can already see? - Am I defending against a concern or claim that the patch never raised? 大模型/agent在github提交pr时可用的skill
大模型/agent提交pr时可用的skill前言问题这个 Skill 解决的几个问题skill文件正文前言问题最近在让 Codex 帮我整理 PR 说明时我反复遇到一个很有意思的问题它要么写得太短为了把文章写的短用了一堆奇怪的ai味压缩语法或者干脆把必要的因果关系也压缩掉要么为了追求完整为了复杂而复杂把调查过程中掌握的各种细节全部塞进去最后反而抓不住重点或者干脆写的偏离了我们提pr时想表达的解决掉的问题。也就是说“太长”或“太复杂”通常不是字数问题而是结构问题它没有抓住重点所以解释范围过大因果主线没有先出现背景知识出现得太早多个根因混在一起比喻和代码没有共用同一套角色。因此当我们说“太复杂”时不能让他机械的删字和精炼我们觉得他写的太短时也不能只让他机械扩写。也就是说它不需要过分复杂复杂不是目标也不需要为了简单过分简短短不是目标它写的应该足够精准。比如一个补丁真正需要向维护者说明的可能只是哪里有问题为什么会出现这个问题修改了什么什么证据说明这个修改有效。如果这四件事情本身讲得足够准确文章往往自然就会变得简洁、清楚而且不会丢失必要信息。同时我理解的“精准”是只保留维护者理解和判断这个具体修改所必需的信息同时把每个必要的信息解释到刚好足够。不是少写也不是多写而是只写真正需要写的东西并把它说准确。这个 Skill 解决的几个问题抓主线不乱扩展背景不为了短而压缩不为了完整而穷举证据证明到哪里结论写到哪里不重复解释已经自解释的信息。用自然、直接的工程语言表达避免模板化、证明式和防御式的“报告腔”。skill文件正文--- name: explain-patch description: Write or revise a precise maintainer-facing explanation of a concrete code change. --- # Explain Patch Write as the engineer who made the patch to the maintainer reviewing it. Before drafting, identify the one thing the explanation must establish: problem → why it happens → change → decisive verification This is the spine. Every sentence should either support this spine or help the maintainer judge the change. 1. Lead with the concrete code path, behavior, and change. Do not begin with generic background. 2. Be precise, not intentionally short or exhaustive. Explain each necessary point once, with enough detail to understand it. 3. Prefer concrete code entities, ordinary technical verbs, and observed results over abstract, formal, or defensive framing. State what happened directly. 4. Explain background only when it is required to follow the spine. Introduce a prerequisite before relying on it. 5. Do not claim more than the evidence establishes. 6. State the relevant scope positively. Do not enumerate everything the patch does not change or disclaim claims that were never made. 7. Do not explain what is already self-evident from the code, data, or table. Present the evidence and state its decision-relevant takeaway once. Use the smallest structure that communicates the change clearly. Do not add sections merely to make the explanation look complete. Before finishing, ask: - Can the maintainer explain why this change is needed, what changed, and why it should work? - Does every paragraph help review this patch? - Is anything important repeated? - Is any claim stronger than its evidence? - Am I explaining something the maintainer can already see? - Am I defending against a concern or claim that the patch never raised?