setup-matt-pocock-skills

Files (7)

• SKILL.md
• openai.yaml · agents/
• domain.md
• issue-tracker-github.md
• issue-tracker-gitlab.md
• issue-tracker-local.md
• triage-labels.md

SKILL.md (first lines)

# Setup Matt Pocock's Skills

搭好 engineering skills 所假定的按仓库配置：

- **Issue tracker** — issues 存放在哪（默认 GitHub；开箱也支持本地 markdown）
- **Triage labels** — 五个规范分诊角色所用的字符串
- **Domain docs** — `CONTEXT.md` 和 ADRs 放在哪，以及读取它们的消费规则

这是由 prompt 驱动的 skill，不是确定性脚本。先探索、呈现你发现的内容、与用户确认，然后再写入。

## 流程

### 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/` — 本 skill 先前的输出是否已存在？
- `.scratch/` — 表明本地 markdown issue tracker 约定已在使用
- `triage` skill 是否已安装？（与本 skill 并列的 `triage` skill 文件夹，或你可用 skills 里有 `triage`。）这决定 Section B 是否会跑。
- Monorepo 信号 — `pnpm-workspace.yaml`、`package.json` 里的 `workspaces` 字段，或已有内容的 `packages/*` 且各自带 `src/`。只在真正大型多包仓库里提出；没有这些信号就表示单上下文，几乎每个仓库都是如此。

### 2. 呈现发现并提问

概括已有什么、缺什么。然后按顺序处理各节——一节一个回答，再下一节。

每节先给出推荐答案，让用户一句话就能接受。只有选择真正会分叉时才给一行解释；探索已经定下来的节直接跳过（未安装 `triage` 时跳过 Section B，没有 monorepo 时跳过 Section C）。

**Section A — Issue tracker。**

> 解释："issue tracker" 是本仓库 issues 存放的地方。像 `to-tickets`、`triage` 和 `to-spec` 这样的 skills 会读写它——它们需要知道该调用 `gh issue create`、在 `.scratch/` 下写 markdown 文件，还是遵循你描述的其他工作流。选你实际用来跟踪本仓库工作的地方。

默认姿态：这些 skills 是为 GitHub 设计的。若 `git remote` 指向 GitHub，就提议 GitHub。若 `git remote` 指向 GitLab（`gitlab.com` 或自托管主机），就提议 GitLab。否则（或用户更偏好时），提供：

- **GitHub** — issues 放在仓库的 GitHub Issues（使用 `gh` CLI）
- **GitLab** — issues 放在仓库的 GitLab Issues（使用 [`glab`](https://gitlab.com/gitlab-org/cli) CLI）
- **Local markdown** — issues 作为文件放在本仓库 `.scratch/<feature>/` 下（适合个人项目或没有 remote 的仓库）
- **Other**（Jira、Linear 等）— 请用户用一段话描述工作流；skill 会把它记成自由散文

把选择记录在 `docs/agents/issue-tracker.md`。GitHub 和 GitLab 模板带有 "PRs as a request surface" 标志，默认 **off**——保持关闭，不要主动提出；若用户希望外部 PRs 进入分诊队列，可稍后在文件里把该标志翻过来。

**Section B — 分诊标签词汇。** 若探索表明 `triage` skill 未安装，整节跳过——未安装的 skill 不需要标签。

若已安装，只问一个问题：

> 要保留默认的分诊标签吗？（推荐：**yes**）

默认值是五个规范角色，每个标签字符串等于其名称：`needs-triage`、`needs-info`、`ready-for-agent`、`ready-for-human`、`wontfix`。选 **yes** 时原样写入。只有用户说 no 时——通常是因为他们的 tracker 已在用别的名字（例如用 `bug:triage` 对应 `needs-triage`）——收集覆盖项，让 `triage` 应用已有标签而不是创建重复标签。

**Section C — Domain docs。** 默认 **single-context** —— 仓库根一份 `CONTEXT.md` + `docs/adr/`。这适合几乎每个仓库；直接写入，不必询问。

仅当探索发现 monorepo 信号时，才提供 **multi-context** —— 根目录一份 `CONTEXT-MAP.md`，指向各上下文的 `CONTEXT.md`。然后确认他们想要哪种布局。

### 3. 确认并编辑

向用户展示草稿：

- 将加入正在编辑的 `CLAUDE.md` / `AGENTS.md` 的 `## Agent skills` 块（选择规则见步骤 4）
- `docs/agents/issue-tracker.md`、`docs/agents/domain.md` 和 `docs/agents/triage-labels.md` 的内容（最后一项仅在安装了 `triage` 时）

写入前让他们编辑。

### 4. 写入

**选择要编辑的文件：**

- 若存在 `CLAUDE.md`，编辑它。
- 否则若存在 `AGENTS.md`，编辑它。
- 若两者都不存在，问用户要创建哪一个——不要替他们选。

永远不要在已有 `CLAUDE.md` 时创建 `AGENTS.md`（反之亦然）——始终编辑已经存在的那一个。

若所选文件里已有 `## Agent skills` 块，就地更新其内容，不要再追加一份重复的。不要覆盖用户对周围章节的编辑。

该块：

```markdown
## 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`.
```

仅当 `triage` 已安装且跑过 Section B 时，才包含 `### Triage labels` 子块，并写入 `docs/agents/triage-labels.md`。未安装时两者都省略。

然后以本 skill 文件夹中的种子模板为起点写入文档文件：

- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
- [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
- [issue-tracker-local.md](./issue-tracker-local.md) — 本地 markdown issue tracker
- [triage-labels.md](./triage-labels.md) — 标签映射（仅当安装了 `triage`）
- [domain.md](./domain.md) — 领域文档消费规则 + 布局

对于 "other" issue trackers，根据用户描述从零编写 `docs/agents/issue-tracker.md`。

### 5. 完成

告诉用户配置已完成，以及哪些 engineering skills 现在会读取这些文件。说明他们之后可以直接编辑 `docs/agents/*.md`——只有想切换 issue tracker 或从头再来时，才需要重新跑本 skill。

From shenjunjian/matt-skill-cn, MIT.

More from shenjunjian/matt-skill-cn