Back to Details

setup-github-labels

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Setup GitHub Labels

配置GitHub标签

Apply one intentional label vocabulary to whatever repo you run this in. The tables below are the source of truth, not the GitHub UI. This is a prompt-driven skill, not a deterministic script: read the set, explore the repo, confirm with the user, then create the labels with 
gh
.
在你运行此工具的任意仓库中应用一套统一的标签体系。以下表格是权威来源，而非GitHub UI。这是一个由提示驱动的skill，而非确定性脚本：读取标签集、浏览仓库、与用户确认，然后使用
gh
创建标签。

The canonical set

标准标签集

Three groups, kept small on purpose. This skill owns the GitHub label objects (name, color, description) for all of them. 
setup-matt-pocock-skills
owns the agent wiring for the triage roles — the role→string mapping in 
docs/agents/triage-labels.md
that tells the 
triage
skill which string to apply — and never touches a label's color or description. So the two skills split by concern, not by which labels: one owns the labels on GitHub, the other owns how the agent refers to them. Anything a tool already owns (Dependabot, labeler actions) is not here.
分为三组，刻意保持精简。本skill负责所有标签的GitHub标签对象（名称、颜色、描述）。
setup-matt-pocock-skills
负责分类角色的代理连接——即
docs/agents/triage-labels.md
中的角色→字符串映射，用于告知
triage
skill应使用哪个字符串——且从不修改标签的颜色或描述。因此两个skill按职责划分，而非按标签归属：一个负责GitHub上的标签，另一个负责代理如何引用这些标签。任何已由工具（如Dependabot、标签器动作）管理的标签均不包含在此处。

Issue 
type:
axis

议题
type:
维度

LabelColorDescription (issue-scoped)
type: bug
d73a4a
issue: Reporting a defect to fix
type: feature
a2eeef
issue: Requesting a new capability or improvement
type: task
cfd3d7
issue: For other work: maintenance, refactor, docs
type: bug
/ 
type: feature
/ 
type: task
mirror GitHub's Issue Types (Bug / Feature / Task). 
task
is the catch-all for refactor/docs/chore/test work. If a repo ever moves under a GitHub org, these map 1:1 onto native Issue Types and the labels can be retired.
标签颜色描述（议题专属）
type: bug
d73a4a
议题：报告需要修复的缺陷
type: feature
a2eeef
议题：请求新增功能或改进
type: task
cfd3d7
议题：用于其他工作：维护、重构、文档
type: bug
/ 
type: feature
/ 
type: task
与GitHub的议题类型（Bug / Feature / Task）一一对应。
task
是重构/文档/杂务/测试工作的通用标签。若仓库归入GitHub组织，这些标签可与原生议题类型1:1映射，届时即可停用这些标签。

Issue triage axis

议题分类维度

The five whose-turn triage roles the 
triage
skill moves an issue through. 
setup-matt-pocock-skills
decides which string each role maps to (and records it in 
docs/agents/triage-labels.md
); this skill creates the actual GitHub labels with a consistent scope prefix, so it reads at a glance whether a state applies to issues, PRs, or both.
LabelColorDescription
needs-triage
fbca04
issue: Maintainer needs to evaluate this issue
needs-info
d876e3
issue/pr: Waiting on reporter for more information
ready-for-agent
0e8a16
issue: Fully specified, ready for an AFK agent
ready-for-human
1d76db
issue: Requires human implementation
wontfix
ffffff
issue: Will not be actioned
needs-info
is the one 
issue/pr:
label: a PR parked on an outside human reuses it rather than minting a PR-scoped twin, so "waiting on a human" reads identically on both. Every other triage role is issue-only.
以下五个分类角色由
triage
skill用于跟踪议题流转。
setup-matt-pocock-skills
决定每个角色映射到哪个字符串（并记录在
docs/agents/triage-labels.md
中）；本skill创建实际的GitHub标签，并添加统一的范围前缀，以便一眼看出该状态适用于议题、PR还是两者皆可。
标签颜色描述
needs-triage
fbca04
议题：维护者需要评估此议题
needs-info
d876e3
议题/PR：等待提交者提供更多信息
ready-for-agent
0e8a16
议题：已完全明确，可交由AFK agent处理
ready-for-human
1d76db
议题：需要人工实现
wontfix
ffffff
议题：不会采取任何行动
needs-info
是唯一的
议题/PR:
标签：当PR等待外部人员处理时，可复用该标签，无需创建PR专属的同类标签，这样“等待人工处理”在议题和PR上的表述保持一致。其他所有分类角色均仅适用于议题。

