mattpocock/skills—面向真实工程的AI编程工作流

发表于2026-07-26|更新于2026-07-26|开发工具

|总字数:11.9k|阅读时长:40分钟|浏览量:

mattpocock/skills 是 Matt Pocock 公开的 Agent Skills 集合。它把需求澄清、领域建模、资料研究、原型验证、规格编写、任务拆分、测试驱动开发、缺陷诊断和代码审查等工程方法封装为可复用的 Skill。

这个仓库不是一个“安装后自动完成整个项目”的框架。每个 Skill 只负责一个明确阶段，使用者需要根据任务类型选择入口，并理解它会读取什么、修改什么以及何时停止。

本文面向第一次接触该项目的读者，逐项介绍仓库当前的 41 个 Skill。每个稳定 Skill 都会说明：

解决什么问题；
适合和不适合什么场景；
如何调用；
会生成什么结果；
在同一个具体项目中如何使用；
是否会修改文件、Issue 或 Git 状态。

本文核对的是仓库 main 分支截至 2026 年 7 月 26 日的内容。项目仍在快速演进，实际行为应以安装后的 SKILL.md 为准。

0. 贯穿全文的具体场景

本文使用一个虚构但完整的 TypeScript 项目：

项目：task-board
形态：Web 任务协作平台
代码：TypeScript Monorepo
存储：PostgreSQL
协作：GitHub Issues + Pull Request

团队准备增加“周期任务”功能：

用户可以创建一个周期规则，例如“每周一 09:00 生成周报任务”。
系统按工作区时区生成任务。
规则可以暂停、恢复和结束。
夏令时切换不能导致任务重复或漏建。
同一周期实例必须具有稳定标识，重试时不能生成两条任务。

这个功能足够复杂，可以展示大多数工程 Skill：

研究 RRULE 和时区规则
  ↓
澄清周期规则、周期实例和实际任务的关系
  ↓
验证状态模型与界面
  ↓
编写规格并拆分任务
  ↓
按 TDD 实现
  ↓
审查、诊断缺陷和维护架构

少数 Skill 是为课程仓库、Obsidian 或写作设计的，无法自然放入周期任务主流程。本文仍会给出具体例子，并明确说明它们为什么不适合直接用于 task-board。

1. 先理解 Skill 如何被调用

1.1 一个 Skill 的基本结构

每个 Skill 至少包含：

1 2	<skill-name>/ └── SKILL.md

SKILL.md 的 Front Matter 通常包含：

---
name: tdd
description: Test-driven development...
---

正文则定义代理应该遵循的流程、完成标准和支持文件。

1.2 User-invoked 与 Model-invoked

本仓库把 Skill 分成两类。

类型	特征	调用方式
User-invoked	Front Matter 含 `disable-model-invocation: true`	用户主动选择
Model-invoked	允许模型按描述自动匹配	用户可明确指定，模型也可自动使用

仓库 README 使用斜杠表示手动调用：

1 2	/to-spec /implement

不同编码代理的界面不完全相同：

Claude Code 通常可以使用 /skill-name；
Codex 等 Agent Skills 宿主可以在提示中明确写“使用 tdd Skill”，或使用界面提供的 Skill 快捷方式；
Model-invoked Skill 不一定需要斜杠命令，描述与当前任务匹配时可以自动触发。

如果命令没有出现，应先检查 Skill 是否安装到当前代理和当前作用域，而不是直接假定 Skill 有问题。

1.3 Skill 不是权限系统

Skill 是过程指令，不是沙箱。它可能要求代理：

修改项目文件；
安装依赖；
创建 Git 提交；
创建或关闭 Issue；
修改标签；
启动子代理；
打开浏览器；
写入 .env 或 GitHub Secrets。

是否允许这些行为，仍由用户授权、代理权限、Hook、操作系统和远程平台控制。

2. 安装与首次配置

2.1 先查看仓库提供的 Skill

1	npx skills@latest add mattpocock/skills --list

该命令会下载并执行 skills npm 包，然后读取远程仓库。执行前应核对包名和来源。团队自动化中应固定经过审查的具体版本，不要长期依赖 @latest。

2.2 交互式安装

1	npx skills@latest add mattpocock/skills

安装器会让用户选择：

Skill；
目标代理；
项目级或全局作用域；
符号链接或复制方式。

当前 CLI 文档中的常见目录为：

代理	项目级	全局
Claude Code	`.claude/skills/`	`~/.claude/skills/`
Codex	`.agents/skills/`	`~/.codex/skills/`

第一次不要选择 --all。仓库包含 personal、in-progress 和 deprecated，其中部分内容带有作者本机路径、实验性命令或已被替代的流程。

2.3 推荐的第一批 Skill

首次体验主流程可以安装：

setup-matt-pocock-skills
ask-matt
grill-with-docs
grilling
domain-modeling
research
prototype
to-spec
to-tickets
implement
tdd
code-review
codebase-design
diagnosing-bugs
handoff

按需要再增加：

triage
wayfinder
improve-codebase-architecture
resolving-merge-conflicts

2.4 Claude Code 插件安装

仓库还提供 Claude Code 插件：

1 2	/plugin marketplace add mattpocock/skills /plugin install mattpocock-skills@mattpocock

Shell 中也可以执行：

1 2	claude plugin marketplace add mattpocock/skills claude plugin install mattpocock-skills@mattpocock

两种方式的区别：

方式	特点	适用情况
skills.sh	Skill 进入项目，可以修改	需要团队定制
Claude Code 插件	作为只读包跟随上游	直接使用作者版本

截至本文核对日期，Codex 原生插件仍在仓库路线图中；Codex 当前可以使用 skills.sh 安装 Agent Skills 标准版本。

3. 工程 Skill：项目配置与流程选择

仓库的 engineering/ 目录包含 17 个稳定工程 Skill。本节逐项介绍。

3.1 setup-matt-pocock-skills：为仓库建立前置配置

解决什么问题

to-spec、to-tickets、triage、wayfinder 和 code-review 需要知道：

Issue 存在哪里；
哪些标签表示不同分诊状态；
CONTEXT.md 和 ADR 放在哪里；
应该读取 AGENTS.md 还是 CLAUDE.md。

