setup-matt-pocock-skills 的问题跟踪器集成边界：为什么只支持主流工具

setup-matt-pocock-skills 的问题跟踪器集成边界：为什么只支持主流工具

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills

setup-matt-pocock-skills是本仓库中用于为工程技能套件做一次性仓库配置的 skill（配置说明），其中"问题跟踪器（issue tracker）"配置决定了/to-tickets、/triage、/to-spec等技能读写 issue 的方式。本文以 .out-of-scope/mainstream-issue-trackers-only.md 这份边界决策文档为主线，结合仓库源码，解析"为什么只对主流问题跟踪器提供一等支持"这一设计取舍：从 CLI 形状硬编码带来的永久维护成本，到"主流"这一判断标准的真实含义，再到local markdown与other/custom两条逃生舱路径。读完你将理解该 skill 的集成边界判定逻辑，并能在自己的仓库中判断该选哪种跟踪器接入方式。

一、决策结论：一等支持仅限于主流工具

该文档给出的核心结论非常明确：

setup-matt-pocock-skillsonly offers first-class support formainstreamissue trackers. Requests to add support for niche, new, or single-vendor experimental trackers are out of scope.

即：setup-matt-pocock-skills只为"主流"问题跟踪器提供一等（first-class）支持；为小众、新出现或单一厂商的实验性跟踪器新增支持，属于明确的范围之外（out of scope）。这份文件本身存放在仓库的 .out-of-scope/ 目录下，正是被拒绝功能请求的知识库的一部分。

这一决策直接影响配置流程的第一个问题——SKILL.md 的 Section A：Issue tracker 中，"选一个你真正跟踪工作的场所"是所有后续技能（to-tickets、triage、to-spec）工作的前提。可选项只有四个：

• GitHub：issue 存放在仓库的 GitHub Issues，通过ghCLI 操作；
• GitLab：issue 存放在仓库的 GitLab Issues，通过glabCLI 操作；
• Local markdown：issue 以文件形式存放在仓库.scratch/<feature>/目录下（适合单人项目或无远程仓库的场景）；
• Other（Jira、Linear 等）：让用户用一段话描述工作流，skill 以自由文本形式记录。

注意这里没有"随便再加一个"的选项——新增的跟踪器支持请求会被拒之门外，这正是本文要解析的边界所在。

二、为什么这属于范围之外：CLI 形状硬编码与永久维护成本

文档给出了一个成本模型式的理由，值得逐句拆解：

Every issue-tracker backend hard-codes a CLI shape into the skills (commands, flags, output parsing). Each new backend is permanent maintenance surface, because it has to keep working as the tool's CLI evolves, and it has to keep being tested against/to-spec,/to-tickets,/triage, and friends.

核心逻辑链条是：

1. 每个跟踪器后端都会把一套 CLI 形状硬编码进技能中——包括命令、参数（flags）和输出解析（output parsing）。也就是说，技能内部并不是"通过通用 API 抽象层"接入任意跟踪器，而是把某个具体 CLI 的调用方式写死在约定里；
2. 每个新后端都是一块永久的维护面——因为底层工具的 CLI 会持续演化，接入代码必须跟着保持可用；
3. 必须持续针对/to-spec、/to-tickets、/triage等技能进行测试——新增后端不是"写一个适配器就完事"，而是要在整条技能链路上持续验证。

这种成本只值得为"相当比例用户真正在用的工具"付出。

从仓库模板看"CLI 形状硬编码"的具体形态

"硬编码 CLI 形状"不是抽象说法，仓库中的种子模板给出了具体的实证。issue-tracker-github.md 和 issue-tracker-gitlab.md 分别把gh和glab两个 CLI 的操作方式写成了逐条约定。

以 GitHub 模板为例，每条操作都精确到命令级别：

• 创建 issue：gh issue create --title "..." --body "..."，多行正文用 heredoc；
• 读取 issue：gh issue view <number> --comments，配合jq过滤评论并获取标签；
• 列出 issue：gh issue list --state open --json number,title,body,labels,comments --jq '...'，配合--label与--state过滤；
• 评论：gh issue comment <number> --body "..."；
• 加/删标签：gh issue edit <number> --add-label "..."/--remove-label "..."；
• 关闭：gh issue close <number> --comment "..."。

GitLab 模板则是另一套完全不同的形状：glab issue create --title "..." --description "..."、评论叫note（glab issue note <number> --message "..."）、标签操作用--label/--unlabel、且glab issue close不接受关闭评论，需要先发说明再关闭。连术语都不同——PR 在 GitLab 里叫 merge request（MR）。

