快记快用#

每个仓库跑一次，配置三件事：工单放哪、标签叫什么、领域文档在哪。直接输入 /setup-matt-pocock-skills，确认几个问题就完成。不跑这个，后面的技能会找不到地方放工单和文档。

一. 为什么需要 setup-matt-pocock-skills#

如果你仔细看过Matt Pocock工程系技能合集中的源码内容，那么所有技能（to-spec、to-tickets、triage、wayfinder…）全都假设一件事：知道”问题（issue）存在哪”、“标签叫什么”、“领域文档放哪”。但每个仓库都不一样：有人用 GitHub，有人用本地 markdown；有人标签叫 needs-triage，有人叫 bug:triage。

没有 setup-matt-pocock-skills 技能 , 就会出现这些事情:

to-tickets 不知道该往哪写：是使用 gh issue create 还是写个 markdown 文件？
grill-with-docs技能产生的领域文档位置应该设定在哪个位置？应该是在根目录下还是在 src/xxx/ 下？

/setup-matt-pocock-skills技能最大的作用在于，它会产下一份本地配置文件(docs/agents/*.md),让所有技能运行时，强制阅读它并按照文件中的内容行动，不用再向用户提问或者去猜。

二. 使用方法和运行机制#

通过直接在用户上下文窗口中调用该技能，该技能会通过(git remote和现有文档)直接读取你的仓库。

接下来，agent会和你需要确认三个核心配置的选择:

Issue tracker（工单放哪）,工单（issues）存在哪里,根据 git remote 自动推荐（GitHub → 用 gh；GitLab → 用 glab）,几乎总是会问（这是最核心的选择）
Triage labels（标签词汇）,五个标准 triage 角色对应的真实标签名,直接用默认五个：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix,只有安装了 triage skill 时才会问。
Domain docs（领域文档布局）,CONTEXT.md 和 ADR 放在哪里,默认 single-context（根目录一个 CONTEXT.md + docs/adr/）,只有探测到 monorepo 信号时才会问是否要 multi-context

最后将这些配置统一定下来后，所有你将使用的工程系技能都会按照你定下的配置，先读文档再进行操作。

运行机制简图#

setup-matt-pocock-skills技能的本质，是一个输入->处理->输出的过程

1
你输入：一个仓库内容信息（它自己会查 git remote、现有文档……）+ 你回答的至多 3 个核心配置决定
2
   ↓
3
它处理(5 步，前 4 步都是"一查一问一写"):
4
   1. Explore（探）     —— 读取仓库现状，只看不问
5

6
   2. Present & ask（报/问）—— 汇报发现，按 A→B→C 三节问，每节带推荐答案，已被探索搞定的节直接跳过
7

8
   3. Confirm & edit（确认）—— 要写的东西先给你看草稿，允许你修改
9

10
   4. Write（写）        —— 选 CLAUDE.md 还是 AGENTS.md，把配置写下去
11

12
   5. Done（收尾）       —— 告诉你哪些技能会读这些文件
13
   ↓
14
它输出（一段配置 + 一段入口）：
15
   │  docs/agents/issue-tracker.md  —— 问题放哪、怎么读写（必写）
16
   │  docs/agents/domain.md         —— 领域文档怎么消费（必写）
17
   │  docs/agents/triage-labels.md  —— 5 个角色名 → 真实标签映射（装了 triage 才写）
18
   │  CLAUDE.md / AGENTS.md 里       —— "## Agent skills" 段：每项一行摘要 + 指针

概念总结#

setup-matt-pocock-skills 为当前仓库搭好其他工程技能所假设的三份配置：issue 追踪器在哪（默认 GitHub，也支持本地 markdown）、5 个分流角色的标签字符串、领域文档（CONTEXT.md 与 ADR）的位置和读取规则。它把答案写成 docs/agents/ 下的 markdown 文件，并在 CLAUDE.md 或 AGENTS.md 里加一段 ## Agent skills 指过去。

技能本体在所有仓库里完全一致，只有 docs/agents/*.md 随仓库变化，技能运行时读这些文件照做。它不在主链条上，而是主链条的前置条件：to-spec、to-tickets、triage、wayfinder 都依赖它写出的文件，每个仓库跑一次。

源码解读查看仓库源码 #

SKILL.md内容深读#

part1: frontmatter#

1
name: setup-matt-pocock-skills
2
description: "Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills."
3
disable-model-invocation: true

名字:setup-matt-pocock-skills 描述:配置这个仓库给工程技能用：搭好问题追踪器、分流标签词汇、领域文档布局。在第一次用其他工程技能之前跑一次。

1
Scaffold the per-repo configuration that the engineering skills assume:
2

3
- Issue tracker: where issues live (GitHub by default; local markdown is also supported out of the box)
4

5
- Triage labels: the strings used for the five canonical triage roles
6

7
- Domain docs: where CONTEXT.md and ADRs live, and the consumer rules for reading them
8

9
This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.

搭建工程技能所假定的每个代码仓库的配置框架：

问题跟踪器：问题存放位置（默认 GitHub；也默认支持本地 Markdown）
分类标签：用于五个标准分类角色的字符串
领域文档：存放 CONTEXT.md 和 ADR 的位置，以及阅读它们的用户规则

这是一项提示驱动的技能，而非确定性的脚本。探索、展示你的发现、与用户确认，然后撰写文档。

Part 2：总纲 —— “prompt-driven，不是脚本”#

1
This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.

这是一个”提示驱动”的技能，不是确定性的脚本。探索 → 汇报发现 → 和用户确认 → 然后才写。

讲解：#

运行的四个步骤：Explore、Present、Confirm、Write——这四个词就是整个技能的骨架，后面 5 步全是它的展开。

输入没法脚本化：仓库状态（git remote、有没有 CLAUDE.md、装没装 triage）虽然是查出来的，但三个决定都是你的人类偏好——没有脚本能替你选”GitHub 还是本地 markdown”。脚本只适合”输入确定、输出确定”的事。

Part 3：Step 1 Explore#

1
Look at the current repo to understand its starting state. Read whatever exists; don't assume.

看当前仓库，理解它的起始状态。读一切存在的东西；不要假设。

讲解：#

Explore将会为后续环节的进行顺利，查询相关的配置内容

具体的Explore行为清单：

查什么	为什么查
`git remote -v`	判断 A 节默认推荐哪个追踪器（GitHub / GitLab）
根目录有没有 CLAUDE.md / AGENTS.md，有没有 `## Agent skills` 段	决定第 4 步改哪个文件、是加段还是更新段
根目录 CONTEXT.md / CONTEXT-MAP.md、`docs/adr/`	判断领域文档现状
`docs/agents/`	这个技能自己以前的产出在不在（重跑时知道自己配过什么 → 幂等）
`.scratch/`	出现了说明本地 markdown 追踪器已经在用
装没装 triage 技能	决定 B 节要不要跑
monorepo 信号（pnpm-workspace.yaml、workspaces 字段、packages/*）	决定 C 节是直接写还是停下来问

Part 4：Step 2 Present & ask#

1
Then take the sections in order. One section, one answer, then the next. Lead each section with the recommended answer so the user can accept it in a word.

按顺序来。一节、一个答案、再下一节。每节用推荐答案开头，让用户用一个词就能接受它。

讲解：#

A 节：(Issue tracker)问题追踪器。 默认操作看 remote：指向 GitHub → 推荐 GitHub；指向 GitLab → 推荐 GitLab；否则给四个选项：GitHub（gh）、GitLab（glab）、本地 markdown（.scratch/）、其他。选”其他”时，你只需一段话描述你的工作流，它原样记进配置文件

B 节：(Triage label vocabulary)分流标签。 只有装了 triage 才跑这一节（没装 = 没技能需要标签 = 整节跳过）。只问一个问题：“保留默认的 5 个标签吗？（推荐：是的）”。

默认值 = 角色名和标签字符串完全一致：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。你拒绝（通常因为追踪器已有别的叫法），它才收集覆盖值，让 triage 复用现有标签、不建重复的。

C 节：(Domain docs)领域文档。 默认单上下文，直接写，不用问。（一个 CONTEXT.md + 根目录 docs/adr/，几乎适配所有仓库。）只有探索发现 monorepo 信号，才提供”多上下文”选项（根目录 CONTEXT-MAP.md 指向各子域的 CONTEXT.md），才需要你确认。

设计要点：决策面被压到最小。 B 和 C 在”用不着你”时整节跳过；剩的问题每题先给推荐答案，你说”好”就过——这又是烤问系技能的”让回答方省力”。注意：没有给你的偏好在哪设置的地方，docs 页原话是 Config is death.（配置 = 死亡。）偏好请写进你自己的 CLAUDE.md。这是它最值得带走的流程原则——把决策面压到最小：能不问就不问（问问题的成本很高），问了就给推荐答案（让回答方省力），涉及个人偏好的地方干脆不留设置入口。

Part 5：Step 3 Confirm & edit#

1
Show the user a draft of: The `## Agent skills` block … Let them edit before writing.

先给用户看草稿：Agent skills 入口段 + 各配置文件的完整内容。让他们先改，再写。

Part 6：Step 4 Write#

1
If `CLAUDE.md` exists, edit it. Else if `AGENTS.md` exists, edit it. If neither exists, ask the user which one to create; don't pick for them. Never create `AGENTS.md` when `CLAUDE.md` already exists (or vice versa).

有 CLAUDE.md 就改它；否则有 AGENTS.md 就改它；两个都没有就问用户要建哪个，不替你选。永远不要在有 CLAUDE.md 时新建 AGENTS.md（反之亦然）。

讲解：#

只改已经存在的那个文件，绝不补建另一个。 这个操作,会防止一个仓库里出现两份互相冲突的指令文件。

写入的内容分两块：

入口段：## Agent skills 段每项一行摘要 + 一行指针（“See docs/agents/issue-tracker.md”）。细节全在配置文件里，入口只放指针——因为每次会话都会读入口，它必须短。
配置文件：用同目录 5 个种子模板作底写到 docs/agents/。重点是这些模板本身是给别的技能读的文档：它们写的是”当技能说 publish to the issue tracker 时，就……”这类运行时行为指令，不是”本仓库用 GitHub”这种陈述句。triage-labels.md 更直白——全篇一张映射表，右列留白用户填写自己的叫法。写给 AI 读的文档要写成”行为指令”：给代理看的文档，写清楚”什么输入 → 什么动作”比写事实描述更可执行。

Part 7：Step 5 + 产物的内容#

1
Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later; re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

告诉用户设置完成、哪些工程技能会读这些文件。日后可直接手改 docs/agents/*.md；只有想换追踪器或从头开始时才需要重跑。

四种产物：

写出的文件	里面有什么	哪些技能使用它们
`issue-tracker.md`	追踪器选型 + 常用读写命令 + Wayfinding 操作段	to-spec / to-tickets / triage / wayfinder
`domain.md`	领域文档阅读规则：先读什么、用词表的词、ADR 冲突要明说、文件缺失静默继续	所有要探索代码库的技能
`triage-labels.md`	5 个角色名 → 真实标签字符串映射，右列留空待填	triage
CLAUDE.md/AGENTS.md 的 Agent skills 段	三个一行摘要 + 指针	每次会话的 agent 本人

当海风翻页时

快记快用#

一. 为什么需要 setup-matt-pocock-skills#

二. 使用方法和运行机制#

运行机制简图#

概念总结#

源码解读查看仓库源码 #

SKILL.md内容深读#

part1: frontmatter#

Part 2：总纲 —— “prompt-driven，不是脚本”#

讲解：#

Part 3：Step 1 Explore#

讲解：#

Part 4：Step 2 Present & ask#

讲解：#

Part 5：Step 3 Confirm & edit#

Part 6：Step 4 Write#

讲解：#

Part 7：Step 5 + 产物的内容#

Matt Pocock 技能集

继续阅读

换条路线

当海风翻页时

快记快用#

一. 为什么需要 setup-matt-pocock-skills#

二. 使用方法和运行机制#

运行机制简图#

概念总结#

源码解读 查看仓库源码#

SKILL.md内容深读#

part1: frontmatter#

Part 2：总纲 —— “prompt-driven，不是脚本”#

讲解：#

Part 3：Step 1 Explore#

讲解：#

Part 4：Step 2 Present & ask#

讲解：#

Part 5：Step 3 Confirm & edit#

Part 6：Step 4 Write#

讲解：#

Part 7：Step 5 + 产物的内容#

分享文章

沿着主题读

换条路线

源码解读查看仓库源码 #