setup-matt-pocock-skills 用于在每个仓库首次配置这些信息。

什么时候使用

适合：

第一次把这套 Skill 引入一个仓库；
从 GitHub Issues 切换到本地 Markdown；
调整 Triage 标签映射；
单体仓库升级为多上下文 Monorepo。

不适合：

每次新会话都重新运行；
只使用 tdd 等不依赖 Tracker 的单个 Skill；
在尚未确认团队工作流时直接批量写配置。

如何调用

1	/setup-matt-pocock-skills

它会先检查远程仓库、AGENTS.md、CLAUDE.md、CONTEXT.md、ADR 目录、.scratch/ 和 Monorepo 信号，再逐项确认配置。

task-board 示例

task-board 位于 GitHub，团队选择：

1
2
3

Issue Tracker：GitHub Issues
Triage 标签：默认五种状态
领域文档：单上下文

Skill 将创建：

1
2
3

docs/agents/issue-tracker.md
docs/agents/domain.md
docs/agents/triage-labels.md

并在现有 AGENTS.md 或 CLAUDE.md 中加入 ## Agent skills。

结果与副作用

它会修改仓库文件，但不会自动代表团队批准这些约定。完成后必须检查：

1 2	git status --short git diff

如果仓库既没有 AGENTS.md 也没有 CLAUDE.md，Skill 会询问创建哪一个，不会自行选择。

3.2 ask-matt：不知道选哪个 Skill 时使用

解决什么问题

仓库有多个入口。ask-matt 是路由器，用于根据任务规模和状态推荐流程。

什么时候使用

适合：

第一次使用，记不住 Skill 名称；
不确定应该先研究、澄清、原型还是实现；
任务似乎同时符合多个流程。

不适合：

已经明确知道需要运行 tdd；
期望它直接实现功能；
用它代替项目首次配置。

如何调用

/ask-matt

我准备给 task-board 增加周期任务。
时区和夏令时行为还没有定，预计需要修改数据库、后端和前端。

task-board 示例

根据描述，ask-matt 应推荐：

research
  ↓
grill-with-docs
  ↓
必要时 prototype
  ↓
to-spec
  ↓
to-tickets
  ↓
逐票 implement

如果只是修复已经稳定复现的重复生成缺陷，它会建议从 diagnosing-bugs 或 tdd 开始。

结果与副作用

ask-matt 只推荐路径，不直接修改代码。它依赖其他 Skill 已经安装；如果推荐了未安装的 Skill，需要补充安装。

4. 工程 Skill：需求、知识与设计

4.1 grill-with-docs：在代码库中澄清需求

解决什么问题

需求描述通常遗漏边界。grill-with-docs 通过连续访谈澄清设计，并使用 domain-modeling 同步领域术语和 ADR。

什么时候使用

适合：

已经有代码库；
产品行为存在多个未决分支；
讨论中出现含义不清的领域词；
希望决策进入长期项目文档。

不适合：

没有代码库的普通计划，应使用 grill-me；
需求已经完整，只需整理为规格，应使用 to-spec；
只需查询一个客观事实，应使用 research 或直接读取环境。

如何调用

/grill-with-docs

我们要支持周期任务。请重点澄清时区、暂停与恢复、
错过执行、修改规则和幂等生成的语义。

Skill 会使用 grilling 的“一次一个问题”方式，并在决策形成时调用 domain-modeling。

task-board 示例

它可能依次询问：

1. 周期时间属于用户时区还是工作区时区？
2. 夏令时跳过 02:30 时，应跳过还是顺延？
3. 暂停后错过的周期实例，恢复时是否补建？
4. 修改规则后，已生成但未完成的任务是否改变？
5. 删除规则是软删除还是立即终止未来实例？

用户每回答一项，Skill 才进入依赖它的下一项。

结果与副作用

它可能更新：