PR-verdict axis

PR结论维度

Whose-turn routing on a PR needs almost no labels: a non-draft PR with no verdict is, by definition, the agent's to finalize, and a PR parked on an outside human reuses the 
needs-info
triage label above rather than minting a PR-scoped twin. What this axis adds is the agent's terminal verdict once it has finished finalizing a PR: the signal that tells the maintainer, at a glance, what each open PR needs from them.
LabelColorDescription (PR-scoped)
recommend-merge
0E8A16
pr: Agent finalized and endorses it: review and merge
recommend-close
D93F0B
pr: Agent recommends closing: your call to review or close
recommend-triage
FBCA04
pr: Agent finalized it but the merge/close call is yours
The verdict is three-way by design: the agent finalizes a PR (rebase, green CI, polish) and then emits exactly one of the three. The split exists because "not mergeable as-is" hides two states with very different maintainer effort:
  • recommend-close
    is the agent's active reject — broken, abandoned, superseded, or clearly out of scope. The maintainer glances and closes.
  • recommend-triage
    is for a PR whose code is sound but whose merge/close call is a product or scope judgment the agent can't make — a clean, working feature where the only open question is "does this project want it". The maintainer must stop and decide; that decision is theirs, not the agent's.
Folding the second into 
recommend-close
would be dishonest — the agent does not recommend closing a sound feature — and would bury the most expensive pile (the product calls only the maintainer can make) inside the cheap one (rubber-stamp closes). So the maintainer's world is three filters: an emerald ship queue (
is:pr is:open label:recommend-merge
), an amber decision queue (
label:recommend-triage
), and a red close pile (
label:recommend-close
).
recommend-triage
is not a cop-out hatch. It is only for "code is sound, the call is product/scope". If the agent has a technical reason the PR shouldn't merge, it still owes a 
recommend-close
with that reason in the review comment — otherwise the decision queue swells with PRs the agent could have resolved and the label loses its meaning.
The agent never merges and never closes — both stay the maintainer's hand; the verdict is a recommendation, not an action. That is why all three labels lead with 
recommend-
rather than the ecosystem-conventional 
ready-to-merge
: the matched 
recommend-merge
/ 
recommend-close
/ 
recommend-triage
set names them honestly as recommendations, and — deliberately — steers clear of the label strings merge bots watch (Kodiak, Mergify, bors, GitHub auto-merge). A bot wired to merge on 
ready-to-merge
would turn the agent's recommendation into an actual merge and break this invariant, so do not rename it back to that conventional string.
A verdict endorses one specific diff, so it goes stale the moment the PR changes: a new commit after a verdict means the agent must clear that label and re-review before the emerald queue can be trusted again. Pushes after a verdict are rare, so this stays a manual step rather than something worth a CI workflow.
A couple of label families are deliberately left out, because a tool already owns them:
  • Tool-managed labels (
    dependencies
    from Dependabot, and other labels created by labeler actions or bots) are owned by that tooling. Leave their color and description alone; do not add them here or you will fight the tool that recreates them.
  • area:*
    labels are per-repo (add them locally, ideally via path-based 
    actions/labeler
    ), so they do not belong in a shared cross-repo set.
