herdr Issue Triage Skill：把 GitHub Issue 分诊做成 Agent 的决策优先工作流

在 herdr 仓库中，.agents/skills/triage/SKILL.md 定义了一个专门用于「GitHub Issue 分诊」的 Agent 技能：当用户说出 triage、询问哪些 open issue 需要处理、或想要 issue 优先级建议灯时，Agent 会检查 herdrdev/herdr 的 open issues，并输出一张紧凑的「决策优先」Markdown 表格。读完本文，你会掌握这套分诊技能的完整规格：触发条件、工具回退策略、表格列语义、三灯分类判据、建议词表与输出风格约束，并能理解它在 herdr 仓库 Agent 技能体系中的定位与实现背景。

技能定位：仓库内的分诊技能

该技能文件位于 .agents/skills/triage/SKILL.md，其 frontmatter 声明了触发语义：

name: triage
description: Triage open herdr GitHub issues into a concise decision-first Markdown table. Use when the user says "triage", asks to triage open issues, asks which issues need attention, or wants issue priority/recommendation lights for herdr.

两个核心约束直接写在正文开头：

• 作用域限定：Use this skill only inside the herdr repository.——该技能只在 herdr 仓库内部生效，防止被泛化到其他项目的 issue 管理场景；
• 工具优先级：优先使用可用的 GitHub MCP 工具；只有在 MCP 不可用、且本机已配置好认证访问时，才回退到 gh issue list / gh issue view 命令行。

这条回退链（MCP 优先 → 已认证的 gh CLI → 否则不执行）是典型的「能力探测式」Agent 指令设计：不假设运行环境，也不鼓励在缺少认证时盲目调用网络工具。

herdr 仓库中与之并列的还有两个内部技能：herdr-throwaway-repro（在隔离的一次性命名会话中复现 bug）与 herdr-pre-release-audit（发布前对照 changelog 与文档做审计）。三者共同构成仓库内「面向维护者的 Agent 工作流」，而 triage 是其中的入口环节——先判断哪些 issue 值得关注，后续的复现（throwaway-repro）与发布审计（pre-release-audit）才有优先级依据。

输出表格：列语义与格式规则

技能规定输出必须采用固定的六列表格结构：

Light	Recommendation	Issue	Age	Reactions	Why
🔴	fix now	#123	18d	5	user-visible regression
🟡	queue	#124	42d	2	useful but not blocking
🔵	defer	#125	7d	0	cosmetic polish

各列的取值规则在文档中逐一定义：

• Light：三灯之一（🔴/🟡/🔵），表达优先级灯；
• Recommendation：短祈使句建议，取值限定在固定词表内（见下文）；
• Issue：必须保留 issue 编号并写成 Markdown 链接形式，保证读者可点击跳转；
• Age：使用「issue 创建以来的天数」（days since issue creation），带 d 后缀，右对齐；
• Reactions：使用 reactions 总数；仅当细分构成会改变解读时才附加紧凑明细，例如 7 (5 👍, 2 👀)——即「总数优先、明细按需」的降噪策略；
• Why：一句话说明判断依据（如 user-visible regression）。

这套列设计的意图是让表格本身成为决策物：维护者扫一眼 Light 列就知道先做什么，Why 列给出最小必要理由，而不是一篇叙述长文。

三灯分类判据

技能给出了逐灯的可操作判据，这是整个技能的核心分类学：

• 🔴 fix now：可复现的 bug、崩溃、数据丢失、被阻塞的工作流、发布风险，或高置信度的用户可见回归；
• 🟡 queue：有用的功能请求、重要的质量问题、反复出现的用户信号、过期但仍成立的 issue，或值得排期的行为改进；
• 🔵 defer：纯外观打磨、低信号点子、报告不清晰的 issue、仅文档层面的小问题，或实现前还需要更多证据的 issue。

注意判据之间的边界设计：🔴 强调「已确认的损害」，🟡 强调「值得排期但非阻塞」，🔵 则把「证据不足」也归入其中——也就是说，分诊阶段不替 issue 下结论，证据不足就明确降级等待，避免 Agent 在信息不全时给出过度承诺。

与之配套的是 Recommendation 词表，只允许六种短祈使短语：fix now、queue、defer、needs repro、close?、needs owner decision。其中 needs repro、close?、needs owner decision 三个非灯值建议体现了分诊的另一职能：提示流程动作（要复现、建议关闭、需维护者拍板），而不只是排优先级。

输出风格约束：抑制长篇叙述

技能对输出体量的控制同样明确：

• 表格之前最多写一句话，仅在需要说明范围时使用（例如「本次共检查了 N 个 open issues」）；
• 表格之后最多一条简短附注，用于表达不确定性或后续动作；
• 除非用户明确要求深入，否则不得输出长叙述。

这条约束与「decision-first」的命名呼应：分诊产物是给维护者的行动清单，而不是分析报告。

实现背景：技能文件如何被 herdr 分发

从仓库源码结构看，herdr 对「技能文件」有完整的工程化处理。公开技能 skills/herdr/SKILL.md（教 Agent 如何控制 herdr 本身）在构建时被编译进二进制：src/main.rs 中 const SKILL: &str = include_str!("../skills/herdr/SKILL.md");，注释明确「Bundled at build time so the printed skill always matches this binary's release」，因此 herdr --skill 打印的永远是与当前安装版本匹配的技能副本；src/cli.rs 中还有面向 Agent 的引导语：上下文中已有 Herdr 技能时跳过，否则执行 herdr --skill。

公开技能与本文的 triage 技能分工不同：前者面向「运行在 herdr pane 内的 Agent 如何控制 herdr」（并要求 HERDR_ENV=1 守卫，见 docs/next/website/src/content/docs/agent-skill.mdx 的安全规则说明）；triage 技能则面向「维护 herdr 仓库的人及其 Agent 如何管理 issue」。两者共享同一套技能文件范式：frontmatter 声明触发条件、正文给出分步操作与硬性安全边界。

参考落点

• 技能全文：.agents/skills/triage/SKILL.md
• 并列技能：.agents/skills/herdr-throwaway-repro/SKILL.md、.agents/skills/herdr-pre-release-audit/SKILL.md
• 公开技能及其安装文档：skills/herdr/SKILL.md、docs/next/website/src/content/docs/agent-skill.mdx
• 技能随二进制打包的实现：src/main.rs

如果你想为自己的项目复刻这套分诊流程，可直接参照该技能的四要素：限定触发词与作用域、按「MCP 优先、CLI 已认证回退」选择数据源、用固定列的决策表承载结论、用受控词表与「一前注后一注」的风格约束压缩输出。