Setup Matt Pocock Skills

Setup Matt Pocock's Skills

搭建 engineering skills 依赖的每仓库配置：

• Issue tracker — issues 存放在哪里（默认 GitHub；也原生支持 local markdown）
• Triage labels — 五个 canonical triage roles 使用的字符串
• Domain docs — CONTEXT.md 和 ADRs 的位置，以及读取它们的消费规则

这是 prompt-driven skill，不是确定性脚本。先探索，展示发现，和用户确认，然后再写入。

Process

1. Explore

查看当前 repo，理解起始状态。读取已有内容，不要假设：

• git remote -v 和 .git/config — 这是 GitHub repo 吗？是哪一个？
• repo 根目录的 AGENTS.md 和 CLAUDE.md — 是否存在？其中是否已经有 ## Agent skills section？
• repo 根目录的 CONTEXT.md 和 CONTEXT-MAP.md
• docs/adr/ 以及任何 src/*/docs/adr/ 目录
• docs/agents/ — 这个 skill 之前是否已经输出过内容？
• .scratch/ — 表明已经在使用 local-markdown issue tracker 约定

2. Present findings and ask

总结现有什么、缺什么。然后带用户逐一完成三个决策：每次只展示一个 section，拿到用户回答后再进入下一个。不要一次性倾倒全部三个。

假设用户不知道这些术语是什么意思。每个 section 先用简短说明开头（它是什么、为什么这些 skills 需要它、选择不同选项会改变什么），然后展示选项和默认值。

Section A — Issue tracker.

Explainer: “issue tracker” 是这个 repo 存放 issues 的地方。to-issues、triage、to-prd 和 qa 等 skills 会从中读取并写入；它们需要知道是调用 gh issue create、在 .scratch/ 下写 markdown 文件，还是遵循你描述的其他工作流。请选择你实际用来跟踪这个 repo 工作的位置。

默认姿态：这些 skills 是为 GitHub 设计的。如果 git remote 指向 GitHub，就推荐 GitHub。如果 git remote 指向 GitLab（gitlab.com 或 self-hosted host），就推荐 GitLab。否则（或用户偏好），提供：

• GitHub — issues 存放在 repo 的 GitHub Issues 中（使用 gh CLI）
• GitLab — issues 存放在 repo 的 GitLab Issues 中（使用 `glab` CLI）
• Local markdown — issues 作为文件存放在本 repo 的 .scratch/<feature>/ 下（适合个人项目或没有 remote 的 repos）
• Other（Jira、Linear 等）— 让用户用一段话描述工作流；skill 会把它记录为自由文本

Section B — Triage label vocabulary.

Explainer: triage skill 处理 incoming issue 时，会把它移过一个 state machine：需要评估、等待 reporter、已准备好给 AFK agent 接手、需要人工实现，或 won't fix。为此，它需要应用与你实际配置相匹配的 labels（或 issue tracker 中的等价物）。如果你的 repo 已经使用不同 label 名（例如 bug:triage 而不是 needs-triage），在这里映射它们，避免 skill 创建重复 labels。

五个 canonical roles：

• needs-triage — maintainer needs to evaluate
• needs-info — waiting on reporter
• ready-for-agent — fully specified, AFK-ready (an agent can pick it up with no human context)
• ready-for-human — needs human implementation
• wontfix — will not be actioned

默认：每个 role 的字符串等于它的名称。询问用户是否想覆盖任何项。如果他们的 issue tracker 还没有现有 labels，默认值即可。

Section C — Domain docs.

Explainer: 一些 skills（improve-codebase-architecture、diagnose、tdd）会读取 CONTEXT.md 来学习项目的 domain language，并读取 docs/adr/ 来了解过去的架构决策。它们需要知道 repo 是一个 global context，还是多个 contexts（例如 frontend/backend 分离的 monorepo），这样才能看对位置。

确认布局：

• Single-context — repo 根目录一个 CONTEXT.md + docs/adr/。大多数 repos 是这样。
• Multi-context — 根目录 CONTEXT-MAP.md 指向每个 context 的 CONTEXT.md 文件（通常是 monorepo）。

3. Confirm and edit

向用户展示草稿：

• 要添加到 CLAUDE.md / AGENTS.md 中的 ## Agent skills block（选择规则见 step 4）
• docs/agents/issue-tracker.md、docs/agents/triage-labels.md、docs/agents/domain.md 的内容

允许用户在写入前修改。

4. Write

选择要编辑的文件：

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

当 CLAUDE.md 已经存在时，绝不创建 AGENTS.md（反之亦然）；始终编辑已经存在的那个。

如果所选文件已经有 ## Agent skills block，就原地更新其内容，而不是追加重复 block。不要覆盖周围 section 的用户编辑。

Block：

## Agent skills

### Issue tracker

[one-line summary of where issues are tracked]. 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`.

然后使用这个 skill 文件夹中的 seed templates 作为起点，写入三个 docs files：

• issue-tracker-github.md — GitHub issue tracker
• issue-tracker-gitlab.md — GitLab issue tracker
• issue-tracker-local.md — local-markdown issue tracker
• triage-labels.md — label mapping
• domain.md — domain doc consumer rules + layout

对于 “other” issue trackers，根据用户描述从头写 docs/agents/issue-tracker.md。

5. Done

告诉用户 setup 已完成，以及哪些 engineering skills 现在会读取这些文件。说明他们之后可以直接编辑 docs/agents/*.md；只有当他们想切换 issue trackers 或从头开始时，才需要重新运行此 skill。

Domain Docs

Engineering skills 探索 codebase 时，应如何消费这个 repo 的 domain documentation。

Before exploring, read these

• repo 根目录的 `CONTEXT.md`，或
• repo 根目录的 `CONTEXT-MAP.md`（如果存在）— 它指向每个 context 的一个 CONTEXT.md。读取与当前话题相关的每个文件。
• `docs/adr/` — 读取与你即将处理区域相关的 ADRs。在 multi-context repos 中，也检查 src/<context>/docs/adr/ 中的 context-scoped decisions。

如果这些文件不存在，静默继续。不要标记缺失；不要提前建议创建。producer skill（/grill-with-docs）会在 terms 或 decisions 实际被解决时懒创建它们。

File structure

Single-context repo（大多数 repos）：

/
├── CONTEXT.md
├── docs/adr/
│   ├── 0001-event-sourced-orders.md
│   └── 0002-postgres-for-write-model.md
└── src/

Multi-context repo（根目录存在 CONTEXT-MAP.md）：

/
├── CONTEXT-MAP.md
├── docs/adr/                          ← system-wide decisions
└── src/
    ├── ordering/
    │   ├── CONTEXT.md
    │   └── docs/adr/                  ← context-specific decisions
    └── billing/
        ├── CONTEXT.md
        └── docs/adr/

Use the glossary's vocabulary

当你的输出命名某个 domain concept 时（issue title、refactor proposal、hypothesis、test name），使用 CONTEXT.md 中定义的 term。不要漂移到 glossary 明确避免的 synonyms。

如果你需要的概念还不在 glossary 中，这是一个信号：要么你正在发明项目没有使用的语言（重新考虑），要么确实存在缺口（为 /grill-with-docs 记录）。

Flag ADR conflicts

如果你的输出与现有 ADR 矛盾，明确指出，而不是静默覆盖：

_Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

Issue tracker: GitHub

这个 repo 的 issues 和 PRDs 存放在 GitHub issues 中。所有操作都使用 gh CLI。

Conventions

• Create an issue: gh issue create --title "..." --body "..."。多行 body 使用 heredoc。
• Read an issue: gh issue view <number> --comments，用 jq 过滤 comments，并同时获取 labels。
• List issues: gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'，按需加上 --label 和 --state filters。
• Comment on an issue: gh issue comment <number> --body "..."
• Apply / remove labels: gh issue edit <number> --add-label "..." / --remove-label "..."
• Close: gh issue close <number> --comment "..."

从 git remote -v 推断 repo；在 clone 内运行时，gh 会自动处理。

When a skill says "publish to the issue tracker"

创建一个 GitHub issue。

When a skill says "fetch the relevant ticket"

运行 gh issue view <number> --comments。

Issue tracker: GitLab

这个 repo 的 issues 和 PRDs 存放在 GitLab issues 中。所有操作都使用 `glab` CLI。

Conventions

• Create an issue: glab issue create --title "..." --description "..."。多行 description 使用 heredoc。传入 --description - 可打开编辑器。
• Read an issue: glab issue view <number> --comments。使用 -F json 获取 machine-readable output。
• List issues: glab issue list -F json，按需使用 --label filters。
• Comment on an issue: glab issue note <number> --message "..."。GitLab 把 comments 称为 “notes”。
• Apply / remove labels: glab issue update <number> --label "..." / --unlabel "..."。多个 labels 可以逗号分隔，也可以重复 flag。
• Close: glab issue close <number>。glab issue close 不接受 closing comment，因此先用 glab issue note <number> --message "..." 发布说明，再 close。
• Merge requests: GitLab 把 PRs 称为 “merge requests”。使用 glab mr create、glab mr view、glab mr note 等；形状与 gh pr ... 相同，只是用 mr 替代 pr，用 note/--message 替代 comment/--body。

从 git remote -v 推断 repo；在 clone 内运行时，glab 会自动处理。

When a skill says "publish to the issue tracker"

创建一个 GitLab issue。

When a skill says "fetch the relevant ticket"

运行 glab issue view <number> --comments。

Issue tracker: Local Markdown

这个 repo 的 issues 和 PRDs 作为 markdown 文件存放在 .scratch/ 中。

Conventions

• 每个 feature 一个目录：.scratch/<feature-slug>/
• PRD 是 .scratch/<feature-slug>/PRD.md
• Implementation issues 是 .scratch/<feature-slug>/issues/<NN>-<slug>.md，从 01 开始编号
• Triage state 记录为每个 issue file 顶部附近的 Status: 行（role 字符串见 triage-labels.md）
• Comments 和 conversation history 追加到文件底部的 ## Comments heading 下

When a skill says "publish to the issue tracker"

在 .scratch/<feature-slug>/ 下创建新文件（必要时创建目录）。

When a skill says "fetch the relevant ticket"

读取引用路径处的文件。用户通常会直接传入路径或 issue number。

Triage Labels

Skills 使用五个 canonical triage roles。这个文件把这些 roles 映射到此 repo issue tracker 中实际使用的 label 字符串。

当某个 skill 提到 role（例如 “apply the AFK-ready triage label”）时，使用此表中对应的 label 字符串。

编辑右侧列，使其匹配你实际使用的 vocabulary。