Storybook Agent 技能实战：用 github-qa-labels 规范 GitHub QA 问题的标签工作流

本文以 Storybook 官方仓库内置的 Agent 技能文件 github-qa-labels/SKILL.md 为核心，完整解读 Storybook 团队在版本升级 QA（Quality Assurance）测试中，如何借助 gh CLI 对发现的 Issue 和 PR 施加统一的跟踪标签（upgrade:<version>）与严重等级标签（sev:S1–sev:S4），并结合仓库中真实的技能体系结构、canary 发布流程与升级命令，说明这套标签规范在 Storybook 研发流水线中的定位、适用边界与批量操作技巧。读完后，你可以直接复现一套可追溯的版本 QA 问题归档流程，并理解该技能在多 Agent 协作框架（Claude Code / Codex 插件）中是如何被装载和引用的。

技能文件的位置与加载机制

github-qa-labels 是 Storybook 仓库为编码 Agent 预置的一组技能（Skills）之一。它的入口文件位于 .claude/skills/github-qa-labels/SKILL.md，但打开该文件会发现它只有一行内容：

@../../../.agents/skills/github-qa-labels/SKILL.md

这是一个引用声明：.claude/skills/ 下的 12 个技能文件全部以同样的方式指向 .agents/skills/ 目录下的同名技能。真正的技能内容定义在 .agents/skills/github-qa-labels/SKILL.md。这种"一处定义、多处引用"的结构与仓库整体的 Agent 指令约定一致——CLAUDE.md 也只有一行 @AGENTS.md，而 AGENTS.md 明确声明自己是"编码 Agent 的规范指令来源，CLAUDE.md 等文件应指向它而非重复指令"。技能体系遵循同样的去重原则，避免多份副本漂移。

技能文件本身采用 YAML frontmatter 声明元信息，github-qa-labels 的定义为：

---
name: github-qa-labels
description: Label GitHub issues and PRs found during QA testing. Use when organizing QA findings with proper labels.
allowed-tools: Bash
---

其中 description 是 Agent 决定"何时触发该技能"的依据（描述里给出了明确的触发场景：整理 QA 发现时），allowed-tools: Bash 则把该技能可用工具限定为 Bash——因为技能的全部操作都是 gh 命令。仓库中还有 .agents/plugins/marketplace.json 声明了 Storybook 的 Codex 插件来源（code/lib/codex-plugin/plugins/storybook），说明同一套技能既服务于仓库内置工作流，也会随插件分发到外部项目中使用。

与 github-qa-labels 并列的还有 canary、storybook-upgrade、minor-release、handle-pr-comments 等技能，共同构成"发布 → 升级 → QA → 归档问题"的完整链路，github-qa-labels 处在 QA 收尾归档这一环。

核心主题：为 QA 发现打标签

技能正文的开篇即给出定位：

When creating or organizing issues/PRs found during QA testing, apply these labels. （在创建或整理 QA 测试中发现的 Issue/PR 时，应用这些标签。）

也就是说，该技能不是通用的 GitHub 标签指南，而是专为"版本升级 QA"这一场景定制的归档规范，包含三类规则：QA 跟踪标签、严重等级标签、以及批量打标操作。

一、QA 跟踪标签 upgrade:<version>

每个版本升级 QA 周期，所有发现的问题都挂到一个按版本号命名的跟踪标签下，从而可以用一个 label 聚合出该版本 QA 的全部发现。

第一步，确保标签存在（若不存在则创建）：

# Create label if it doesn't exist
gh label create "upgrade:10.2" --repo storybookjs/storybook --color "0E8A16" --description "Issues/PRs found during 10.2 upgrade QA"

各参数含义：

• "upgrade:10.2"：标签名，遵循 upgrade:<major.minor> 的命名约定，与 QA 目标版本一一对应；
• --repo storybookjs/storybook：显式指定目标仓库（技能默认操作 Storybook 官方仓库）；
• --color "0E8A16"：深绿色，让版本跟踪标签在 GitHub 列表中视觉可辨；
• --description：说明该标签的语义边界，防止被误用到非 QA 场景。