The "still being worked" state is owned by GitHub's native draft flag, not a label. A PR mid-iteration (including agent- or self-authored PRs, where the author is the maintainer so review-request doesn't apply) stays a draft until the agent has a verdict. So there is deliberately no 
ready-for-maintainer
/ 
ready-for-review
label: 
recommend-merge
already is the "your turn to ship" signal, and the draft flag already owns "not yet". The maintainer's "needs my attention" filter is 
is:pr is:open label:recommend-merge
. 
/make-pr
opens autonomous PRs as draft for exactly this reason.
The same draft flag is why there is no 
do-not-merge
label: a "don't merge this yet" state is almost always temporary (a PR kept open to exercise CI, or one mid-iteration), and that is precisely what draft expresses. A draft PR already cannot be merged, so a separate flag would just be a second, redundant mechanism for "not yet".
PR type and area stay absent: PR type comes from the conventional-commit title, and area is per-repo. Only the PR verdict is shared here, because "is this one mine to ship" generalizes across every repo with PRs. Each description leads with a scope prefix — 
issue:
, 
pr:
, or 
issue/pr:
— to advertise where it applies, so tools and people don't cross-apply.
PR的流转几乎不需要额外标签：未标记为草稿且无结论标签的PR，默认由agent完成最终处理；若PR等待外部人员处理，可复用上述分类标签中的
needs-info
，无需创建PR专属的同类标签。此维度添加的是agent完成PR最终处理后的终端结论，让维护者一眼就能看出每个开放PR需要他们做什么。
标签颜色描述（PR专属）
recommend-merge
0E8A16
PR：Agent已完成处理并认可，请审核并合并
recommend-close
D93F0B
PR：Agent建议关闭，请自行决定是否审核或关闭
recommend-triage
FBCA04
PR：Agent已完成处理，但合并/关闭的决策由你决定
结论刻意设计为三种：agent完成PR的最终处理（变基、CI通过、优化）后，会生成这三种结论中的一种。拆分的原因在于，“当前无法合并”包含两种维护者投入差异极大的状态：
  • recommend-close
    是agent的主动拒绝——PR存在问题、已废弃、被替代或明显超出范围。维护者只需浏览即可关闭。
  • recommend-triage
    适用于代码无问题，但合并/关闭的决策属于产品或范围判断，agent无法做出的PR——比如一个干净可用的功能，唯一的问题是“该项目是否需要这个功能”。维护者必须停下来做出决策；这个决策属于他们，而非agent。
将第二种情况归入
recommend-close
并不恰当——agent并不建议关闭一个可用的功能——且会将最耗时的部分（只有维护者能做出的产品决策）混入简单的操作（批量关闭）中。因此维护者的工作分为三个筛选队列：绿色的合并队列（
is:pr is:open label:recommend-merge
）、黄色的决策队列（
label:recommend-triage
）和红色的关闭队列（
label:recommend-close
）。
recommend-triage
不是逃避的借口。它仅适用于“代码无问题，决策属于产品/范围”的情况。若agent有技术原因认为PR不应合并，仍需标记
recommend-close
并在评审评论中说明原因——否则决策队列会充斥agent本可解决的PR，导致该标签失去意义。
agent从不执行合并或关闭操作——这两项操作始终由维护者完成；结论只是建议，而非行动。这就是为什么三个标签都以
recommend-
开头，而非行业常规的
ready-to-merge
：统一的
recommend-merge
/ 
recommend-close
/ 
recommend-triage
标签诚实地表明它们是建议，并且——刻意——避开合并机器人（如Kodiak、Mergify、bors、GitHub自动合并）监听的标签字符串。若机器人配置为看到
ready-to-merge
就执行合并，会将agent的建议转化为实际合并操作，打破这一规则，因此请勿将其改回常规字符串。
结论仅针对特定的差异，因此PR一旦变更，结论就会失效：结论生成后若有新提交，agent必须清除该标签并重新评审，才能确保绿色队列的可信度。结论生成后的推送操作很少见，因此这一步保持手动，无需CI工作流。
有几类标签刻意未包含在内，因为已由工具管理：
  • 工具管理的标签（如Dependabot的
    dependencies
    ，以及其他由标签器动作或机器人创建的标签）由对应工具负责。请勿修改它们的颜色和描述；也不要将其添加到此处，否则会与重建这些标签的工具产生冲突。
  • area:*
    标签是仓库专属的（应在本地添加，理想情况下通过基于路径的
    actions/labeler
    ），因此不属于跨仓库共享的标签集。
