Codex 中使用 `mattpocock/skills` 的完整教程

Administrator

2026-06-10

Skills

适用范围：Codex CLI、Codex IDE Extension、Codex App 的本地项目工作流。Codex 官方文档说明，Agent Skills 可在 Codex CLI、IDE Extension 和 Codex App 中使用；本教程不把 Codex Web/云端任务作为主路径。
参考：https://developers.openai.com/codex/skills

1. 先理解：`mattpocock/skills` 是什么

mattpocock/skills 是 Matt Pocock 公开的一组 Agent Skills，用来把真实软件工程中的常见流程拆成可复用的技能，例如需求盘问、TDD、架构改进、问题诊断、PRD/Issue 拆分等。

仓库地址：

https://github.com/mattpocock/skills

在 Codex 里，Skill 本质上是一个目录，目录里必须有 SKILL.md，也可以包含：

scripts/
references/
assets/

Codex 会先读取每个 skill 的 name、description 和路径，只有在需要时才加载完整的 SKILL.md。这叫 progressive disclosure。

2. 准备环境

2.1 安装 Codex CLI

macOS 或 Linux：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

也可以用 npm 或 Homebrew：

npm install -g @openai/codex
brew install --cask codex

安装后运行：

codex

然后用 ChatGPT 账号或 OpenAI API key 登录。

参考：

https://developers.openai.com/codex/quickstart

2.2 安装 Node.js / npm

因为 Matt 的推荐安装方式使用：

npx skills@latest add mattpocock/skills

所以你的机器上需要有 Node.js 和 npm。

检查命令：

node -v
npm -v
npx -v

如果这些命令没有输出版本号，先安装 Node.js。

2.3 建议准备 Git 和 GitHub CLI

如果你要使用 to-prd、to-issues、triage 这类跟 issue tracker 相关的 skills，建议安装并登录 GitHub CLI：

gh auth login
gh issue list

setup-matt-pocock-skills 会询问 issue tracker。如果你的项目使用 GitHub，它通常会配合 gh CLI 使用。

3. 推荐安装方式：用 `npx skills@latest`

进入你平时使用 Codex 的项目目录：

cd /path/to/your/project

运行安装器：

npx skills@latest add mattpocock/skills

安装器通常会让你选择：

要安装哪些 skills。
要安装到哪些 coding agents。
是否包含 /setup-matt-pocock-skills。

我建议第一批至少选择：

setup-matt-pocock-skills
grill-with-docs
grill-me
tdd
diagnose
zoom-out
improve-codebase-architecture
to-prd
to-issues
triage
handoff
prototype

可以暂时不选：

git-guardrails-claude-code

原因是它更偏 Claude Code hooks。Codex 的命令管控更适合用 Codex Rules / permissions 机制处理。

4. Codex Skills 应该安装到哪里

Codex 会扫描多个位置。常用位置如下：

作用域	路径	适合场景
当前目录	`$CWD/.agents/skills`	只对当前启动 Codex 的目录生效
Git 仓库根目录	`$REPO_ROOT/.agents/skills`	团队共享，建议提交到仓库
用户级	`$HOME/.agents/skills`	个人所有项目通用
管理员级	`/etc/codex/skills`	机器或容器级默认 skills

建议：

个人长期使用：装到 ~/.agents/skills
团队统一流程：装到 <repo>/.agents/skills 并提交到 Git
临时试用：装到当前项目的 .agents/skills

5. 如果安装器没有正确识别 Codex：手动安装

通常不需要手动安装。但如果 npx 安装后 Codex 里看不到 skills，可以手动把 skill 文件夹复制到 Codex 扫描路径。

5.1 macOS / Linux：复制到用户级 skills

mkdir -p ~/.agents/skills

tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/mattpocock/skills "$tmp"