第二步，把标签加到具体的 Issue 或 PR 上：

# Add to issue/PR
gh issue edit <NUMBER> --repo storybookjs/storybook --add-label "upgrade:10.2"
gh pr edit <NUMBER> --repo storybookjs/storybook --add-label "upgrade:10.2"

<NUMBER> 替换为 Issue/PR 编号。gh issue edit 与 gh pr edit 都通过 --add-label 增量添加标签，不会覆盖已有标签，因此 upgrade:10.2 可以与其他标签（如严重等级、类型标签）共存。

二、严重等级标签 sev:S1 – sev:S4（仅限 Bug）

对于真正的缺陷，再叠加一个严重等级标签：

gh issue edit <NUMBER> --repo storybookjs/storybook --add-label "sev:S2"

技能正文给出四级严重度的精确定义：

标签	级别	含义
sev:S1	Critical	严重、阻断性，且无 workaround
sev:S2	Significant	重要问题，可能有 workaround
sev:S3	Moderate	中等问题，workaround 存在
sev:S4	Minor	轻微问题、边缘场景、workaround 容易

判定标准的核心变量是"有无替代方案"与"影响面大小"，这使不同 QA 执行者对同一问题打出的等级趋于一致。

三、什么类型的问题该打严重等级标签

技能用一张判定表明确了 sev:* 的适用范围，这里完整保留：

问题类型	是否打严重等级标签
Bug（运行时错误）	是
Bug（类型错误）	是
Bug（automigrate 问题）	是
文档问题	否
功能请求	否
增强建议	否

也就是说：sev:* 只用于 bug，文档类问题、feature request、enhancement 一律不打严重等级标签（但仍应挂 upgrade:<version> 跟踪标签）。值得注意的是表中专门列出"automigrate 问题"——这与 Storybook 大型版本升级时依赖 codemod/automigrate 工具链的现状直接相关：自动迁移脚本产生的破坏同样按 bug 定级。

四、批量打标

QA 一轮下来往往积累十几个问题，技能给出了用 && 串联命令的批量操作示例：

gh issue edit 33524 --repo storybookjs/storybook --add-label "upgrade:10.2" && \
gh issue edit 33527 --repo storybookjs/storybook --add-label "upgrade:10.2" && \
gh pr edit 33526 --repo storybookjs/storybook --add-label "upgrade:10.2"

要点有三：

1. 用 && 顺序串联，任一命令失败即停止，避免在错误仓库上继续误操作；
2. Issue 用 gh issue edit、PR 用 gh pr edit，二者不能混用；
3. 批量场景下编号是已确认的真实 Issue/PR 号（如技能示例中的 33524、33526、33527），执行前应先核对。

结合仓库上下文：这个技能在 QA 流水线中的位置

单看标签规则略显孤立，放进 Storybook 的发布流程里，github-qa-labels 的职责就清晰了。

QA 测的是什么：canary 版本与升级命令

从 .agents/skills/canary/SKILL.md 可以看到，Storybook 的每个 PR 都可以通过 GitHub Actions 发布一个格式可预测的 canary 版本：

0.0.0-pr-<PR_NUMBER>-sha-<SHORT_SHA>

例如 PR #33526、commit 短 SHA 为 a2e09fa2 时，canary 版本即 0.0.0-pr-33526-sha-a2e09fa2，并以 canary dist-tag 发布到 npm，同时把版本号写回 PR 描述。随后 QA 的验证动作由 .agents/skills/storybook-upgrade/SKILL.md 定义：

npx storybook@<VERSION> upgrade