“仍在处理中”的状态由GitHub原生的草稿标记负责，而非标签。处于迭代中的PR（包括agent或维护者自己创建的PR，此时无需请求评审）会保持草稿状态，直到agent得出结论。因此刻意没有
ready-for-maintainer
/ 
ready-for-review
标签：
recommend-merge
本身就是“轮到你发布”的信号，而草稿标记已经负责“尚未完成”的状态。维护者的“需要关注”筛选条件是
is:pr is:open label:recommend-merge
。
/make-pr
命令会将自动创建的PR标记为草稿，正是出于这个原因。
同样，草稿标记也解释了为什么没有
do-not-merge
标签：“暂时不要合并”的状态几乎总是临时的（比如为了测试CI而保持开放的PR，或处于迭代中的PR），而这正是草稿标记的用途。草稿PR本身就无法合并，因此单独的标签只是“尚未完成”的第二种冗余机制。
PR的类型和范围标签未包含在内：PR类型来自约定式提交标题，范围是仓库专属的。此处仅共享PR的结论，因为“这个PR是否需要我发布”是所有有PR的仓库都通用的需求。每个描述都以范围前缀开头——
issue:
、
pr:
或
issue/pr:
——以表明其适用范围，避免工具和人员错误应用。

Issue ↔ PR equivalents

议题 ↔ PR对应关系

