Storybook 的 Agent 技能实战用 update-pr-description 技能让 AI 帮你校准 PR 标题与描述【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇围绕 Storybook 仓库中的 Agent 技能文件 update-pr-description/SKILL.md 展开讲解该技能如何通过一套标准化的六步工作流让编码 Agent 对比 PR 的标题/描述与其实际实现commit diff逐条提出并应用修正。读完后你将掌握如何在自己的大型仓库中组织一个核心技能文件 多工具镜像的 Agent 技能体系以及 PR 描述与 CI 流水线之间如何通过 HTML 注释锚点如 canary 区段形成机器可读的协作契约。技能体系定位.claude/skills是指向.agents/skills的镜像层在 Storybook 仓库中AI 编码 Agent 的指令体系遵循 AGENTS.md 中声明的原则This file is the canonical instruction source for coding agents. Files likeCLAUDE.mdshould point here instead of duplicating instructions——即指令以单一来源为准其余文件只做指针。技能skill文件同样采用这一单一来源 镜像策略核心技能定义位于 .agents/skills/ 目录下例如 .agents/skills/update-pr-description/SKILL.md而 .claude/skills/ 目录下的同名文件仅是一行内容直接引用核心文件。以本文主角为例.claude/skills/update-pr-description/SKILL.md 的全部内容就是../../../.agents/skills/update-pr-description/SKILL.md即通过相对路径引用把 Claude Code 的技能入口指向.agents中的权威版本.claude/skills/下的canary、pr、docs-review等 12 个技能目录全部采用相同模式。这样做的收益是技能逻辑只在.agents/skills/中维护一份Claude Code 与通用 Agent 规范共用同一份定义避免两处文档漂移——而 PR 描述本身漂移恰恰是这个技能要解决的问题。Frontmatter技能的元数据与触发语义每个 SKILL.md 以 YAML frontmatter 开头声明技能的名称与触发条件--- name: update-pr-description description: Evaluate a PRs title and description against its actual implementation, then iteratively suggest and apply updates. Use when the user asks to check, fix, or update a PR title or description. ---其中description承担了触发词的角色当用户要求检查、修正或更新 PR 标题/描述时Agent 应加载该技能。作为对照同目录下的 canary 技能 还额外声明了allowed-tools: Bash说明 frontmatter 也用于约束技能可用的工具集。六步工作流从证据采集到代用户提交技能的主体是一个明确的六步流程核心思想是先取证、再比对、最后才动笔全程以ghCLI 为操作界面。第 1 步定位目标 PRResolve优先使用用户提供的 PR 编号或 URL若用户未提供则用gh pr view反查当前分支对应的 PRgh pr view # 查看当前分支关联的 PR这一步保证了后续所有操作都锚定在正确的 PR 上而不是凭分支名猜测。第 2 步采集三类证据Gather evidence技能要求并行采集三类相互独立的证据分别回答声称了什么与实际做了什么# 1) PR 的标题与正文声称的内容 gh pr view pr --json title,body # 2) 提交历史实际做了什么按 commit 粒度 gh pr view pr --json commits # 3) 相对 base 分支的完整 diff实际改动的最终形态 gh pr diff pr值得注意的是技能特意区分了commits与diffcommit message 反映的是开发过程中的阶段性意图可能包含已被推翻的中间提交而gh pr diff给出的是合并前相对 base 的最终净改动。只比对其中任何一个都可能误判。第 3 步评估实质性偏差Evaluate divergence这是技能中最体现判断力的步骤。技能明确区分了值得标记的偏差与应忽略的差异只标记 meaningful divergence实质性偏差范围错误wrong scope、遗漏重大改动missing major changes、过时陈述stale claims、不准确的总结inaccurate summary忽略 trivial wording琐碎措辞差异措辞风格、形容词选择等不影响信息准确性的差异不触发修改。这一条实际上是在给 Agent 设定克制度PR 描述是写给维护者看的工程沟通文档不是文学文本Agent 的职责是纠正事实性偏差而非润色文风。第 4 步汇报并设置早退出口Report技能要求 Agent 先向用户报告标题和/或描述是否存在实质性偏差并且如果没有偏差到此为止If not, stop here。这个显式的早退分支很关键——它防止 Agent 为了展示能力而对一个本来准确的描述强行重写与后文 Notes 中的Do not rewrite a description thats already accurate形成呼应。第 5 步逐条迭代建议Suggest iteratively若存在偏差技能规定采用一次只提一个变更的协商节奏提出具体的更新后标题/描述Propose concrete updated title/description每次只就一处变更征询用户是否应用Ask the user one change at a time接受用户的编辑与进一步修正循环精炼accept edits, and refine。这种小步提交式的对话设计使每次修改都可被独立审查避免 Agent 一次性提交整篇重写稿让用户难以逐条判断。第 6 步代用户应用Apply用户同意后Agent 通过单条gh命令完成提交gh pr edit pr --title ... --body ...至此技能闭环完成读取gh pr view/gh pr diff→ 判断 → 协商 → 写回gh pr edit。Notes 四原则与 Storybook PR 模板的机器级契约技能末尾的 Notes 部分看似简短实则是与仓库 PR 模板 深度耦合的约束规则逐条展开1. 匹配仓库既有模板风格Match the repositorys existing PR template/styleStorybook 的 PR 模板 .github/PULL_REQUEST_TEMPLATE.md 有严格的分区结构Closes #关联 issue 编号多 issue 需拆分列出## What I did变更摘要Checklist for Contributors自动化测试覆盖stories / unit tests / integration tests / end-to-end tests 四个复选框强制性的 Manual testing 小节模板明确标注 This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitlyChecklist for MaintainersCI 沙箱标签ci:normal/ci:merged/ci:daily对应沙箱集合定义在 code/lib/cli-storybook/src/sandbox-templates.ts、QA 标签qa:needed/qa:skip、以及必选的类别标签bug、maintenance、dependencies、build、cleanup、documentation、feature request、BREAKING CHANGE、otherCanary release 区段与Benchmark 区段由 HTML 注释锚点占位。Agent 在重写描述时必须保留这套骨架只填充内容不改变结构。2. 不重写已经准确的描述Dont rewrite a description thats already accurate与第 4 步的早退逻辑一致属于幂等性约束技能的最终状态是描述与实现一致而非描述被我改过。3. 同步更新复选框状态Update the state of checkboxes where appropriatePR 正文中的- [ ]复选框是维护者流程的输入。典型场景PR 初开时 Manual testing 步骤缺失Agent 补齐步骤的同时把对应的测试覆盖项从- [ ]改为- [x]。这与模板填写章节、保留注释的约定put an x inside the [ ]配合。4. 填充章节时删除占位符/提示注释Remove section placeholders/reminders when filling out a section模板中大量使用 HTML 注释作为给人类贡献者的填写提示例如!-- Briefly describe what your PR does --。当 Agent 实际填写了某章节后应删去对应提示注释避免说明文字与填写内容并存的冗余。5. 绝不删除 canary release 区段Do not remove the canary release section这是 Notes 中唯一一条禁止性规则其背后有直接的工程原因可以从发布流水线得到验证。在 publish.yml 的publish-canary作业中canary 发布完成后有一个 Replace Pull Request Body 步骤使用ivangabriele/find-and-replace-pull-request-body动作以CANARY_RELEASE_SECTION这一 HTML 注释作为定位锚点把整个区段替换为发布结果见 publish.yml#L380-L405- name: Replace Pull Request Body uses: ivangabriele/find-and-replace-pull-request-body... with: githubToken: ${{ secrets.GH_TOKEN }} prNumber: ... find: CANARY_RELEASE_SECTION isHtmlCommentTag: true replace: | This pull request has been released as version 0.0.0-pr-PR_NUMBER-sha-SHORT_SHA. Try it out in a new sandbox by running npx storybookVERSION sandbox ...也就是说模板中包裹 canary 说明的成对注释!-- CANARY_RELEASE_SECTION -- ... !-- CANARY_RELEASE_SECTION --是 CI 与 PR 正文之间的机器可读接口流水线发布 canary 版本版本号格式为0.0.0-pr-PR_NUMBER-sha-SHORT_SHA由 publish.yml#L365-L372 的yarn release:version --exact步骤确定后依赖这对锚点原地注入版本号与npx storybookVERSION sandbox/upgrade的试用命令。一旦 Agent 在校准描述时把这个区段当作未填写的模板残留删掉后续所有 canary 发布的 PR 回写都会静默失效。同理模板末尾的BENCHMARK_SECTION注释也承担类似职责。这条规则因此可以从一般性的谨慎编辑升格理解为PR 描述不仅是给人读的文档还是 CI 系统写入结果的挂载点编辑 Agent 必须把锚点注释视为不可变结构。兄弟技能update-pr-description 在 PR 生命周期中的位置从 .agents/skills/ 下的技能集合看update-pr-description并非孤立工具而是 Storybook PR 流水线上开 PR → 发 canary → 校准描述链条的一环技能文件职责与本文技能的关系prSKILL.md定义 PR 标题格式[Area]: [Description]如CSFFactories: Fix type export与三类必选标签category/CI/QA要求逐字复制模板并保留全部 HTML 注释定义了描述应该长什么样是本文技能评估偏差时的风格基准open-prSKILL.md从当前分支开 draft PR自动探测 base 分支支持 stacked PR、按模板填正文、创建后主动询问是否发 canary开 PR 阶段产出第一版描述后续可能随代码演进偏离实现canarySKILL.md通过gh workflow run --repo storybookjs/storybook publish.yml --field prPR_NUMBER触发 canary 发布并说明如何从 PR 正文中读取发布版本号canary 发布会改写 PR 正文的 canary 区段进一步提高了编辑描述不得破坏锚点的必要性update-pr-descriptionSKILL.md本文主角比对标题/描述与实际实现迭代式修正在 PR 生命周期中任何时点新增 commit、rebase、拆分合并后都可触发兜底保证描述不失真可以看到一个清晰的设计思路pr/open-pr技能保证开 PR 时描述是模板化、准确的canary技能保证发布时CI 能写回 PR而update-pr-description保证整个迭代过程中描述持续与实现同步。三者共同依赖同一个契约文件 .github/PULL_REQUEST_TEMPLATE.md以及其中不可删除的注释锚点。可迁移的实践要点从这个技能中可以提炼出若干对任意大型仓库都有参考价值的做法技能文件用证据驱动而非模板驱动编写。流程的每一步都绑定可执行命令gh pr view --json、gh pr diff、gh pr editAgent 的每个判断都有数据源而不是凭上下文感觉PR 描述写得对不对显式定义不做什么。只标记实质性偏差已准确则不重写逐条协商等约束比步骤本身更能决定技能的实际效果它们共同压制了 LLM 常见的过度改写倾向单一来源 镜像引用.claude/skills/一行指针 →.agents/skills/权威文件让多 Agent 工具生态共享同一份技能定义文档锚点即接口CANARY_RELEASE_SECTION这类 HTML 注释让 PR 正文同时服务人类阅读与 CI 程序化改写任何自动编辑流程都必须把保留锚点列为硬约束——这正是 update-pr-description/SKILL.md 最后一条 Note 存在的原因。综合来看update-pr-description 技能 的价值不仅在于帮人改 PR 描述更在于它示范了如何在 Storybook 这样的工程仓库中把 PR 正文当作一份同时面向人与 CI 的可执行文档来治理模板定义结构注释锚点定义机器接口Agent 技能则负责在整个 PR 生命周期内维持内容与实现的持续一致。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考