Storybook open-pr 技能解析：AI Agent 按仓库约定自动发起 Pull Request 的完整工作流

Storybook open-pr 技能解析AI Agent 按仓库约定自动发起 Pull Request 的完整工作流【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本篇指南基于 Storybook 仓库中的.claude/skills/open-pr/SKILL.md该文件是指向 open-pr 技能 的引用指针展开完整拆解这一 AI Agent Skill 的六步工作流从 Git 上下文收集、基础分支自动检测、标签交互询问到基于 PR 模板 的正文填充、gh pr create草稿 PR 创建以及可选的 canary 发布。读完后你能理解该技能如何通过一个 Shell 脚本 支持 stacked PR 场景的基础分支推断并能参照同样的约定为自己的仓库设计 PR 自动化技能。技能定位与元数据open-pr是 Storybook 仓库内置的一套面向 AI Agent如 Claude Code的技能定义。技能文件位于 .agents/skills/open-pr/SKILL.md而.claude/skills/open-pr/SKILL.md中仅有一行../../../.agents/skills/open-pr/SKILL.md——这是 Claude Code 的引用指针语法让.claude/skills/目录下的技能直接复用.agents/skills/中的单一事实来源避免两份内容各自维护。技能的 YAML frontmatter 声明了它的身份与权限边界name: open-pr description: Opens a pull request from the current branch using the PR template. Use when the user asks to open a PR, create a pull request, or invokes /open-pr. allowed-tools: Bash, Read, AskQuestion三个字段各承担一个职责name技能注册名用户可通过/open-pr直接唤起description触发条件的自然语言描述Agent 依据它判断用户请求open a PR / create a pull request是否命中该技能allowed-tools工具白名单。本技能只允许Bash执行 git/gh 命令、Read读取 PR 模板、AskQuestion向用户询问标签没有写文件的权限——这与 canary 技能 只允许Bash的设计一致最小权限原则贯穿整套技能。技能的整体目标是从当前分支、遵循 Storybook 约定地开出一个草稿 PR。它和 pr 技能 是配套关系pr技能定义 PR 标题格式、三类标签的完整语义与 PR 正文撰写规范open-pr则负责把这套约定落成一次可执行的六步流程并在需要时跳转到 canary 技能。工作流总览六步流程SKILL.md 将整个过程编排为六个阶段Gather context——收集 Git 上下文Detect base branch——检测基础分支Ask for labels——交互式询问三类标签Draft title and body——起草标题与正文Create the PR——创建草稿 PRReport and offer canary——汇报结果并询问是否发 canary。以下按阶段展开并深入关键脚本的源码实现。第 1 步并行收集 Git 上下文技能要求并行运行以下命令以掌握当前分支状态git status git diff git log --oneline base...HEAD # base 在第 2 步确定后补跑 git branch -vv其中git branch -vv显示各分支的 upstream 跟踪关系为后续 base 检测提供线索git log --oneline base...HEAD的三点语法列出当前分支相对 base 分叉点的全部提交用于判断 PR 实际包含哪些改动。若当前分支尚未推送到远端需要先执行git push -u origin HEAD-u参数会同时建立 upstream 跟踪——这正是第 2 步 base 检测第一优先级信号tracked upstream的来源。第 2 步基础分支检测核心算法确定 PR 应合并到哪个分支是 Storybook 多分支协作模式的难点。仓库采用main当前版本线与next开发线双 trunk 结构且 PR 模板 明确要求除当前版本专属修复外所有 PR 提交到next分支。但仅默认next不足以覆盖 stacked PR在一个已开 PR 的功能分支上再开一层 PR的场景。技能给出的命令是git fetch origin bash .agents/skills/open-pr/scripts/detect-base-branch.shdetect-base-branch.sh 的完整检测策略可以从源码逐段验证它按三级优先级依次尝试并带有一组严格的合法性校验与平票裁决规则。优先级 1tracked upstream第 99–102 行# 1. Tracked upstream (set when branching with -u or --track) if upstream$(git rev-parse --abbrev-ref {upstream} 2/dev/null); then try_explicit_base ${upstream} figit rev-parse --abbrev-ref {upstream}取当前分支显式跟踪的远端分支第 1 步的git push -u或带-u建分支时设置并归一化掉origin/前缀后作为候选 base。优先级 2reflog 中的 checkout 来源第 104–116 行当没有 upstream 时脚本解析当前分支的 reflog用正则匹配最近一次checkout: moving from X to 当前分支或branch: Created from X记录if [[ ${line} ~ checkout:\ moving\ from\ (.)\ to\ ${current_branch} ]]; then try_explicit_base ${BASH_REMATCH[1]} break fi if [[ ${line} ~ branch:\ Created\ from\ (.) ]]; then try_explicit_base ${BASH_REMATCH[1]} break fi这覆盖了从feature/foo直接git checkout -b feature/bar这类未设置 upstream 的 stacked PR 场景。优先级 3扫描全部 origin/* 分支取最近的严格祖先第 118–131 行前两级都落空时脚本用git for-each-ref --format%(refname:short) refs/remotes/origin/枚举所有远端分支逐一评估以git rev-list --count origin/$1..HEAD统计候选分支到 HEAD 的提交数提交数最少的严格祖先胜出——这实现了支持 stacked PR而非只支持 main/next的目标。合法性校验 is_valid_base第 30–41 行一个分支要成为有效 base 必须同时满足四个条件任何一条不满足即被排除不能是当前分支自身branch ! current_branchorigin/branch必须真实存在于远端候选分支的 tip 不得与当前 HEAD 同处一个提交Skips branches at the same commit as HEAD必须通过git merge-base --is-ancestor ${ref} HEAD证明它是 HEAD 的祖先。平票裁决第 76–90 行当两个候选分支到 HEAD 的提交数相同时consider()函数按两条规则裁决功能分支优先于 trunktelescoped 父分支优先于main/nextis_trunk()只认main和next若现任 best 是功能分支而新候选是 trunk则保留 best同为 trunk 时next优先于main脚本第 87–90 行显式处理branch next的覆盖逻辑。兜底第 133–135 行若三级检测全部落空脚本回退到nextif [ -z ${best} ]; then bestnext fi这与 PR 模板中默认提交到next的仓库约定一致。脚本最终把检测到的分支名输出到 stdout并要求 Agent 把结果告知用户。第 3 步交互式询问三类标签技能要求通过AskQuestion工具向用户提出三个问题选项取自 .github/PULL_REQUEST_TEMPLATE.md 中维护者检查单列出的可用标签问题选项CI 标签ci:normal、ci:merged、ci:dailyQA 标签qa:needed、qa:skip类型标签bug、maintenance、dependencies、build、cleanup、documentation、feature request、BREAKING CHANGE、other这套标签体系在 pr 技能 中有完整的语义定义三类标签均必选其一类型标签决定改动性质与是否进入 release changelogbuild/cleanup/documentation不进 changelogfeature request引入新功能BREAKING CHANGE表示破坏性变更dependencies专用于依赖升降级CI 标签控制 GitHub 检查单运行哪一组 sandbox。模板检查单明确指出各标签对应的 sandbox 集合定义在 code/lib/cli-storybook/src/sandbox-templates.tsQA 标签告知 release 团队该 PR 在下一次 minor 发布前是否需要人工手动验证。pr 技能给出的启发式规则包括触及路径/文件系统/可能影响 Windows 的行为 →qa:needed跨多个模块必须协同生效的复杂改动 →qa:needed简单直接的改动 →qa:skip无法判断时直接问用户。值得注意的是标签集合在两份文档间存在细微差异pr 技能额外列出了ci:docs配合documentation类型使用见 .agents/skills/pr/SKILL.md 第 42 行而 open-pr 技能的提问表格以 PR 模板的检查单为准——这也解释了 SKILL.md 中Verify the available labels with the PR template这句话的用意标签选项应以 PR 模板 为最终事实来源避免技能文档与模板漂移。第 4 步起草标题与正文标题采用[Area]: [Description]格式具体规范Area 首字母大写、不含空格、允许连字符与示例如CSFFactories: Fix type export、Nextjs-Vite: Add support、CLI: Fix automigrate issue由 pr 技能 定义open-pr 直接引用不重复。正文的要求是读取.github/PULL_REQUEST_TEMPLATE.md逐字复制模板包括所有 HTML 注释然后填充指定字段。对照模板全文可以明确各字段的处理规则Closes #有关联 issue 时填入编号多个 issue 用closes #1000, closes #1001形式拆分模板第 3 行注释What I did简述 PR 做了什么Testing 检查单勾选 stories / unit / integration / end-to-end 中适用的自动化测试类型Manual testing模板用[!CAUTION]标注此节对所有贡献都是强制的若确无手动测试必要必须显式说明理由。模板注释还给出了书写范式——面向另一位维护者的复现步骤而非我如何测过例如1. Run a sandbox for template, e.g. yarn task --task sandbox --start-from auto --template react-vite/default-ts 2. Open Storybook in your browser 3. Access X storypr 技能进一步要求每条步骤可复制粘贴、明确预期行为、UI 改动要链接到具体 story并强调提交 PR 前先自己跑一遍这些步骤Documentation 检查单适用时勾选含弃用/移除功能时须同步 MIGRATION.md模板中该链接指向 storybookjs/storybook 仓库的 next 分支Checklist for Maintainers三项维护者检查单CI 标签、QA 声明、类型标签保持未勾选——这些由维护者侧流程负责贡献者不应代勾。模板末尾还保留了若干机器可读的 HTML 注释锚点填充时必须原样保留!-- CANARY_RELEASE_SECTION --canary 工作流回写发布版本的占位区、!-- BENCHMARK_SECTION --性能数据区。pr 技能也提到CI 完成后可以把已发布的 Chromatic 链接写进手动测试一节格式为https://branch--project_id.chromatic.com/?path/story/story_id其中branch需按 Chromatic 的 slug 规则转换如feature/foo→feature-foo。第 5 步创建草稿 PRSKILL.md 给出的完整创建命令是gh pr create \ --draft \ --base detected-base \ --title Area: Description \ --body $(cat EOF FILLED_TEMPLATE EOF ) \ --assignee me \ --label type,ci,qa各参数要点--draft技能 Notes 明确要求Always draft——PR 永远以草稿态创建评审通过前不进入正式评审流程--base填入第 2 步detect-base-branch.sh的输出--body使用 heredocEOF带引号防止变量展开承载填好的模板全文。相比 pr 技能中的单行--body FILLED_TEMPLATE写法heredoc 能安全承载含反引号、!模板中有[!CAUTION]、多行的长正文避免 shell 转义地狱--assignee meNotes 要求always assignme把 PR 指派给操作者本人--label三个标签以逗号拼接对应第 3 步的三个回答。pr 技能中还给出了该命令的最简形式可作对照gh pr create --draft --title Area: Description --body FILLED_TEMPLATE --label category,ci,qa第 6 步汇报结果并询问 canary创建成功后技能要求先分享 PR URL再通过AskQuestion追问是否要为这个 PR 创建 canary release用户选Yes执行/canary PR_NUMBER并汇报 workflow 运行状态用户选No流程结束。canary 技能 定义了这一步的后续机制通过gh workflow run --repo storybookjs/storybook publish.yml --field prPR_NUMBER触发 GitHub Actions发布形如0.0.0-pr-PR_NUMBER-sha-SHORT_SHA的 npm 版本并打上canarytag随后 workflow 会把确切版本号回写到 PR 正文的CANARY_RELEASE_SECTION占位区——这正呼应了第 4 步保留 HTML 注释的要求。发布后可用npx storybookVERSION sandbox或直接npx storybookVERSION upgrade验证该版本。canary 发布的前提是拥有仓库 admin 权限、PR 处于 open 状态且ghCLI 已认证。关键约定小结Notes 部分SKILL.md 结尾的 Notes 用两条短规则固化了硬性约定也适合作为自定义同类技能时的检查清单Always draft; always assignme——草稿态 自指派是 Storybook PR 流程的不变式canary 发布的细节交给canary技能——单一职责拆分open-pr 只负责问一句要不要真正触发与监控逻辑在 canary 技能 中二者通过/canary PR_NUMBER命令衔接。可借鉴的设计要点从这套技能文件的结构可以看到几个值得复用的工程实践单一事实来源 指针复用.claude/skills/open-pr/SKILL.md仅一行引用.agents/skills/open-pr/SKILL.md是唯一维护点确定性逻辑下沉到脚本base 分支检测这种有明确算法upstream → reflog → 最近严格祖先 平票裁决 兜底next的逻辑被固化为 detect-base-branch.sh而不是依赖 Agent 每次自由发挥保证行为可重复、可 review模板即契约标签选项、正文结构、机器锚点CANARY_RELEASE_SECTION全部锚定在 .github/PULL_REQUEST_TEMPLATE.md 上技能文档只负责怎么填模板负责填什么两者漂移时以模板为准最小工具授权frontmatter 的allowed-tools精确到Bash, Read, AskQuestion技能没有任何超出 PR 创建所需的能力面。适用前提与限制该工作流针对 Storybook 仓库的多分支约定main/next双 trunk、PR 默认进next、维护者 cherry-pick 回main移植到其他仓库时需要改写is_trunk()的 trunk 集合与兜底分支ghCLI 必须已认证且对目标仓库有开 PR 的权限canary 环节额外要求 admin 权限检测脚本依赖git for-each-ref、reflog 等本地 Git 元数据在浅克隆shallow clone或缺少 reflog 的检出环境中优先级 2/3 的检测信号会不完整最终依赖next兜底标签集合以 PR 模板 与 pr 技能 当前内容为准其中ci:docs目前只出现在 pr 技能中若模板后续补齐open-pr 的提问表格需同步。相关文件索引文件作用.claude/skills/open-pr/SKILL.md指向.agents/skills/open-pr/SKILL.md的引用指针.agents/skills/open-pr/SKILL.mdopen-pr 技能主体六步工作流.agents/skills/open-pr/scripts/detect-base-branch.sh基础分支检测脚本upstream → reflog → 最近祖先 裁决.agents/skills/pr/SKILL.mdPR 标题格式、三类标签完整语义、正文撰写规范.agents/skills/canary/SKILL.mdcanary 发布触发、版本号规则、发布后验证.github/PULL_REQUEST_TEMPLATE.mdPR 正文模板标签、检查单、CANARY_RELEASE_SECTION 锚点code/lib/cli-storybook/src/sandbox-templates.tsci:normal/ci:merged/ci:daily对应的 sandbox 集合定义【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考