Issues and PRs run the same underlying state machine — whose turn is it, and what must they do — but express it with different signals. This skill creates both sides' labels; 
setup-matt-pocock-skills
owns the issue side's vocabulary (which string each triage role maps to). The PR side also leans on GitHub's native draft flag. This table lines them up so a state reads the same whether you're looking at an issue or a PR:
State (whose turn / what's needed)Issue (triage role)PR (verdict + draft flag)
Unprocessed — someone must look
needs-triage
no verdict label, non-draft
Blocked on an outside human
needs-info
needs-info
(same label, reused)
Still being built / iterated(open issue, no extra label)draft flag
Agent's turn to act
ready-for-agent
no verdict label, non-draft
Maintainer's turn — endorsed
ready-for-human
(human implements)
recommend-merge
(human reviews/merges)
Maintainer's turn — must decide
needs-triage
(maintainer evaluates)
recommend-triage
(product/scope call)
Won't proceed
wontfix
recommend-close
Three asymmetries are intentional, not gaps:
  • needs-triage
    and 
    ready-for-agent
    collapse into one PR state.     A non-draft PR with no verdict already means "agent, finalize this", so the PR side never separates "needs evaluation" from "agent's turn" — there is no PR 
    needs-triage
    or 
    ready-for-agent
    label. On the issue side they stay distinct because an issue can sit triaged-but-not-yet-assigned.
  • The maintainer's terminal action differs. 
    ready-for-human
    on an issue means implement it; 
    recommend-merge
    on a PR means review and merge it. Same "your turn, human" role, different verb — which is why 
    ready-for-human
    stays issue-only and 
    recommend-merge
    is its PR counterpart rather than a shared label.
  • needs-triage
    spans two PR states.     On issues, "maintainer must evaluate" is one state. On PRs it splits by when: a fresh PR is the agent's to finalize (no verdict, non-draft), and only after the agent finalizes does a leftover product/scope call earn its own verdict, 
    recommend-triage
    . That is why 
    recommend-triage
    is a distinct PR label and the agent never puts 
    needs-triage
    on a PR (that would invert it to "agent hasn't looked yet").
do-not-merge
is absent on purpose: a "don't merge yet" PR is the draft row above, so it needs no label of its own.
议题和PR运行相同的底层状态机——轮到谁处理，需要做什么——但表达方式不同。本skill创建双方的标签；
setup-matt-pocock-skills
负责议题端的词汇（每个分类角色映射到哪个字符串）。PR端还依赖GitHub的原生草稿标记。下表将两者对应起来，以便无论查看议题还是PR，状态的含义都保持一致：
状态（轮到谁处理 / 需要做什么）议题（分类角色）PR（结论 + 草稿标记）
未处理——需要有人查看
needs-triage
无结论标签，非草稿
等待外部人员处理
needs-info
needs-info
（复用同一标签）
仍在构建/迭代中(开放议题，无额外标签)草稿标记
轮到Agent处理
ready-for-agent
无结论标签，非草稿
轮到维护者——已获认可
ready-for-human
（人工实现）
recommend-merge
（人工审核/合并）
轮到维护者——必须做出决策
needs-triage
（维护者评估）
recommend-triage
（产品/范围决策）
不会继续推进
wontfix
recommend-close
三处不对称是刻意设计的，而非遗漏：
  • needs-triage
    和
    ready-for-agent
    合并为一种PR状态。     无结论标签的非草稿PR本身就意味着“Agent，请完成此PR的最终处理”，因此PR端从不区分“需要评估”和“轮到Agent处理”——没有PR专属的
    needs-triage
    或
    ready-for-agent
    标签。在议题端它们保持区分，因为议题可能已完成分类但尚未分配处理。
  • 维护者的终端操作不同。 议题上的
    ready-for-human
    意味着实现该议题；PR上的
    recommend-merge
    意味着审核并合并该PR。同样是“轮到人工处理”的角色，但操作不同——这就是为什么
    ready-for-human
    仅适用于议题，而
    recommend-merge
    是其PR端的对应标签，而非共享标签。
  • needs-triage
    对应两种PR状态。     在议题端，“维护者必须评估”是一种状态。在PR端，它按时间点拆分：新PR由Agent完成最终处理（无结论标签，非草稿），只有在Agent完成处理后，剩余的产品/范围决策才会获得专属结论标签
    recommend-triage
    。这就是为什么
    recommend-triage
    是独立的PR标签，且Agent绝不会在PR上标记
    needs-triage
    （否则会被误解为“Agent尚未查看”）。
do-not-merge
标签刻意缺失：“暂时不要合并”的PR属于上表中的草稿行，因此无需单独的标签。

Process

流程

Detect, preview, confirm, then apply.
检测、预览、确认、应用。

1. Detect the current repo

1. 检测当前仓库

bash
gh repo view --json nameWithOwner -q .nameWithOwner
If that fails (no GitHub remote), ask the user which repo to target.
bash
gh repo view --json nameWithOwner -q .nameWithOwner
若命令失败（无GitHub远程仓库），询问用户目标仓库。

2. Preview (read-only)

2. 预览（只读）

Show the user which canonical labels are new vs already present on the repo, by comparing the tables' labels against the repo's existing ones:
bash
gh label list --repo "$REPO" --limit 200 --json name -q '.[].name'
Labels in the tables but not in that list will be created; labels already present will have their color/description updated.
将表格中的标签与仓库现有标签对比，向用户展示哪些标准标签是新增的，哪些已存在：
bash
gh label list --repo "$REPO" --limit 200 --json name -q '.[].name'
表格中有但仓库中没有的标签将被创建；已存在的标签将更新其颜色/描述。

3. Confirm, then apply

3. 确认后应用

Creating labels on a (often public) repo is an outward-facing action, so confirm with the user first. Then create each label from the tables with 
--force
, which adds it if missing and updates color/description if it already exists:
bash
gh label create "type: bug"     --color d73a4a --description "issue: Reporting a defect to fix"                   --force --repo "$REPO"
gh label create "type: feature" --color a2eeef --description "issue: Requesting a new capability or improvement"  --force --repo "$REPO"
gh label create "type: task"    --color cfd3d7 --description "issue: For other work: maintenance, refactor, docs" --force --repo "$REPO"
gh label create "needs-triage"    --color fbca04 --description "issue: Maintainer needs to evaluate this issue"     --force --repo "$REPO"
gh label create "needs-info"      --color d876e3 --description "issue/pr: Waiting on reporter for more information" --force --repo "$REPO"
gh label create "ready-for-agent" --color 0e8a16 --description "issue: Fully specified, ready for an AFK agent"     --force --repo "$REPO"
gh label create "ready-for-human" --color 1d76db --description "issue: Requires human implementation"              --force --repo "$REPO"
gh label create "wontfix"         --color ffffff --description "issue: Will not be actioned"                       --force --repo "$REPO"
gh label create "recommend-merge"  --color 0E8A16 --description "pr: Agent finalized and endorses it: review and merge"   --force --repo "$REPO"
gh label create "recommend-close"  --color D93F0B --description "pr: Agent recommends closing: your call to review or close" --force --repo "$REPO"
gh label create "recommend-triage" --color FBCA04 --description "pr: Agent finalized it but the merge/close call is yours" --force --repo "$REPO"
To set up several repos, repeat with each 
--repo
.
在（通常是公开的）仓库中创建标签是对外可见的操作，因此需先获得用户确认。然后使用
--force
参数从表格中创建每个标签：若标签不存在则添加，若已存在则更新颜色/描述：
bash
gh label create "type: bug"     --color d73a4a --description "issue: Reporting a defect to fix"                   --force --repo "$REPO"
gh label create "type: feature" --color a2eeef --description "issue: Requesting a new capability or improvement"  --force --repo "$REPO"
gh label create "type: task"    --color cfd3d7 --description "issue: For other work: maintenance, refactor, docs" --force --repo "$REPO"
gh label create "needs-triage"    --color fbca04 --description "issue: Maintainer needs to evaluate this issue"     --force --repo "$REPO"
gh label create "needs-info"      --color d876e3 --description "issue/pr: Waiting on reporter for more information" --force --repo "$REPO"
gh label create "ready-for-agent" --color 0e8a16 --description "issue: Fully specified, ready for an AFK agent"     --force --repo "$REPO"
gh label create "ready-for-human" --color 1d76db --description "issue: Requires human implementation"              --force --repo "$REPO"
gh label create "wontfix"         --color ffffff --description "issue: Will not be actioned"                       --force --repo "$REPO"
gh label create "recommend-merge"  --color 0E8A16 --description "pr: Agent finalized and endorses it: review and merge"   --force --repo "$REPO"
gh label create "recommend-close"  --color D93F0B --description "pr: Agent recommends closing: your call to review or close" --force --repo "$REPO"
gh label create "recommend-triage" --color FBCA04 --description "pr: Agent finalized it but the merge/close call is yours" --force --repo "$REPO"
若要配置多个仓库，只需为每个仓库重复上述命令并修改
--repo
参数。

4. Report

4. 报告结果

Tell the user which labels were created vs updated. Non-canonical labels already on the repo are left untouched (this skill only adds/updates the canonical set). If they want to retire a stray label, that is a manual, deliberate step: 
gh label delete "<name>" --repo "$REPO" --yes
. Deleting strips it off every issue/PR currently wearing it, so never do it without explicit confirmation.
This skill creates the triage labels, but the engineering skills only apply them if the repo also has the agent wiring — the role→string mapping in 
docs/agents/triage-labels.md
. If that file is absent (
test -f docs/agents/triage-labels.md
), recommend running 
setup-matt-pocock-skills
to write it. That's a one-line pointer, not a requirement: the labels stand on their own; the wiring is what lets the 
triage
skill reach for them. Skip the recommendation when the file is already present.
告知用户哪些标签是新增的，哪些是已更新的。仓库中已有的非标准标签保持不变（本skill仅添加/更新标准标签集）。若用户想要移除无关标签，需手动执行：
gh label delete "<name>" --repo "$REPO" --yes
。删除标签会移除所有当前使用该标签的议题/PR上的标签，因此必须获得明确确认后再执行。
本skill创建分类标签，但工程类skill仅在仓库同时配置了代理连接（即
docs/agents/triage-labels.md
中的角色→字符串映射）时才会应用这些标签。若该文件不存在（
test -f docs/agents/triage-labels.md
），建议运行
setup-matt-pocock-skills
来创建该文件。这只是一个提示，而非强制要求：标签可独立使用；代理连接是让
triage
skill能够使用这些标签的前提。若文件已存在，则跳过该建议。

Changing the set

修改标签集

Edit the tables above: add or remove a row, and keep the 
gh label create
lines in step 3 in sync with them. For a triage role, also keep it consistent with the role→string mapping 
setup-matt-pocock-skills
records in 
docs/agents/triage-labels.md
— this skill owns the label's color and description, that skill owns which string the role maps to. Keep the set small: before adding a label, check it carries information the commit title, diff, or an existing label (or another skill's labels) doesn't.
编辑上方的表格：添加或删除行，并保持步骤3中的
gh label create
命令与表格同步。对于分类角色，还需保持与
setup-matt-pocock-skills
记录在
docs/agents/triage-labels.md
中的角色→字符串映射一致——本skill负责标签的颜色和描述，该skill负责角色映射到哪个字符串。保持标签集精简：添加标签前，确认该标签所承载的信息无法通过提交标题、差异或现有标签（或其他skill的标签）体现。