setup-matt-pocock-skills

用途

setup-matt-pocock-skills 用于为一个仓库建立工程技能所假定的配置。它应在首次使用同系列其他工程技能之前运行一次。它搭建的内容包括：

• 问题跟踪器（issue tracker）——问题存放在哪里（默认 GitHub；本地 markdown 也开箱即支持）
• 分类标签（triage labels）——五个固定分类角色所使用的字符串
• 领域文档（domain docs）——CONTEXT.md 与 ADR 的位置，以及读取它们的消费规则

这是一个提示驱动的技能，不是确定性脚本：先探索、展示发现、与用户确认，然后写入。

主要能力与流程

1. 探索

查看当前仓库以了解其初始状态，读取已存在的内容而不做假设，包括：

• git remote -v 和 .git/config——是否为 GitHub 仓库、是哪一个
• 仓库根目录的 AGENTS.md 与 CLAUDE.md——是否存在，其中是否已有 ## Agent skills 区块
• 仓库根目录的 CONTEXT.md 与 CONTEXT-MAP.md
• docs/adr/ 及任何 src/*/docs/adr/ 目录
• docs/agents/——本技能此前的输出是否已存在
• .scratch/——本地 markdown 问题跟踪器约定已在使用的迹象

2. 展示发现并提问

先总结已有与缺失的内容，然后逐项引导用户完成三项决策，一次呈现一节并取得回答后再进入下一节，不会一次性抛出全部三项。假定用户不了解这些术语，每节会先做简短说明（它是什么、这些技能为何需要它、不同选择会带来什么变化），再给出选项与默认值。

A 节——问题跟踪器

“问题跟踪器”即该仓库问题存放的位置。to-issues、triage、to-prd、qa 等技能会读写它，因此需要知道是调用 gh issue create、在 .scratch/ 下写 markdown 文件，还是遵循用户描述的其他工作流。默认取向：这些技能为 GitHub 设计；若 git remote 指向 GitHub，则建议 GitHub；若指向 GitLab（gitlab.com 或自托管），则建议 GitLab。否则（或用户偏好）提供：

• GitHub——问题位于仓库的 GitHub Issues（使用 gh CLI）
• GitLab——问题位于仓库的 GitLab Issues（使用 glab CLI）
• 本地 markdown——问题以文件形式存放在本仓库的 .scratch/<feature>/ 下（适合个人项目或无远程的仓库）
• 其他（Jira、Linear 等）——请用户用一段话描述工作流，技能将记录为自由文本

仅当用户选择 GitHub 或 GitLab 时，追加一个问题：

“PR 作为请求入口”说明——开源仓库常以拉取请求而非问题形式收到功能请求，PR 是附带代码的问题。若开启，/triage 会把外部 PR 拉入同一队列，并像问题一样走同一套标签与状态（协作者正在处理的 PR 不会被动）。若 PR 不是你的请求入口，则关闭。

• PR 作为请求入口——是 / 否（默认：否）。答案记录在 docs/agents/issue-tracker.md。本地 markdown 与其他跟踪器跳过此问题——它们没有 PR。

B 节——分类标签词汇

当 triage 技能处理一个进入的问题时，会让它经过一个状态机：需要评估、等待报告者、可供 AFK 智能体领取、可供人工处理、不予修复。为此，它需要施加与你实际配置的字符串相匹配的标签（或问题跟踪器中的等价物）。若仓库已使用不同标签名（例如用 bug:triage 而不是 needs-triage），在此做映射，让技能施加正确的标签而不产生重复。

五个固定角色：

• needs-triage——维护者需要评估
• needs-info——等待报告者
• ready-for-agent——已完整说明、可 AFK（智能体无需人工上下文即可领取）
• ready-for-human——需要人工实现
• wontfix——不会被处理

默认：每个角色的字符串等于其名称。询问用户是否要覆盖任何一项。若其问题跟踪器没有已有标签，默认值即可。

C 节——领域文档

部分技能（improve-codebase-architecture、diagnosing-bugs、tdd）会读取 CONTEXT.md 以了解项目领域语言，读取 docs/adr/ 了解过往架构决策。它们需要知道仓库是单一全局上下文还是多个（例如前后端分离上下文的 monorepo），以查找正确位置。

确认布局：

• 单上下文——仓库根目录一个 CONTEXT.md + docs/adr/。多数仓库如此。
• 多上下文——根目录的 CONTEXT-MAP.md 指向各上下文的 CONTEXT.md 文件（典型为 monorepo）。

3. 确认与编辑

向用户展示草稿：将添加到 CLAUDE.md / AGENTS.md 的 ## Agent skills 区块，以及 docs/agents/issue-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md 的内容。写入前允许其编辑。

4. 写入

选择要编辑的文件：

• 若 CLAUDE.md 存在，编辑它。
• 否则若 AGENTS.md 存在，编辑它。
• 若两者都不存在，询问用户要创建哪一个——不要替其选择。

绝不在 CLAUDE.md 已存在时创建 AGENTS.md（反之亦然）——始终编辑已存在的那个。若所选文件中已存在 ## Agent skills 区块，则原地更新其内容，而不是追加重复区块。不要覆盖用户对周边章节的修改。

区块内容：

## Agent skills

### Issue tracker

[one-line summary of where issues are tracked, plus whether external PRs are a triage surface]. See `docs/agents/issue-tracker.md`.

### Triage labels

[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.

### Domain docs

[one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.

随后使用本技能文件夹中的种子模板作为起点写入三个文档文件：

• issue-tracker-github.md——GitHub 问题跟踪器
• issue-tracker-gitlab.md——GitLab 问题跟踪器
• issue-tracker-local.md——本地 markdown 问题跟踪器
• triage-labels.md——标签映射
• domain.md——领域文档消费规则 + 布局

对于“其他”问题跟踪器，依据用户描述从零编写 docs/agents/issue-tracker.md。

5. 完成

告知用户配置已完成，以及哪些工程技能现在会读取这些文件。说明他们之后可以直接编辑 docs/agents/*.md——只有在想切换问题跟踪器或从头重来时才需要重新运行本技能。

适用场景

当用户请求与以下工作流匹配时使用：为该仓库的工程技能做配置——设置其问题跟踪器、分类标签词汇与领域文档布局。在首次使用其他工程技能之前运行一次。来源为 mattpocock/skills（MIT）。

限制

• 当工作流指名上游工具、账号、API 密钥或本地环境时，需要这些条件。
• 未经用户明确批准，不授权破坏性、生产环境、付费或对外消息类操作。
• 在将生成的产物或建议视为最终版之前，应针对用户的真实来源进行验证。