用途
to-pr 用于为当前任务创建或更新 Pull Request 的描述。它的目标是让审查者快速理解变更为什么存在,以及实现的大致形态。适用于每次打开 Pull Request 或需要重写其描述的场景。
主要能力
- 读取 PR 描述模板({SKILLBASE}/references/pr_description_template.md),并严格按模板撰写,不超出模板范围。
- 识别或创建 Pull Request:通过 gh pr view 检查当前分支是否已有 PR;若没有,则检查 git status 与当前分支提交,必要时提交任务相关变更、推送分支并创建 PR。
- 收集解释变更所需的上下文:读取工单和相关任务产物、完整 PR diff 及足够的周边代码、通过 gh pr view 收集 PR 元数据和变更文件。
- 按模板撰写描述:Why the change 恰好一句话;Special things to note 保持 1-3 条要点,优先写审查者警告、迁移、兼容性约束、有意省略或意外决策,无特殊事项时写 - None.;Change outline 采用紧凑的、受 /show-me 启发的结构化视图,而非散文或逐文件变更日志。
- Change outline 只包含有助于解释本 PR 的视图:SQL 表与端点契约变更及业务逻辑伪代码、关键数据结构/类型变更、展示变更职责的浅层文件树、React 组件树变更(含重要 hooks、state 和包边界)、调用树/调用栈/控制流/数据流变更。展示已有形态的变更时优先用 diff 块;当大部分是新增或 diff 会掩盖归属与顺序时展示完整目标形态。省略未变更的类别。
- 以 Things to be aware of 作为最后一节,涵盖“变更之外”的内容:独自做出的决策、意外情况、不在本 PR 中的内容、后续事项,每项标记为工单、维护者待办或无需处理。保持四行,空行后写 None.,让读者知道已考虑过。Special things to note 仍聚焦变更本身。
- 用 Closes #n 链接本 PR 完成的工单;对仍需维护者试用(QA)的工单用 Refs #n,避免合并时提前关闭。
- 可选:若知道工单 id/url、相关计划/文档 url 或其他相关链接,可加入头部,否则省略头部。
- 保存并发布描述:保存到 .scratch/pr-{number}/description.md(.scratch/ 已被 gitignore,GitHub 保存已发布的描述,因此保存或重写不会产生待提交内容),再用 gh pr edit {number} --body-file {output-path} 更新 PR,并确认更新成功。
- 报告完成:读取 {SKILLBASE}/references/describe_pr_final_answer.md,按该最终答案模板回复 PR URL、保存的描述路径和简洁的变更文件列表。
- 为每个变更文件生成两个审查链接,基于推送后 PR 的 head commit(gh pr view {number} --json url,headRefOid,files),使更新后的 PR 链接到新的 head。从 PR url 取 {owner}/{repo}:最终版本为 https://github.com/{owner}/{repo}/blob/{headRefOid}/{path};diff 为 {pr_url}/files#diff-{hash},其中 {hash} 是路径的 SHA-256(printf %s '{path}' | shasum -a 256,Linux 上用 sha256sum)。变更文件很多时,链接关键文件并按路径列出其余文件。
使用方式
该技能按工作流执行:先读取描述模板,再识别或创建 PR,收集上下文,按模板撰写描述,保存并发布,最后报告完成。撰写时以一个人对另一个人说话的方式书写,避免行话和俚语,使用简单、连贯、简洁的语言。提及 issue 或 pull request 时用其标题而非仅编号,例如 #12 Add login,而不是 #12,这在标题、正文和告知用户的内容中都适用。
适用场景
- 打开新的 Pull Request 时。
- 需要重写已有 Pull Request 的描述时。
- 需要为审查者提供结构化变更概览(如 SQL、数据结构、文件树、React 组件树、调用流等)时。
限制
- 必须始终读取并遵循 {SKILLBASE}/references/pr_description_template.md,不得将 PR 正文扩展到该模板之外。
- 仅当当前分支没有相关工作且没有可安全创建 PR 的当前分支 PR 时,才让用户选择 PR。
- 遵循仓库的 git 安全协议。
- 关于收费、价格、平台支持范围等信息,资料中暂未提供。