describe-pr 是一个专注于为当前任务生成或更新拉取请求(PR)描述的 AI 技能。它旨在产出简洁、结构化的 PR 描述,使审阅者能够快速理解变更存在的理由以及实现的整体形态。
用途 该技能的核心用途是:当开发者需要为当前工作分支创建或更新 PR 描述时,通过自动化的方式收集上下文并按照固定模板生成内容,减少手动编写描述的负担,同时保证描述的一致性和信息密度。
主要能力
- 读取预定义的 PR 描述模板({SKILLBASE}/references/pr_description_template.md),并严格遵循模板结构。
- 识别当前分支是否已有 PR,若没有则根据 git 状态和提交记录,在需要时提交任务相关变更、推送分支并创建 PR。
- 收集撰写描述所需的上下文,包括任务票据、完整的 PR diff、周边代码以及 PR 元数据和变更文件列表。
- 按照模板撰写描述,包含“Why the change”(一句话)、“Special things to note”(1-3 条要点)以及受 /show-me 启发的“Change outline”结构视图(如 SQL 表与端点契约变更、文件树、React 组件树、调用树/控制流/数据流变更等),并优先使用 diff 块展示对现有结构的修改。
- 处理会话尾部标记:从环境变量 HUMANLAYER_SESSION_URL 或分支提交记录中获取 HumanLayer 会话链接,若存在则在 PR 正文末尾添加水平线、徽章链接和隐藏的 HTML 注释(包含 HumanLayer-Session: {url}),确保该注释为正文最后一行。
- 将生成的描述保存到指定路径(.humanlayer/tasks/{task-slug}/pr-description.md 或 .humanlayer/tasks/pr-{number}/description.md),并使用 gh pr edit 更新 PR 正文。
- 最后按照指定的最终回答模板报告完成情况,包括 PR URL、保存的描述 URL 和变更文件列表。
使用方式 该技能仅在用户明确按名称调用时使用。调用后,技能会依次执行上述工作流。使用前提是环境中已安装并登录 gh CLI,且当前目录为 git 仓库。如果 gh 缺失或未登录,技能会停止并告知用户,不会尝试绕过。技能还会遵循仓库的 git 安全协议。
适用场景 适用于开发者在完成一项任务后,需要为当前分支创建或更新 PR 描述的场景。尤其适合希望描述保持简洁、结构化,并包含审阅者关键信息的团队。也适用于需要将 HumanLayer 会话链接自动附加到 PR 正文的工作流。
限制
- 仅在用户明确调用时触发,不会自动运行。
- 依赖 gh CLI 和 git 环境,缺少时无法继续。
- 必须存在可用的 PR 描述模板文件,否则无法按模板生成。
- 不会编造会话 URL;当无法获取有效 URL 时不添加尾部标记。
- 描述内容严格限制在模板范围内,不添加走查工件、详尽实现叙述、验证清单、变更日志或计划偏差部分。