for d in "$tmp"/skills/{engineering,productivity,misc}/*; do
  if [ -f "$d/SKILL.md" ]; then
    cp -R "$d" "$HOME/.agents/skills/"
  fi
done

ls ~/.agents/skills

5.2 macOS / Linux：复制到当前仓库，供团队共享

mkdir -p .agents/skills

tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/mattpocock/skills "$tmp"

for d in "$tmp"/skills/{engineering,productivity,misc}/*; do
  if [ -f "$d/SKILL.md" ]; then
    cp -R "$d" .agents/skills/
  fi
done

git status

然后可以把 .agents/skills 提交到仓库：

git add .agents/skills
git commit -m "Add Matt Pocock agent skills"

5.3 Windows PowerShell：复制到用户级 skills

$dest = "$HOME\.agents\skills"
New-Item -ItemType Directory -Force $dest | Out-Null

$temp = New-Item -ItemType Directory -Path ([System.IO.Path]::GetTempPath()) -Name "matt-skills-$([guid]::NewGuid())"
git clone --depth 1 https://github.com/mattpocock/skills $temp.FullName

Get-ChildItem "$($temp.FullName)\skills" -Directory | ForEach-Object {
  Get-ChildItem $_.FullName -Directory | Where-Object {
    Test-Path (Join-Path $_.FullName "SKILL.md")
  } | ForEach-Object {
    Copy-Item $_.FullName -Destination $dest -Recurse -Force
  }
}

Get-ChildItem $dest

6. 在 Codex 中确认 skills 已加载

进入项目目录后启动 Codex：

cd /path/to/your/project
codex

在 Codex CLI 里输入：

/skills

然后检查列表里是否有：

setup-matt-pocock-skills
grill-with-docs
tdd
diagnose
zoom-out

你也可以用 $ 直接提及 skill，例如：

$tdd

注意：Matt 的 README 可能使用 /setup-matt-pocock-skills 这种写法，这更接近 Claude Code 的 slash-command 习惯。在 Codex 里，更稳妥的方式是：

/skills

然后从菜单里选择 setup-matt-pocock-skills。

或者直接输入：

$setup-matt-pocock-skills

7. 第一次必须做：运行 `setup-matt-pocock-skills`

setup-matt-pocock-skills 会为当前仓库生成 Matt 这套工程 skills 需要的配置。它主要处理三件事：

Issue tracker：GitHub、GitLab、本地 Markdown 或其他流程。
Triage labels：needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix。
Domain docs：单上下文 CONTEXT.md + docs/adr/，或 monorepo 的 CONTEXT-MAP.md 多上下文布局。

在 Codex 中输入：

$setup-matt-pocock-skills

请为当前仓库初始化 Matt Pocock skills。优先使用 AGENTS.md；issue tracker 如果 git remote 是 GitHub 就用 GitHub，否则用 local markdown；triage labels 使用默认五类；domain docs 使用 single-context。先展示将要写入的内容，再修改文件。

setup skill 通常会尝试写入：

AGENTS.md 或 CLAUDE.md
docs/agents/issue-tracker.md
docs/agents/triage-labels.md
docs/agents/domain.md

8. 重要：Codex 更应该用 `AGENTS.md`

Codex 官方项目指令文件是：

AGENTS.md

建议在仓库根目录创建：

touch AGENTS.md

然后再运行：

$setup-matt-pocock-skills

如果你的仓库已经有 CLAUDE.md，setup 可能会优先编辑 CLAUDE.md。这时可以让 Codex 同步：

请把 CLAUDE.md 中的 ## Agent skills 区块同步复制到 AGENTS.md，保留 CLAUDE.md 不变。Codex 以后以 AGENTS.md 为准。

9. 推荐的 `AGENTS.md` 模板

可以在仓库根目录创建或补充：

# AGENTS.md

## Working agreements

- Prefer small, reviewable diffs.
- Before implementing ambiguous product changes, use `$grill-with-docs`.
- For bug fixes or performance regressions, use `$diagnose`.
- For implementation, prefer `$tdd` and follow red-green-refactor.
- After code changes, run the project’s relevant checks before summarizing.
- Do not add new production dependencies without explaining why.

## Project commands

- Install: `pnpm install`
- Typecheck: `pnpm typecheck`
- Test: `pnpm test`
- Lint: `pnpm lint`
- Build: `pnpm build`

## Agent skills

### Issue tracker

Work items are tracked in GitHub Issues. See `docs/agents/issue-tracker.md`.

### Triage labels

Use the default Matt Pocock triage labels. See `docs/agents/triage-labels.md`.

### Domain docs

This repo uses a single-context domain model: `CONTEXT.md` plus `docs/adr/`. See `docs/agents/domain.md`.

根据你的项目，把 pnpm 命令改成实际命令即可。

10. 常用工作流

10.1 新功能：先盘问，再写 PRD，再拆 Issue

第一步，用 grill-with-docs 对齐需求：

$grill-with-docs

我要实现：用户可以在账单页下载发票 PDF。

请先阅读相关代码、CONTEXT.md 和 docs/adr/。然后一次只问我一个问题，盘问需求、边界条件、数据来源、权限、错误状态和测试策略。每个问题都给出你的推荐答案。

第二步，把对齐后的上下文变成 PRD：

$to-prd

请把我们当前对“发票 PDF 下载”的共识整理成 PRD。如果 GitHub CLI 可用，请创建 GitHub issue；否则保存到 .scratch/invoice-pdf/prd.md。

第三步，把 PRD 拆成垂直切片 issues：

$to-issues

请把这个 PRD 拆成可以独立交给 agent 执行的垂直切片 issues。每个 issue 必须包含验收标准、测试建议、涉及模块和不做什么。

10.2 实现功能：用 TDD

$tdd

实现 issue #123：用户可以在账单页下载发票 PDF。

要求：
1. 先写一个失败测试。
2. 只实现让该测试通过的最小代码。
3. 每次只做一个 vertical slice。
4. 每轮运行相关测试。
5. 不要一次性写完所有测试。

tdd skill 的核心是：

red -> green -> refactor

也就是：

先写失败测试。
写最小实现让测试通过。
重构。
重复下一轮。

重点是 vertical slice，不要一次性写完所有测试再一次性实现所有代码。

10.3 修 bug：用 `diagnose`

$diagnose

线上出现这个错误：

<粘贴错误日志>

请按 reproduce → minimise → hypothesise → instrument → fix → regression-test 的顺序处理。先不要直接改代码，先告诉我你如何复现和缩小问题。

适合以下场景：

难复现 bug
性能回归
测试偶发失败
复杂状态错误
生产环境日志分析

10.4 看不懂代码：用 `zoom-out`

$zoom-out

我不熟悉 `src/billing/invoices` 这一块。请上升一个抽象层次，画出相关模块、调用方、数据流和关键 domain terms。

适合以下场景：

接手陌生模块
重构前理解代码
让 Codex 解释某个目录的职责
找出调用关系
理解 domain glossary

10.5 架构整理：用 `improve-codebase-architecture`

$improve-codebase-architecture

请阅读 CONTEXT.md、docs/adr/ 和 billing 相关代码，找出 3 个最值得改善的架构点。不要直接大改，先给出：
1. 当前结构的问题
2. 为什么它会变坏
3. 小步重构计划
4. 每一步的验证方式

适合以下场景：

代码开始变乱
模块边界不清楚
想重构但不知道从哪里开始
需要让 agent 找出架构层面的 deepening opportunities

10.6 接力开发：用 `handoff`

当一个任务做到一半，需要交给下一个 agent 或下一个会话继续时：

$handoff

请为当前任务生成 handoff 文档，包含：
1. 当前目标
2. 已完成内容
3. 未完成内容
4. 关键文件
5. 已运行的命令
6. 当前失败点
7. 下一步建议

10.7 快速原型：用 `prototype`

$prototype

请为“发票 PDF 下载”做一个最小可运行原型。目标是验证技术路径，不要求最终架构。请明确哪些代码只是 prototype，哪些可以保留。

适合：

验证方案是否可行
探索第三方库
比较两种实现路线
先跑通端到端流程

11. 更新 skills

使用安装器更新：

npx skills@latest add mattpocock/skills

如果你是手动安装，可以重新 clone 后覆盖复制：

mkdir -p ~/.agents/skills

tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/mattpocock/skills "$tmp"

for d in "$tmp"/skills/{engineering,productivity,misc}/*; do
  if [ -f "$d/SKILL.md" ]; then
    rm -rf "$HOME/.agents/skills/$(basename "$d")"
    cp -R "$d" "$HOME/.agents/skills/"
  fi
done

更新后重启 Codex。

12. 禁用某个 skill

不用删除文件，也可以在 ~/.codex/config.toml 禁用：

[[skills.config]]
path = "/Users/you/.agents/skills/tdd/SKILL.md"
enabled = false

修改后重启 Codex。

13. 常见问题排查

13.1 `/skills` 里看不到 Matt 的 skills

检查目录结构是否正确：

ls ~/.agents/skills/tdd/SKILL.md
ls .agents/skills/tdd/SKILL.md

正确结构应该是：

~/.agents/skills/
  tdd/
    SKILL.md
  grill-with-docs/
    SKILL.md
  setup-matt-pocock-skills/
    SKILL.md

错误结构通常是：

~/.agents/skills/
  skills/
    engineering/
      tdd/
        SKILL.md

如果路径正确但仍不显示：

1. 退出 Codex
2. 重新进入项目目录
3. 再运行 codex
4. 输入 /skills 检查

13.2 `$setup-matt-pocock-skills` 没触发

优先用：

/skills

然后从菜单里选择：

setup-matt-pocock-skills

13.3 setup 写到了 `CLAUDE.md`，Codex 没读到

解决：

请把 CLAUDE.md 中的 ## Agent skills 区块同步到 AGENTS.md。以后 Codex 以 AGENTS.md 为准。

也可以手动复制相关区块。

13.4 GitHub issue 创建失败

检查：

gh auth status
gh repo view
gh issue list

如果你的项目不用 GitHub Issues，可以重新运行 setup，并选择：

Local markdown

这样 issues 会写到类似下面的位置：

.scratch/<feature>/

13.5 Codex 乱跑命令或权限太大

建议：

调低 Codex 权限。
使用 Codex Rules 控制哪些命令可以运行。
在 AGENTS.md 里明确禁止危险命令。
让 Codex 在运行 destructive command 前先解释并请求确认。

可以在 AGENTS.md 加：

## Safety rules

- Do not run destructive commands such as `rm -rf`, `git reset --hard`, or database migrations unless explicitly requested.
- Before modifying package dependencies, explain why the dependency is needed.
- Prefer read-only exploration before editing files.
- Show a short plan before large refactors.

14. 推荐实践

14.1 先少装，再扩展

第一批装这些就够：

setup-matt-pocock-skills
grill-with-docs
tdd
diagnose
zoom-out

等熟悉后再加：

to-prd
to-issues
triage
handoff
prototype
improve-codebase-architecture

14.2 每个仓库先跑一次 setup

每个项目第一次使用时，先运行：

$setup-matt-pocock-skills

这样可以把以下约定固化到仓库：

issue tracker
triage labels
domain docs
agent workflow

14.3 Codex 项目优先维护 `AGENTS.md`

Codex 项目中，建议把团队指令写到：

AGENTS.md

不要只写在：

CLAUDE.md

如果团队同时使用 Claude Code 和 Codex，可以两个文件都保留，但要同步关键区块。

14.4 复杂需求先 `grill-with-docs`

不要一上来就说：

帮我实现发票 PDF 下载

更好的方式是：

$grill-with-docs

我要实现发票 PDF 下载。请先盘问我需求、权限、边界、测试和现有 domain model，不要急着写代码。

14.5 实现时用 `$tdd`

$tdd

请用 red-green-refactor 实现这个 issue。一次只写一个失败测试和对应最小实现。

14.6 遇到 bug 用 `$diagnose`

不要让 agent 直接猜修复。应该要求它先复现、缩小、假设、插桩：

$diagnose

请先复现这个问题，缩小触发条件，再提出假设。没有复现前不要改代码。

14.7 团队共享时，把这些文件一起提交

建议提交：

.agents/skills/
AGENTS.md
docs/agents/issue-tracker.md
docs/agents/triage-labels.md
docs/agents/domain.md
CONTEXT.md
docs/adr/

14.8 定期 review skills

Skill 本质上是 agent 指令和可选脚本。安装公开仓库里的 skills 后，建议像审查依赖一样审查：

SKILL.md
scripts/
references/
assets/

特别是 scripts 目录里是否包含会修改文件、运行外部命令或访问网络的逻辑。

15. 一个完整的日常使用示例

15.1 进入项目

cd ~/work/my-app
codex

15.2 查看 skills

/skills

选择：

setup-matt-pocock-skills

输入：

请初始化当前仓库的 Matt Pocock skills 配置。使用 AGENTS.md、GitHub Issues、默认 triage labels、single-context domain docs。先展示计划，再写文件。

15.3 新功能需求盘问

$grill-with-docs

我要做“用户可以下载发票 PDF”。请先读 billing/invoices 相关代码和 CONTEXT.md，然后一次一个问题盘问我，直到需求、边界、权限、测试策略都明确。

15.4 生成 PRD

$to-prd

把当前共识整理成 PRD，并创建 GitHub issue。

15.5 拆任务

$to-issues

把 PRD 拆成 3-5 个 vertical slice issues，每个 issue 都要能独立实现和测试。

15.6 实现其中一个 issue

$tdd

实现 issue #123。严格 red-green-refactor，一次只写一个失败测试和一个最小实现。每轮运行相关测试。

15.7 检查改动

在 Codex 里可以用：

/diff

也可以让 Codex 总结：

请总结本次改动，包括：
1. 修改了哪些文件
2. 完成了哪些需求
3. 运行了哪些测试
4. 还有哪些风险

16. 最小命令速查

安装 Codex

npm install -g @openai/codex

安装 Matt Pocock skills

npx skills@latest add mattpocock/skills

启动 Codex

codex

查看 skills

/skills

初始化当前仓库

$setup-matt-pocock-skills

需求盘问

$grill-with-docs

TDD 实现

$tdd

Bug 诊断

$diagnose

架构理解

$zoom-out

生成 PRD

$to-prd

拆 issue

$to-issues

17. 推荐最终目录结构

一个比较理想的项目结构如下：

my-app/
  AGENTS.md
  CONTEXT.md
  docs/
    agents/
      issue-tracker.md
      triage-labels.md
      domain.md
    adr/
      0001-use-single-context-domain-docs.md
  .agents/
    skills/
      setup-matt-pocock-skills/
        SKILL.md
      grill-with-docs/
        SKILL.md
      tdd/
        SKILL.md
      diagnose/
        SKILL.md
      zoom-out/
        SKILL.md
      to-prd/
        SKILL.md
      to-issues/
        SKILL.md

18. 总结

把 mattpocock/skills 接到 Codex 后，你的工作流会从：

直接叫 AI 写代码

变成：

盘问需求 -> 记录上下文 -> 写 PRD -> 拆 issue -> TDD 小步实现 -> 诊断和重构

最推荐的入门路径是：

1. 安装 Codex
2. 运行 npx skills@latest add mattpocock/skills
3. 在 Codex 中输入 /skills
4. 运行 setup-matt-pocock-skills
5. 确认 AGENTS.md、docs/agents/*.md 已生成
6. 新需求先用 grill-with-docs
7. 实现时用 tdd
8. 修 bug 用 diagnose

这套方式最大的价值不是“多几个提示词”，而是让 Codex 更像一个有流程约束的工程伙伴：先问清楚，再小步做，再验证结果。

参考链接

Matt Pocock skills 仓库：https://github.com/mattpocock/skills
Codex Agent Skills 文档：https://developers.openai.com/codex/skills
Codex Quickstart：https://developers.openai.com/codex/quickstart
Codex AGENTS.md 文档：https://developers.openai.com/codex/guides/agents-md
Codex CLI slash commands：https://developers.openai.com/codex/cli/slash-commands
Codex Rules：https://developers.openai.com/codex/rules

1. 先理解：mattpocock/skills 是什么

2. 准备环境

2.1 安装 Codex CLI

2.2 安装 Node.js / npm

2.3 建议准备 Git 和 GitHub CLI

3. 推荐安装方式：用 npx skills@latest

4. Codex Skills 应该安装到哪里

5. 如果安装器没有正确识别 Codex：手动安装

5.1 macOS / Linux：复制到用户级 skills

5.2 macOS / Linux：复制到当前仓库，供团队共享

5.3 Windows PowerShell：复制到用户级 skills

6. 在 Codex 中确认 skills 已加载

7. 第一次必须做：运行 setup-matt-pocock-skills

8. 重要：Codex 更应该用 AGENTS.md

9. 推荐的 AGENTS.md 模板

10. 常用工作流

10.1 新功能：先盘问，再写 PRD，再拆 Issue

10.2 实现功能：用 TDD

10.3 修 bug：用 diagnose

10.4 看不懂代码：用 zoom-out

10.5 架构整理：用 improve-codebase-architecture

10.6 接力开发：用 handoff

10.7 快速原型：用 prototype

11. 更新 skills

12. 禁用某个 skill

13. 常见问题排查

13.1 /skills 里看不到 Matt 的 skills

13.2 $setup-matt-pocock-skills 没触发

13.3 setup 写到了 CLAUDE.md，Codex 没读到

13.4 GitHub issue 创建失败

13.5 Codex 乱跑命令或权限太大

14. 推荐实践

14.1 先少装，再扩展

14.2 每个仓库先跑一次 setup

14.3 Codex 项目优先维护 AGENTS.md

14.4 复杂需求先 grill-with-docs

14.5 实现时用 $tdd

14.6 遇到 bug 用 $diagnose

14.7 团队共享时，把这些文件一起提交

14.8 定期 review skills

15. 一个完整的日常使用示例

15.1 进入项目

15.2 查看 skills

15.3 新功能需求盘问

15.4 生成 PRD

15.5 拆任务

15.6 实现其中一个 issue

15.7 检查改动

16. 最小命令速查

安装 Codex

安装 Matt Pocock skills

启动 Codex

查看 skills

初始化当前仓库

需求盘问

TDD 实现

Bug 诊断

架构理解

生成 PRD

拆 issue

17. 推荐最终目录结构

18. 总结

参考链接

1. 先理解：`mattpocock/skills` 是什么

3. 推荐安装方式：用 `npx skills@latest`

7. 第一次必须做：运行 `setup-matt-pocock-skills`

8. 重要：Codex 更应该用 `AGENTS.md`

9. 推荐的 `AGENTS.md` 模板

10.3 修 bug：用 `diagnose`

10.4 看不懂代码：用 `zoom-out`

10.5 架构整理：用 `improve-codebase-architecture`

10.6 接力开发：用 `handoff`

10.7 快速原型：用 `prototype`

13.1 `/skills` 里看不到 Matt 的 skills

13.2 `$setup-matt-pocock-skills` 没触发

13.3 setup 写到了 `CLAUDE.md`，Codex 没读到

14.3 Codex 项目优先维护 `AGENTS.md`

14.4 复杂需求先 `grill-with-docs`

14.5 实现时用 `$tdd`

14.6 遇到 bug 用 `$diagnose`