用途
describe-pr 是一个仅在用户明确按名称调用时才使用的技能,用于为当前任务创建或更新 Pull Request 描述。目标是写出简洁说明,帮助审查者理解改动存在的原因以及实现的整体形态。
主要能力
- 读取 PR 描述模板({SKILLBASE}/references/pr_description_template.md)并严格按其结构撰写正文,不扩展模板之外的内容。
- 识别或创建 Pull Request:通过
gh pr view --json url,number,title,state,baseRefName,headRefName检查当前分支是否已有 PR;若无,则检查git status --short --branch与当前分支提交,必要时提交任务相关改动、推送带上游的分支并创建 PR。 - 收集解释改动所需的上下文:读取工单及相关任务产物、完整的 PR diff 与足够的周边代码、PR 元数据与变更文件,并参考 show-me 的视觉大纲约定。
- 按模板撰写描述:“Why the change”恰好一句话;“Special things to note”1-3 条要点,优先提示审查者警告、迁移、兼容性约束、有意省略或意外决策,无特殊情况时写
- None.;“Change outline”采用紧凑的结构化视图,而非散文或逐文件变更日志,仅保留有助于说明本次 PR 的视图,例如 SQL 表与接口契约变更及业务逻辑伪代码、展示职责变化的浅层文件树、含重要 hooks、状态和包边界的 React 组件树变化、调用树/调用栈/控制流/数据流变化等;展示既有形态的改动时优先使用 diff 块,当大部分为新内容或 diff 会掩盖归属与顺序时展示完整目标形态。 - 添加会话页脚:从环境变量
HUMANLAYER_SESSION_URL读取会话深链,若为空则回退到分支提交中的humanlayer-session:尾注取最新 URL;有 URL 时在正文末尾添加由水平分隔线、链接到该 URL 的 HumanLayer | open session 徽章以及一行内容恰为HumanLayer-Session: {url}的隐藏 HTML 注释组成的页脚;均无 URL 或已有同 URL 尾注时不添加,且不得虚构或猜测 URL。 - 保存并发布:任务目录存在时使用
.humanlayer/tasks/{task-slug}/pr-description.md,否则使用.humanlayer/tasks/pr-{number}/description.md,再通过gh pr edit {number} --body-file {output-path}更新 PR,并确认更新成功。 - 报告完成:简要读取关键任务产物以获取其云端 URL,按最终答复模板回复 PR URL、已保存描述 URL 与简洁的变更文件列表。
使用方式
在需要为当前任务撰写或更新 PR 描述时,由用户明确点名调用该技能。技能会自行检查 gh 登录状态与分支 PR 情况;仅当当前分支没有相关工作且没有可安全创建的当前分支 PR 时,才请用户选择 PR。
适用场景
适用于已有或即将创建的 Pull Request 需要一份结构化、面向审查者的简洁描述,尤其在意说明改动动机、实现形态、调用与数据流变化、组件树变化以及需要特别注意的迁移或兼容性事项时。
限制
- 仅在用户明确按名称调用时使用。
- 若
gh缺失或未登录,必须停止并告知用户,不得绕过。 - 必须始终读取并遵循 PR 描述模板,不得超出模板扩展正文。
- 不添加 walkthrough 产物、详尽实现叙述、验证清单、变更日志文本或计划偏差章节。
- 会话页脚属于归属信息,不混入正文的散文、标题和链接行;不得虚构会话 URL。
- 描述需以简单、连贯、简洁的语言撰写,像人与人之间交流一样,避免术语和俚语。