1 2	CONTEXT.md docs/adr/*.md

它不会直接实现功能。访谈完成后通常进入 to-spec。

4.2 domain-modeling：建立项目共同语言

解决什么问题

domain-modeling 处理术语冲突、同义词、边界场景和难以逆转的领域决策。

什么时候使用

适合：

“任务”“周期”“执行”等词在讨论中含义不一致；
代码与产品描述的模型冲突；
需要建立或更新 CONTEXT.md；
一项重要取舍值得写 ADR。

不适合：

只是读取已有 CONTEXT.md；
写具体实现计划；
把类名、文件名等实现细节塞入领域词汇表。

如何调用

这是 Model-invoked Skill，可以明确要求：

1	使用 domain-modeling Skill 澄清 RecurringRule、Occurrence 和 Task 的关系。

它也会被 grill-with-docs、triage 和架构流程调用。

task-board 示例

讨论后形成：

Recurring Rule：
描述未来周期实例如何产生的规则。

Occurrence：
规则在某个计划时间上的一次逻辑实例。

Generated Task：
由一个 Occurrence 实际生成的任务。

关系：

1 2	Recurring Rule 1 ── N Occurrence Occurrence 1 ── 0..1 Generated Task

这能避免把“下一次任务”同时用于计划实例和数据库任务。

结果与副作用

术语写入 CONTEXT.md，不包含实现细节。只有满足以下条件才建议 ADR：

难以逆转；
缺少背景时会显得意外；
确实经过多方案权衡。

4.3 research：让后台代理查一手资料

解决什么问题

research 把外部资料调查交给后台代理，并要求使用官方文档、规范、源码或一方 API。

什么时候使用

适合：

实现依赖标准或第三方 API；
需要在继续讨论的同时让代理后台调查；
希望把结论保存为带引用的 Markdown。

不适合：

事实可以直接从当前仓库找到；
只是想得到无来源的快速总结；
调查结果不需要写入仓库。

如何调用

1 2	使用 research Skill 调查 RFC 5545 中 RRULE、时区标识和夏令时相关要求，并保存带引用的研究笔记。

task-board 示例

后台代理查阅：

RFC 5545
IANA Time Zone Database
项目所用日期库的官方文档
PostgreSQL 时间类型文档

产出：

1	docs/research/recurring-rules-and-timezones.md

后续 grill-with-docs 可以引用该文件讨论产品选择。

结果与副作用

Skill 会启动后台代理并在仓库写 Markdown。它只提供事实，不替用户决定“DST 不存在时间应该跳过还是顺延”。

4.4 prototype：用一次性代码回答设计问题

解决什么问题

有些问题靠文字无法可靠决定。prototype 构建一次性原型，分为两条路径：

问题	原型
状态或业务逻辑是否合理	交互式终端程序
界面应该长什么样	同一路由上的多个 UI 变体

什么时候使用

适合：

状态机存在难以想象的边界；
多个 UI 方案需要实际比较；
原型的目标是回答一个明确问题。

不适合：

已经确定要写生产实现；
只是为了“先写点代码看看”；
需要长期维护、完整测试和错误处理。

如何调用

逻辑原型：

1	使用 prototype Skill 验证周期规则在暂停、恢复和夏令时切换时的状态变化。

UI 原型：

1	使用 prototype Skill 为周期规则编辑器生成三种明显不同的交互方案。

task-board 示例

逻辑原型可以提供命令：

create weekly 09:00 Asia/Shanghai
advance 7d
pause
advance 14d
resume
show-state

每个动作后打印完整状态，帮助用户决定恢复时是否补建错过的 Occurrence。

UI 原型可以使用：

1
2
3

/prototype/recurring-rule?variant=a
/prototype/recurring-rule?variant=b
/prototype/recurring-rule?variant=c

结果与副作用

原型要求：

明确标注为 throwaway；
一个命令即可运行；
默认不持久化；
不追求测试和完整错误处理；
验证后把结论写入 Issue；
原型代码保存在临时分支，不进入主分支。

不要把“原型运行正常”误认为生产实现已经完成。

4.5 codebase-design：设计深模块与测试 seam

解决什么问题

codebase-design 提供一套设计词汇：

Module
Interface
Implementation
Depth
Seam
Adapter
Leverage
Locality

目标是把大量行为隐藏在较小 Interface 后，形成可测试的深模块。

什么时候使用

适合：

设计一个新模块的 Interface；
判断测试应该放在哪个 seam；
模块只是薄转发层；
修改一个行为需要散落到许多调用者；
其他 Skill 需要统一架构语言。

不适合：

只做代码风格整理；
在只有一个实现且没有真实变化点时提前添加 Adapter；
为了“架构感”增加不必要抽象。

如何调用

1 2	使用 codebase-design Skill 设计周期计算模块。调用方只提供规则和计算窗口，不应了解 RRULE 解析与 DST 细节。

task-board 示例

浅模块可能要求调用方依次执行：

parseRule()
loadTimezone()
expandDates()
filterExceptions()
normalizeDst()
deduplicate()

更深的 Interface 可以是：

interface RecurrenceEngine {
  occurrencesBetween(
    rule: RecurringRule,
    window: TimeWindow,
  ): Occurrence[];
}

RRULE、时区、例外日期和去重逻辑都留在实现内部。调用方和测试通过同一 Interface 使用模块。

结果与副作用

这个 Skill 是设计参考，不会自动完成重构。它强调：

Interface 是完整使用契约，不只是 TypeScript interface；
一个 Adapter 往往只是假想 seam，两个真实实现才证明变化点存在；
测试应通过 Interface，而不是越过 Interface 访问内部。

5. 工程 Skill：规格、任务、实现与审查

5.1 to-spec：把已经讨论清楚的内容写成规格

解决什么问题

to-spec 将当前对话和代码库理解整理为可实施规格，并发布到配置好的 Issue Tracker。

什么时候使用

适合：

grill-with-docs 已经完成；
关键决策已经明确；
需要把对话转成长期、可引用的任务来源。

不适合：

仍有大量未决问题；
希望它重新采访用户；
只需要一张很小的修复任务。

如何调用

/to-spec

它会先确认测试 seam，再生成：

Problem Statement
Solution
User Stories
Implementation Decisions
Testing Decisions
Out of Scope
Further Notes

task-board 示例

规格会包含：

用户可以创建、暂停、恢复和结束周期规则。
每个 Occurrence 至多产生一个 Generated Task。
时区属于工作区。
DST 不存在时间按团队确认的规则处理。
首个版本不支持任意自然语言周期表达式。

测试决策可以规定：

1
2
3

通过 RecurrenceEngine Interface 测试周期展开；
通过 HTTP 接口测试创建和修改规则；
通过任务生成作业测试并发幂等。

结果与副作用

当前 Skill 会：

将规格发布到 Issue Tracker；
应用 ready-for-agent 标签；
避免在长期规格中写容易过时的文件路径。

如果只想生成本地草稿，应提前修改项目副本或明确覆盖发布行为。

5.2 to-tickets：把规格拆成垂直切片

解决什么问题

大型规格无法在一个上下文中完成。to-tickets 将其拆成 tracer-bullet 垂直切片，并声明阻塞关系。

什么时候使用

适合：

实现需要多个独立会话；
数据库、后端和前端可以组成多个可验证增量；
希望多个代理处理无阻塞任务。

不适合：

一个会话即可完成的小任务；
按技术层拆出无法独立验证的“数据库任务”“前端任务”；
尚未形成稳定规格。

如何调用

1	/to-tickets <spec-issue-url>

Skill 会先展示拟议任务、每项交付和阻塞关系，等用户确认后再发布。

task-board 示例

合理拆分：

01 创建最小周期规则并预览下一次 Occurrence
   Blocked by: None

02 由到期 Occurrence 幂等生成任务
   Blocked by: 01

03 暂停与恢复周期规则
   Blocked by: 01

04 处理夏令时跳转
   Blocked by: 01

05 提供周期规则编辑界面
   Blocked by: 01, 03

错误拆分：

01 建表
02 写后端
03 写前端
04 补测试

后者的单个任务无法独立证明用户行为。

结果与副作用

本地 Tracker 会写入：

1	.scratch/<feature>/issues/01-*.md

远程 Tracker 会创建多个 Issue，并建立原生或文本阻塞关系。它不会自动关闭父 Issue。

对于无法分批保持检查通过的全局变更，Skill 使用 expand–migrate–contract，而不是强行垂直拆分。

5.3 implement：按规格或任务完成一张票

解决什么问题

implement 是单张规格或 Ticket 的实施入口。它编排 TDD、检查和 Review。

什么时候使用

适合：

Ticket 已经自包含；
验收条件和测试 seam 已明确；
当前分支只承载这一项工作。

不适合：

需求仍在变化；
工作区有其他人的未提交修改；
用户尚未授权创建提交；
多张 Ticket 被混在一个上下文中。

如何调用

1	/implement <ticket-url>

或：

1	使用 implement Skill 实现 .scratch/recurring-tasks/issues/02-idempotent-generation.md

task-board 示例

执行 Ticket 02 时，它应：

读取 Ticket 和规格；
调查现有任务生成流程；
与用户确认幂等测试 seam；
使用 tdd 完成一个红—绿切片；
经常运行单个测试和类型检查；
结束时运行完整测试；
使用 code-review 审查；
提交当前分支。

结果与副作用

当前 implement/SKILL.md 明确要求：

1	Commit your work to the current branch.

因此调用前必须检查：

1 2	git status --short git branch --show-current

如果团队要求人工审查后才提交，应修改项目级 Skill，删除自动提交，不能只依赖口头习惯。

5.4 tdd：一个行为切片一个红—绿循环

解决什么问题

tdd 让代理先写能失败的行为测试，再写最小实现。

什么时候使用

适合：

新功能具有清晰的可观察行为；
缺陷可以转成回归测试；
希望通过公共 Interface 保护重构。

不适合：

还不知道要实现什么；
为私有函数逐一补测试；
一次先写完全部测试，再一次写完实现；
用快照或 Mock 复制实现细节。

如何调用

1 2	使用 tdd Skill 实现“同一个 Occurrence 重试两次只生成一个任务”。测试 seam 使用任务生成作业的公开入口。

task-board 示例

一次切片：

Red：
并发处理同一个 Occurrence，两次调用产生两个任务。

Green：
增加最小唯一约束和冲突处理，使测试通过。

下一切片：
相同 Occurrence 但不同规则版本时返回明确冲突。

结果与副作用

写测试前必须与用户确认 seam。测试应验证公共行为，不应：

直接测试私有方法；
查询内部表来绕过公开 Interface；
重算与实现相同的算法作为期望值；
为未来可能需求提前写代码。

当前 Skill 还规定重构不属于红—绿循环，而放在 Review 阶段处理。

5.5 code-review：分别检查规范与规格

解决什么问题

同一份代码可能“写得规范但需求做错”，也可能“需求做对但破坏项目约定”。code-review 将两类审查分开。

什么时候使用

适合：

实现完成后审查当前分支；
审查 Pull Request；
检查一段固定提交范围；
需要对照原始 Issue 或 PRD。

不适合：

没有明确比较点；
Diff 为空；
只想运行格式化或 Lint；
编码代理不支持并行子代理且没有降级方案。

如何调用

1	/code-review main

也可以使用提交或标签：

1	/code-review HEAD~3

task-board 示例

Skill 固定：

1 2	git diff main...HEAD git log main..HEAD --oneline

然后并行执行：

Standards 审查：
检查 AGENTS.md、CONTRIBUTING.md 和 Fowler 代码异味基线。

Spec 审查：
对照周期任务规格检查遗漏、错误实现和范围蔓延。

结果与副作用

最终保留两个独立部分：

1 2	## Standards ## Spec

不会把两类问题合并排序。它主要是只读流程，但会启动并行子代理，并需要读取 Tracker 中的规格。

6. 工程 Skill：缺陷、分诊、架构与大型工作

6.1 diagnosing-bugs：先建立反馈回路，再推断根因

解决什么问题

diagnosing-bugs 用于难复现、间歇性或性能缺陷。它的核心完成条件是先得到一个已经运行过、能准确捕获用户症状的命令。

什么时候使用

适合：

Bug 不能一眼定位；
问题具有并发、时间或环境相关性；
性能回归需要测量；
需要最小化复现和验证假设。

不适合：

明确的拼写错误；
已经有失败测试且修复非常直接，可以使用 tdd；
尚未获得复现环境却准备凭代码猜测。

如何调用

1 2	使用 diagnosing-bugs Skill 调查 DST 切换后周期任务重复生成。先建立可重复执行的反馈回路，不要先改代码。

task-board 示例

阶段一先产生：

1	npm test -- recurring-task-dst-repro

这个测试需要：

固定时区；
固定系统时间；
驱动真实任务生成路径；
明确断言只生成一条任务；
多次运行保持相同结果。

之后才进行：

最小化输入
  ↓
列出 3～5 个可证伪假设
  ↓
逐项插桩
  ↓
写回归测试
  ↓
修复并重新运行原始复现

结果与副作用

无法建立反馈回路时，Skill 要求停止并请求：

环境访问；
HAR、日志、Core Dump；
带时间戳的录屏；
临时生产插桩授权。

修复后还会清理所有带唯一前缀的调试日志，并记录真正根因。

6.2 triage：把外部 Issue 变成可执行任务

解决什么问题

triage 处理由用户、客户或外部贡献者提交的原始 Issue 和 PR，使其进入明确状态。

什么时候使用

适合：

外部 Bug 报告缺少信息；
Feature Request 需要确认价值和范围；
外部 PR 需要验证声明；
维护者需要查看哪些条目需要关注。

不适合：

to-tickets 已经生成的 Ticket；
团队内部正在开发的普通分支；
未经授权批量关闭 Issue。

如何调用

1	/triage 显示所有需要我处理的条目

或：

1	/triage #128

task-board 示例

用户报告：

1	“夏令时开始那周，我的周期任务出现了两条。”

Skill 会：

读取 Issue、评论、标签和作者；
检查代码中是否已经实现相关行为；
搜索 .out-of-scope/ 中是否有既往拒绝；
复现报告；
推荐 bug + needs-info 或 bug + ready-for-agent；
必要时生成 Agent Brief。

结果与副作用

五种状态为：

needs-triage
needs-info
ready-for-agent
ready-for-human
wontfix

它会评论、改标签，某些结论还会关闭 Issue。当前 Skill 要求 AI 生成的分诊评论带免责声明。执行远程修改前应确认推荐结果。

6.3 improve-codebase-architecture：扫描值得深化的模块

解决什么问题

improve-codebase-architecture 查找浅模块、缺乏稳定 seam、修改分散和难以测试的热点，生成可视化 HTML 报告。

什么时候使用

适合：

同一区域频繁修改；
一个行为需要改很多文件；
Bug 无法在正确 seam 写回归测试；
团队安排架构维护时间。

不适合：

当前只需紧急修复生产问题；
全仓库没有明确热点却要求列出大量理论重构；
用户已经选定具体 Interface，只需实现。

如何调用

1
2
3

/improve-codebase-architecture

重点检查周期任务生成与调度区域。

task-board 示例

Skill 先读取提交历史、CONTEXT.md 和相关 ADR，再让 Explore 子代理调查，最后在系统临时目录生成：

1	architecture-review-<timestamp>.html

报告候选可能包括：

Strong：
把分散在 Job、Repository 和 Controller 中的周期计算
收敛到 RecurrenceEngine Interface 后。

Worth exploring：
将任务生成幂等规则集中到 OccurrenceMaterializer。

用户选择一项后，Skill 再通过 grilling 和 domain-modeling 深入讨论。

结果与副作用

HTML 使用 Tailwind 和 Mermaid CDN，需要浏览器和网络才能完整查看。报告写入临时目录，不进入仓库；后续讨论可能更新 CONTEXT.md 或 ADR。

6.4 wayfinder：为超大型工作绘制决策地图

解决什么问题

wayfinder 处理大到无法在一个会话规划、连“要做哪些决定”都尚未完全看清的工作。

什么时候使用

适合：

绿地系统；
跨多个服务和团队的迁移；
长期功能平台化；
需要多次研究、原型和人工决策。

不适合：

已经有清晰规格；
一个会话能规划完的功能；
只是任务很多，但决策并不模糊。

如何调用

创建地图：

/wayfinder

我们要把周期任务扩展为跨项目自动化平台，
但权限、触发器、执行隔离和计费都还没有定。

继续地图：

1	/wayfinder <map-issue-url>

task-board 示例

地图的 Destination：

1	形成一份可以进入 to-spec 的自动化平台设计。

决策 Ticket：

Research：第三方 Webhook 重试语义
Prototype：规则编排器 UI
Grilling：工作区与项目权限边界
Task：获取真实客户自动化样本

每个会话只解决一项决策。开放、无阻塞、未认领的 Ticket 构成 frontier。

结果与副作用

它会在 Tracker 创建：

一张 wayfinder:map；
多张子 Issue；
标签、依赖和认领关系。

地图产出的是决策，不是功能代码。路线清晰后应进入：

1	to-spec → to-tickets → implement

6.5 resolving-merge-conflicts：按双方原始意图解决冲突

解决什么问题

resolving-merge-conflicts 用于已经处于 merge 或 rebase 冲突状态的仓库。

什么时候使用

适合：

git merge 已暂停；
git rebase 已暂停；
需要根据双方 Issue、PR 和提交意图逐个解决冲突。

不适合：

尚未开始 merge；
只是两个文件内容不同；
用户希望评估是否应该放弃本次 merge。

如何调用

1 2	使用 resolving-merge-conflicts Skill 解决当前 rebase。先查明双方修改的原始 Issue 和提交意图。

task-board 示例

当前分支修改了 RecurrenceEngine，而 main 同时重构了时区 Adapter。Skill 会：

检查当前 rebase 状态；
读取双方提交和原始 Issue；
逐 Hunk 保留两侧意图；
不借冲突引入新行为；
运行类型检查、测试和格式化；
暂存并继续 rebase。

结果与副作用

这个 Skill 非常强硬：

1	Always resolve; never --abort.

它还会暂存文件、提交或继续 rebase。用户如果希望保留“必要时中止”的选择，应在项目副本中修改这一规则，或不要调用该 Skill。

7. 通用生产力 Skill

productivity/ 目录包含 5 个稳定 Skill。它们不一定只用于编程。

7.1 grill-me：没有代码库时澄清计划

适用场景

grill-me 是 grilling 的手动入口，适合讨论一个尚未进入仓库的计划、产品想法或决策。

如何调用

1
2
3

/grill-me

我想做一个支持个人周期任务的 SaaS，但还没有代码库。

示例与结果

代理会一次询问一个决策，例如目标用户、核心价值、是否需要协作和首个付费场景。它不会写 CONTEXT.md，也不会直接实现。

有现成代码库并希望留下领域文档时，应改用 grill-with-docs。

7.2 grilling：一次一个问题的访谈原语

适用场景

grilling 是 Model-invoked Skill，也是多个流程的基础。它用于压力测试计划和遍历决策树。

如何调用

1	使用 grilling Skill 逐项澄清周期任务的暂停语义。

task-board 示例

正确行为：

问题 1：暂停期间是否继续创建 Occurrence？
推荐：创建逻辑实例但不物化为任务。

等待用户回答后，再问依赖这个答案的问题。

它会自己查找文件系统中的客观事实，只把真正的决策交给用户。达成共同理解前不执行实现。

7.3 handoff：把长会话交给新会话

适用场景

handoff 用于上下文接近上限、需要分叉调查或准备开启独立实现会话。

如何调用

1	/handoff 下一会话将实现 DST 边界测试

task-board 示例

交接文档引用：

规格 Issue
CONTEXT.md
相关 ADR
当前分支和提交
未解决问题
建议使用的 Skill

然后用户开启新会话并引用该文件。

结果与副作用

文档写入操作系统临时目录，而不是仓库。Skill 要求删除 API Key、密码和个人信息，并避免复制已有规格或 Diff。

7.4 teach：建立可持续的学习工作区

适用场景

teach 用于跨多个会话学习一个主题，不是一次性解释。

如何调用

1	/teach 我想系统学习周期调度、时区和夏令时处理

task-board 示例

可以新建一个独立学习目录，生成：

MISSION.md
RESOURCES.md
NOTES.md
reference/*.html
learning-records/*.md
lessons/*.html
assets/*

第一课可能只训练“区分 UTC Instant、Local Date Time 与 Time Zone”，后续通过检索练习、间隔复习和交错练习增强长期记忆。

结果与副作用

这是重型、状态化 Skill，会在当前目录创建一整套教学资产。不要在生产源码根目录随意运行，除非团队确实希望把学习材料纳入项目。

7.5 writing-great-skills：编写和改进 Skill 的参考

适用场景

用于创建或审查自己的 SKILL.md，重点提高流程可预测性。

如何调用

/writing-great-skills

请审查我们自定义的 release Skill，
重点检查触发描述、完成标准、重复和上下文负担。

task-board 示例

团队编写 /release-task-board 时，可以用它检查：

是否应该手动触发；
描述是否包含真正不同的触发分支；
每一步是否有可检查完成条件；
参考资料是否应拆到独立文件；
是否存在重复、沉积、空话和过长正文。

结果与副作用

它主要提供 Skill 设计词汇和审查原则，不自动创建文件。需要修改 Skill 时，应明确提供目标文件和授权。

8. 专项 Skill

misc/ 中的 4 个 Skill 解决特定工具问题，不属于通用主流程。

8.1 git-guardrails-claude-code：阻止危险 Git 命令

什么时候使用

适合希望在 Claude Code 中阻止：

git push
git reset --hard
git clean -f
git branch -D
git checkout .
git restore .

如何调用

1 2	使用 git-guardrails-claude-code Skill，为 task-board 项目安装项目级 Git 防护。

task-board 示例

Skill 将复制：

1	.claude/hooks/block-dangerous-git.sh

并合并 .claude/settings.json 的 PreToolUse Hook。验证时向脚本传入模拟的 git push origin main，预期退出码为 2。

限制与副作用

它专门面向 Claude Code Bash Hook，不是通用 Codex Skill。Windows 原生环境需要 Bash 或改写为 PowerShell 等价脚本。修改设置时必须合并现有 Hook，不能覆盖。

8.2 migrate-to-shoehorn：迁移 TypeScript 测试中的类型断言

什么时候使用

适合 TypeScript 测试因大型对象而大量使用：

1 2	value as Request value as unknown as Request

不允许在生产代码使用 Shoehorn。

如何调用

1 2	使用 migrate-to-shoehorn Skill，迁移周期任务测试中的 Request 和 Workspace 类型断言。

task-board 示例

修改前：

1	runJob({ workspaceId: "w1" } as JobContext);

修改后：

1	runJob(fromPartial({ workspaceId: "w1" }));

故意传入错误类型时使用 fromAny()。

结果与副作用

它会安装：

1	npm i @total-typescript/shoehorn

并修改测试和锁文件。完成后必须运行类型检查与测试，不能机械替换生产代码中的 as。

8.3 scaffold-exercises：创建 AI Hero 课程练习结构

什么时候使用

这个 Skill 针对具有以下约定的课程仓库：

exercises/XX-section/
└── XX.YY-exercise/
    ├── problem/
    ├── solution/
    └── explainer/

它不是普通项目目录脚手架。

如何调用

1 2	使用 scaffold-exercises Skill，为课程新增“周期调度与时区”章节。

示例

它可以生成：

05-recurring-scheduling/
├── 05.01-timezone-basics/explainer/readme.md
├── 05.02-dst-boundaries/problem/readme.md
└── 05.02-dst-boundaries/solution/readme.md

然后运行：

1	pnpm ai-hero-cli internal lint

限制与副作用

task-board 本身不符合这一课程结构，因此不应安装。当前 Skill 还要求通过 Lint 后创建 Git 提交。

8.4 setup-pre-commit：安装 Husky 提交前检查

什么时候使用

适合 Node.js 项目需要统一执行：

1
2
3

lint-staged + Prettier
typecheck
test

如何调用

1	使用 setup-pre-commit Skill 为 task-board 配置项目级提交前检查。

task-board 示例

它会检测 package-lock.json，然后安装：

1
2
3

husky
lint-staged
prettier

创建或修改：

.husky/pre-commit
.lintstagedrc
.prettierrc
package.json
package-lock.json

若 package.json 不存在 typecheck 或 test，它会省略对应命令并告知用户。

结果与副作用

当前 Skill 最后会暂存全部相关文件并提交：

1	Add pre-commit hooks (husky + lint-staged + prettier)

它还可能新建 Prettier 配置，导致大量格式差异。运行前应先确认项目已有格式规范与提交授权。

9. 作者个人 Skill

personal/ 中的 Skill 带有作者自己的工作方式或路径。它们不是通用推荐。

9.1 edit-article：按信息依赖重构文章

如何使用

1	使用 edit-article Skill 编辑 docs/recurring-tasks-guide.md。

它先按标题拆分章节，从信息依赖角度检查顺序，向用户确认结构后再逐节改写。

适用场景与限制

适合作者认同以下风格时：

先确认章节；
依赖概念先介绍；
每段最多 240 个字符；
重点压缩与改善流动性。

240 字符是作者个人规则，不是通用技术写作标准。用于本博客前应先修改本地 Skill，否则可能把需要完整论证的段落切得过碎。

9.2 obsidian-vault：管理作者的 Obsidian Vault

如何使用

原 Skill 用于搜索、创建和组织：

1	/mnt/d/Obsidian Vault/AI Research/

并采用：

Title Case 文件名
根目录扁平组织
[[wikilinks]]
* Index.md 索引笔记

task-board 示例

如果先把路径改为自己的 Vault，可以创建：

1
2
3

Recurring Tasks Index.md
RFC 5545 Notes.md
DST Failure Modes.md

并通过 [[RFC 5545 Notes]] 建立关联。

限制

路径硬编码为作者的 WSL 目录。未经修改直接运行通常会失败或操作错误位置，因此不应作为通用 Skill 安装。

10. 开发中的 Skill

in-progress/ 中有 9 个实验性 Skill。它们可以用于研究，但接口和行为可能变化，不建议直接作为团队稳定流程。

10.1 batch-grill-me：按决策前沿批量提问

它与 grilling 的区别是：

grilling：
一次只问一个问题。

batch-grill-me：
一次询问当前所有互不依赖的 frontier 问题。

调用示例：

1
2
3

/batch-grill-me

批量澄清周期任务首个版本。

它适合用户希望减少往返次数，同时仍保持决策依赖顺序的场景。缺点是单轮问题较多，认知负担更高。

10.2 claude-handoff：直接启动新的 Claude 后台代理

它不是把交接文档保存到临时目录，而是执行：

1	claude --bg --name "<descriptive name>" "<handoff summary>"

调用示例：

1	/claude-handoff 下一代理负责 DST 测试

新代理从当前目录立即开始工作，用户通过 claude agents 管理。它依赖特定 Claude CLI 后台代理能力，并会直接启动新进程，因此比稳定版 handoff 副作用更强。

10.3 loop-me：把生活或工作循环写成 Workflow 规格

它使用“Loop”观察重复活动，再把可委派过程写入：

1 2	workflows/*.md NOTES.md

调用示例：

1	/loop-me 每周一整理 task-board 的未分诊 Issue

Skill 会澄清 Trigger、Checkpoint、Brief 和自动化边界，直到实现者不需要再问问题。它产出 Workflow 规格，不实现自动化。

10.4 setup-ts-deep-modules：用 dependency-cruiser 强制深模块

适合 TypeScript 仓库希望规定：

包根文件是公开入口
任何子目录都是私有实现
测试只能通过入口使用包
禁止依赖循环

调用示例：

1
2
3

/setup-ts-deep-modules

把 task-board 的 src/packages 配置为深模块。

它会：

安装 dependency-cruiser；
写 .dependency-cruiser.cjs；
增加 lint:boundaries；
创建 example 包；
故意加入一次非法深层导入，观察检查失败；
恢复后再次观察通过；
写包目录 README；
更新 AGENTS.md 或 CLAUDE.md。

这是大范围工程修改，只适合团队已经接受该模块约定的 TypeScript 仓库。

10.5 to-questionnaire：把未知决策交给领域专家异步回答

适合当前用户无法独立回答、但知道谁掌握信息的情况。

调用示例：

1
2
3

/to-questionnaire

我们需要客户成功团队说明企业客户的周期任务需求。

Skill 只采访：

1 2	问卷发给谁？需要从对方获得哪些事实或决策？

然后写：

1	to-questionnaire-recurring-task-enterprise-needs.md

问题按重要性排序，每题一个概念，并提供回答区域。它不会替领域专家回答。

10.6 wizard：生成引导人工完成配置的 Bash 脚本

适合第三方服务配置、一次性迁移或 A→B 状态转换。

调用示例：

1
2
3

/wizard

为 task-board 编写 Sentry、数据库和 GitHub Actions Secrets 配置向导。

脚本会：

打开正确 URL；
告诉用户点击位置；
读取普通值或隐藏 Secret；
更新 .env；
使用 gh secret 或 gh variable；
在不可逆步骤前确认；
显示进度和剩余时间。

Skill 只静态检查脚本，不会替用户端到端运行，因为脚本会打开浏览器并等待输入。它可能接触凭据，使用前必须审查目标、变量名和写入位置。

10.7 writing-fragments：写作探索阶段收集碎片

适合还没有文章结构，只想扩大素材空间。

调用示例：

1	/writing-fragments docs/raw-recurring-task-article.md

代理通过访谈不断追加：

观点；
场景；
代码；
类比；
引语；
尚未完成的想法；
可以统领全文的 leading word。

文件只有一个 H1，碎片之间使用水平线，不建立目录。它只探索，不组织文章。

10.8 writing-shape：逐段把素材塑造成文章

它读取一份固定素材文件，并另建文章文件。

调用示例：

/writing-shape

输入：docs/raw-recurring-task-article.md
输出：docs/recurring-task-article.md

流程：

完整读取素材；
确认读者已知的前置概念；
给出 2～3 个不同开头；
用户选择；
每次只决定并写入下一个段落或区块；
讨论应该使用 prose、列表、表格、Callout 还是代码块。

它不修改原素材，也不负责发布或 Front Matter。

10.9 writing-beats：按叙事 Beat 选择文章路径

writing-beats 与 writing-shape 都消费固定素材，但单位不同：

1 2	writing-shape：段落或内容块 writing-beats：叙事中的一次推进

调用示例：

1	/writing-beats docs/raw-recurring-task-article.md

代理先确认读者已掌握哪些概念，再提供 2～3 个起始 Beat。用户选择后只写这一 Beat，然后根据已经“落地”的概念提供下一组可达 Beat。

适合强调阅读旅程和叙事转折的文章；普通结构化教程使用 writing-shape 更直接。

11. 已弃用 Skill

deprecated/ 中的 4 个 Skill 仍保留在仓库，但新项目不应安装。理解它们的替代关系比学习旧用法更重要。

11.1 design-an-interface

旧用途：

1 2	启动 3 个以上子代理，生成明显不同的 Interface，然后按简单性、通用性、深度和误用风险比较。

旧调用示例：

1	使用 design-an-interface 为 RecurrenceEngine 生成四种 Interface。

替代方式：

1 2	使用 codebase-design，并读取其 DESIGN-IT-TWICE.md 参考。

不应再把它作为独立稳定 Skill 安装。

11.2 qa

旧用途：

1	让用户口头报告多个问题，代理调查代码并直接创建 GitHub Issue。

旧示例：

1	“周期任务有时重复，编辑后预览也不刷新。”

替代方式：

triage

新流程提供更明确的状态机、验证、Agent Brief 和自定义 Tracker 支持。

11.3 request-refactor-plan

旧用途：

详细采访重构方案；
检查测试；
拆成非常小的提交；
创建 GitHub Issue。

旧示例：

1	把周期调度逻辑从 Controller 重构为独立模块。

替代组合：

improve-codebase-architecture
  ↓
grill-with-docs
  ↓
to-spec
  ↓
to-tickets

新组合能把架构调查、领域决策和实施切片分开。

11.4 ubiquitous-language

旧用途：

1	从对话提取领域词，写 UBIQUITOUS_LANGUAGE.md。

旧示例会整理 RecurringRule、Occurrence 和 Task。

替代方式：

1	domain-modeling

新 Skill 使用 CONTEXT.md，在讨论过程中实时挑战术语，并只在必要时创建 ADR。

12. 将核心 Skill 串成一次完整实践

现在使用 task-board 周期任务走完整主流程。

12.1 第一次配置

1	/setup-matt-pocock-skills

确认 GitHub Tracker、标签和领域文档布局。

12.2 调查标准与第三方行为

1	使用 research Skill 调查 RFC 5545、IANA 时区和项目日期库。

得到带引用的研究笔记。

12.3 澄清需求与术语

1	/grill-with-docs

逐项决定时区、DST、暂停、恢复、修改和删除语义，同时形成：

1 2	CONTEXT.md docs/adr/

12.4 用原型验证高风险问题

1	使用 prototype Skill 验证暂停/恢复状态机。

保留结论，不把原型代码合入主分支。

12.5 形成规格

/to-spec

审查 User Stories、Implementation Decisions、Testing Decisions 和 Out of Scope。

12.6 拆分垂直任务

1	/to-tickets <spec-url>

确认每张票都能在一个新上下文中独立验证。

12.7 每张票在新会话实现

1	/implement <ticket-url>

使用 tdd 完成红—绿循环，并在结束前执行：

1	/code-review main

12.8 外部缺陷进入分诊

1	/triage #128

复现、分类并生成可实施 Brief。

12.9 难处理缺陷进入诊断

1	使用 diagnosing-bugs Skill 调查 DST 重复生成。

先建立反馈回路，再产生假设和修复。

12.10 定期检查架构热点

1	/improve-codebase-architecture

只选择真实影响近期修改和测试的候选项，不进行无目标重构。

13. 按问题选择 Skill

当前问题	应使用
第一次在仓库启用这套流程	`setup-matt-pocock-skills`
不知道应该走哪条路径	`ask-matt`
有代码库，需求仍有歧义	`grill-with-docs`
没有代码库，只想澄清计划	`grill-me`
需要一次一个问题深入访谈	`grilling`
领域术语冲突	`domain-modeling`
需要查官方资料	`research`
逻辑或 UI 必须实际体验后决定	`prototype`
对话已经清楚，需要规格	`to-spec`
工作超过一个上下文	`to-tickets`
实现一张自包含任务	`implement`
需要测试先行	`tdd`
需要对照规范与规格审查	`code-review`
需要设计深模块 Interface	`codebase-design`
Bug 难复现或根因不明	`diagnosing-bugs`
外部 Issue 或 PR 需要分诊	`triage`
代码热点难测试、修改分散	`improve-codebase-architecture`
项目大到连决策路线都不清晰	`wayfinder`
merge/rebase 已经发生冲突	`resolving-merge-conflicts`
长会话需要交给新会话	`handoff`
需要跨会话系统学习	`teach`
需要编写自己的 Skill	`writing-great-skills`

14. 使用前必须检查的副作用

Skill	关键副作用
`setup-matt-pocock-skills`	修改 Agent 指令和 `docs/agents/`
`grill-with-docs` / `domain-modeling`	修改 `CONTEXT.md` 和 ADR
`research`	启动后台代理并写研究文件
`prototype`	创建一次性代码和临时分支
`to-spec`	发布远程规格并打标签
`to-tickets`	创建多张 Issue 与依赖
`implement`	修改代码、运行测试并提交
`code-review`	启动并行子代理
`triage`	评论、改标签或关闭条目
`wayfinder`	创建决策地图和子 Issue
`resolving-merge-conflicts`	暂存文件并完成 merge/rebase
`teach`	在当前目录创建完整教学工作区
`setup-pre-commit`	安装依赖、改配置并提交
`wizard`	生成可写 `.env` 和 GitHub Secrets 的脚本

每次安装或更新第三方 Skill，都应像审查代码一样检查：

是否包含 Shell 命令；
是否会访问网络；
是否修改远程系统；
是否默认提交；
是否读取或写入凭据；
是否依赖当前代理不具备的能力；
是否存在作者个人路径；
是否仍属于 in-progress 或 deprecated。

15. 更新与移除

查看已安装 Skill：

1	npx skills list

更新项目级 Skill：

1	npx skills update -p

更新单个 Skill：

1	npx skills update tdd

交互式移除：

1	npx skills remove

移除指定 Skill：

1	npx skills remove tdd

团队更新应在干净分支执行。更新后对比 SKILL.md，特别检查新增外部写操作、自动提交、子代理和凭据处理行为。

16. 总结

mattpocock/skills 的核心不是让用户记住 41 个命令，而是为不同问题提供明确入口：

需求不清晰    → 访谈与领域建模
事实不确定    → 一手资料研究
纸面难决策    → 一次性原型
工作量较大    → 规格与垂直任务
进入实现      → TDD 与双轴审查
缺陷难定位    → 反馈回路驱动诊断
外部请求积压  → 状态化分诊
规模超出视野  → 决策地图

第一次使用时，推荐只安装稳定主流程所需的 Skill，在一个真实功能中完整走通：

setup
  ↓
research
  ↓
grill-with-docs
  ↓
prototype（需要时）
  ↓
to-spec
  ↓
to-tickets
  ↓
implement + tdd + code-review

理解每个 Skill 的输入、输出和副作用后，再逐步加入 Triage、Wayfinder、架构审查和专项 Skill。对于 personal、in-progress 和 deprecated，应先阅读源码并完成项目化改造，而不是因为它们位于同一仓库就默认安装。

参考资料

[1] mattpocock/skills GitHub 仓库

[2] 项目 README

[3] Engineering Skills

[4] Productivity Skills

[5] Misc Skills

[6] Personal Skills

[7] In-progress Skills

[8] Deprecated Skills

[9] skills.sh CLI

[10] Claude Code 插件文档

[11] 项目 MIT License

文章作者: 秋风、萧瑟

文章链接: https://lx-cel.github.io/2026/07/26/mattpocock-skills—面向真实工程的AI编程工作流/

开发工具 Claude Code AI编程 Agent Skills Codex