此外，两个平台在编号空间上也截然不同：GitHub 的 issue 和 PR 共享一个编号空间（#42可能是 issue 也可能是 PR，需要gh pr view 42失败后回退到gh issue view 42），而 GitLab 分开编号（#42一旦确定表面就没有歧义）。这些平台差异全部沉淀为模板中的平台专属约定，而不是技能共享的抽象——这正是"每个后端都是一块永久维护面"的根源。

从代码结构看，这些差异被设计为约定文档（convention doc）而非可执行适配器：模板写入docs/agents/issue-tracker.md后，triage等技能通过读取该文件得知应该调用哪套 CLI 形状（参见 triage 技能的 invocation 逻辑 中"以/triage触发、按 issue-tracker 配置行动"的描述）。这意味着任何新增后端都需要同步维护一份新的约定文档，并保证其与技能实际行为一致。

三、"主流"是判断而非数字：判定标准解析

文档明确指出：

"Mainstream" is a judgment call, not a numeric bar.

"主流"是一个判断（judgment call），而不是数字门槛（numeric bar）。文档给了两个方向的例子来锚定这个判断：

• 属于主流的：GitHub、GitLab、Backlog.md——"broadly known, widely used, well past the experimental phase"（广为人知、被广泛使用、早已过了实验阶段）的工具；
• 不属于主流的：一个只有几百颗 GitHub star 的、面向 agent 的全新工具——"no matter how interesting the design"（无论设计多有趣都不算）。

文档进一步澄清了信号与规则的区别：

Stars, age, and download counts are useful signals when making the call but none of them is the rule. The rule is: would a typical engineer recognise this tool and have plausibly chosen it for their team?

• 信号（signals）：star 数、年龄、下载量，这些在判断时是有用的参考，但没有哪一条单独构成规则；
• 规则（the rule）：一个典型工程师是否会认出这个工具，并且有理由为他们的团队选择它。

这是一个"可迁移的判断标准"——不绑定某个具体数字，而是模拟真实工程师的认知与选型行为。从仓库证据看，这一判断正是通过 Prior requests 这样的真实案例逐步校准的（见下文 #99 案例）。

四、逃生舱：非主流跟踪器的既有两条路径

文档强调，拒绝新增后端不意味着非主流工具无路可走，两条逃生舱（escape hatches）已经存在：

• local markdownfor lightweight in-repo tracking.
• other/customfor users who want to wire something up themselves.
• Neither requires the core skills to know about the specific tool.

逃生舱一：local markdown——轻量级的仓库内跟踪。其约定在 issue-tracker-local.md 中有完整定义：每个功能一个目录.scratch/<feature-slug>/，spec 为.scratch/<feature-slug>/spec.md，实现 issue 按issues/<NN>-<slug>.md从01起逐个编号（且明确要求"绝不合并成一个 tickets 文件"），triage 状态用文件内Status:行记录，评论追加在## Comments标题下。这套约定同样支持/wayfinder的完整流程：map 是.scratch/<effort>/map.md，子 ticket 是独立文件，阻塞关系用Blocked by: NN, NN行表达。

逃生舱二：other/custom——用户自己接线。按 SKILL.md 的 Section A 的说明，选择 Other（Jira、Linear 等）时，技能让用户用一段话描述其工作流，并把这段自由文本记录为docs/agents/issue-tracker.md的内容。

两条逃生舱的共同点是：核心技能都不需要"认识"那个具体工具。local markdown只需要文件系统读写约定，other/custom只需要消费一段用户提供的工作流描述——这正好呼应了前文"每个后端都是一块永久维护面"的结论：逃生舱路径把"让技能理解具体工具"的成本省掉了，因此不需要为小众工具付出维护代价。

五、三套后端的配置落点：docs/agents/ 下的约定文件

无论选哪条路径，最终配置都会落到仓库的docs/agents/目录，由 SKILL.md 的 Step 4 Write 写入：

• issue-tracker-github.md →docs/agents/issue-tracker.md（GitHub 模板）；
• issue-tracker-gitlab.md →docs/agents/issue-tracker.md（GitLab 模板）；
• issue-tracker-local.md →docs/agents/issue-tracker.md（Local markdown 模板）；
• "other" 场景则从零手写docs/agents/issue-tracker.md。