该命令会自动检测项目内所有 @storybook/* 包、统一升级到目标版本、处理 peer dependencies，并支持 npm/yarn/pnpm；技能还强调两条纪律——不要手动 npm add 单个 storybook 包（保证包间版本同步），以及一次只升一个主版本（如 8.x → 9.x → 10.x，不能从 8.x 直接跳 10.x）。github-qa-labels 的批量示例中恰好出现了 PR #33526 与 canary 技能里的示例版本号 0.0.0-pr-33526-sha-a2e09fa2，从源码结构看可以推断：QA 流程正是"用 npx storybook@0.0.0-pr-33526-sha-a2e09fa2 upgrade 在下游项目复测 → 发现回归问题 → 创建 Issue #33524/#33527 与修复 PR #33526 → 统一挂 upgrade:<version> 标签归档"。

标签名与当前仓库版本的对应

以仓库现状为例，code/core/package.json 中 storybook 包的当前版本为 10.6.0-beta.1，按技能的命名约定，该版本升级 QA 期间应创建并使用 upgrade:10.6 跟踪标签（10.2 只是技能文档中的示意版本）。由于标签名直接编码版本号，gh issue list -L "upgrade:10.6" 之类的查询即可随时盘点该版本 QA 的未关闭项，为 minor-release 技能在写 CHANGELOG.md 时提供问题清单输入。

与其他技能、指令文件的协作关系

从 .agents/skills/ 目录结构看，Storybook 把 Agent 的工作流拆成了 12 个职责单一的 SKILL.md：

• canary：触发 PR 的 canary 发布，产出待测版本号；
• storybook-upgrade：在外部项目执行升级验证；
• github-qa-labels：把验证发现的问题规范化归档；
• handle-pr-comments：逐条处理 PR review 意见；
• minor-release：汇总 prerelease 条目写 minor/major 版本的 changelog；
• 其余如 open-pr、pr、rebuild-restart-storybook 等覆盖开 PR、重启本地实例等操作。

每个技能只声明自己的触发条件与工具白名单，github-qa-labels 的 allowed-tools: Bash 意味着 Agent 执行它时只有命令执行权限，无法改写仓库文件——这与标签操作"只动 GitHub 侧元数据、不动代码"的性质吻合。而全局性的行为准则（base 分支为 next、任务编排用 NX 与 yarn task 等）统一收口在 AGENTS.md，技能文件不重复这些内容，保持单一事实来源。

实践要点小结

结合技能全文与仓库证据，落地这套规范时可按以下清单执行：

1. 建标签：QA 开始前先 gh label create "upgrade:<version>"（带 --color 与 --description），确保同版本所有发现聚合到一个可查询的标签下；
2. 区分两类标签：所有 QA 发现（Issue 和 PR）一律挂 upgrade:<version>；仅 bug 类追加 sev:S1–sev:S4，文档、feature request、enhancement 不打严重等级；
3. 按 workaround 定级：无 workaround 且阻断 → S1；可能有 workaround → S2；有 workaround → S3；边缘场景 → S4；
4. 批量操作：用 && 串联 gh issue edit / gh pr edit，注意 issue 与 pr 命令不可互换；
5. 保持包版本同步：QA 对象若是下游项目，升级必须走 npx storybook@<version> upgrade 而非手工安装，且一次只跨一个主版本；
6. 版本号格式：测 canary 时使用 0.0.0-pr-<PR_NUMBER>-sha-<SHORT_SHA> 格式，可从 PR 号与最新 commit SHA 自行推导，也可从 PR 描述中的发布提示获取。

这套看似简单的标签约定，实际上把"哪个版本的 QA、发现了什么级别的问题、由哪个 PR 修复"三个维度固化到了 GitHub 元数据里，使升级回归问题在整个版本生命周期内可聚合、可追溯、可交接——这也是 Storybook 这类拥有大量下游框架集成（React、Vue3、Angular、Svelte、Next.js 等，见 .agents/skills/storybook-upgrade/SKILL.md 与 AGENTS.md 中的 monorepo 结构说明）的大型项目做版本升级 QA 时，值得直接借用的工程实践。