这解释了文档中"针对/to-spec、/to-tickets、/triage持续测试"的维护面为何真实存在：GitHub 与 GitLab 模板中还有"PR/MR as a request surface"开关（默认 off），/triage会读取这个标志来决定是否把外部 PR 纳入分诊队列；triage技能的状态机（needs-triage→needs-info/ready-for-agent/ready-for-human/wontfix，参见 triage 技能的角色定义）需要与每个后端的标签操作命令一一对应。每新增一个后端，上述所有环节都要重新适配、回归测试——这就是"永久维护面"的全部内涵。

六、这份文档本身：out-of-scope 知识库的运转机制

值得指出的是，本决策文档是仓库 .out-of-scope/ 知识库的一份活样本。根据 triage 技能的 OUT-OF-SCOPE.md，这个目录持久化记录被拒绝的功能请求，有两个用途：

1. 机构记忆（institutional memory）：功能被拒绝的理由在 issue 关闭后不丢失；
2. 去重（deduplication）：新 issue 与既有拒绝记录匹配时，技能直接引用旧决策，而不是重新争论一遍。

文件按概念（concept）而非按 issue 命名——多个请求同一件事的 issue 归入同一个文件。写作风格要求像一份简短的设计文档（可读性强、有理由、有例子），而非数据库条目。命名用短小的 kebab-case（如mainstream-issue-trackers-only.md本身就是）。

在/triage的 Step 1 "Gather context" 中，技能会读取.out-of-scope/*.md，把与新请求相似的既有拒绝记录呈递给维护者（"This is similar to .out-of-scope/... We rejected this before because..."）。本仓库中另有一份同构文件 .out-of-scope/question-limits.md（关于 grilling 不设问题数量上限的边界），展示了这一知识库的一致格式：核心声明 → Why this is out of scope → Prior requests。

对本文主题而言，这意味着新增 issue-tracker 后端的请求被拒后，会按此机制被归并到本文件，避免未来重复讨论。

七、真实案例：Prior requests 中的 #99

文档记录了一个真实的历史请求作为判定基准：

• #99: "Add dex as an issue tracker backend" (dex was ~3 months old and ~300 stars at the time of the request)

在提出请求时，dex 大约只有 3 个月历史、约 300 颗 star。它完美命中了文档描述的"反面教材"形态：全新、面向 agent、star 数远低于任何主流工具。按第三节的判断规则，一个典型工程师不太可能在团队里选型一个 3 个月大、300 star 的跟踪器——因此该请求被判定为范围之外。

这个案例同时演示了信号（age、stars）如何辅助判断、却不替代判断：~3 个月与 ~300 star 本身不构成规则，它们是"新工具仍处实验阶段"这一判断的具体证据。

八、实践建议：你的仓库该怎么选

结合 SKILL.md 的 Section A 的默认姿态（designed for GitHub；git remote 指向 GitHub 就建议 GitHub，指向 GitLab 就建议 GitLab），以及本文的边界决策，接入方式的选择逻辑可以概括为：

• 仓库托管在 GitHub：直接用 GitHub +ghCLI，一等支持、开箱即用；
• 仓库托管在 GitLab（含自托管）：用 GitLab +glabCLI，同样是一等支持；
• 单人项目或没有远程仓库：local markdown足够轻量，零外部依赖；
• 团队用的是 Jira、Linear 等未内置工具：选other/custom，用一段话描述工作流写入docs/agents/issue-tracker.md；
• 想让技能"原生认识"一个小众或实验性跟踪器：按本决策文档，这属于范围之外，不会被纳入一等支持——但上述逃生舱路径随时可用。

无论哪种选择，配置都会写入docs/agents/issue-tracker.md，后续可随时直接编辑该文件（如切换PRs as a request surface标志）；只有要整体更换跟踪器时才需要重跑setup-matt-pocock-skills。

九、总结

setup-matt-pocock-skills对问题跟踪器采取"主流优先"的一等支持策略，本质是一个成本模型：每个后端都要硬编码 CLI 形状（命令、参数、输出解析），都要在工具 CLI 演化中持续维护，都要针对/to-spec、/to-tickets、/triage等技能链路持续测试。因此"主流"被定义为一种判断而非数字——以"典型工程师是否会认出并选型该工具"为准绳，star 数、年龄、下载量只是辅助信号。非主流工具并非无路可走：local markdown与other/custom两条逃生舱让用户在不增加核心技能维护负担的前提下完成接入。这一决策连同其 原始边界文档，通过.out-of-scope/知识库机制沉淀为可复用的拒绝记忆，为后续同类请求提供一致的判定依据。

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills