Agent Skills 收集

Agent Skills 收集

这页服务一个具体场景：新建仓库时，快速初始化一组 agent coding skills。它放安装命令、每个 skill 在工作流里的位置，以及哪些 Matt skills 只适合作为可选扩展。博客更适合写完整经验和复盘。

这套组合有两个来源：

• project-docs-system：我们自己的项目文档入口，负责 AGENTS.md 和 docs/ 的分层知识系统。
• Matt Pocock skills v1.1：以 grill-with-docs -> to-spec -> to-tickets -> implement -> code-review 为主线，wayfinder 负责路线尚不清晰的大型工作，implement 内部用 tdd 做红绿循环。

主安装组合

npx skills add https://github.com/multicul-silver-wolf/agent-docs-system-skill --skill project-docs-system
npx skills add https://github.com/mattpocock/skills --skill wayfinder
npx skills add https://github.com/mattpocock/skills --skill grilling
npx skills add https://github.com/mattpocock/skills --skill domain-modeling
npx skills add https://github.com/mattpocock/skills --skill grill-with-docs
npx skills add https://github.com/mattpocock/skills --skill codebase-design
npx skills add https://github.com/mattpocock/skills --skill to-spec
npx skills add https://github.com/mattpocock/skills --skill to-tickets
npx skills add https://github.com/mattpocock/skills --skill implement
npx skills add https://github.com/mattpocock/skills --skill tdd
npx skills add https://github.com/mattpocock/skills --skill code-review
npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture

可选 Matt 配置

如果一个仓库准备完整采用 Matt 的 issue tracker workflow，再安装并运行 setup-matt-pocock-skills：

npx skills add https://github.com/mattpocock/skills --skill setup-matt-pocock-skills

它会配置 issue tracker、triage labels、Matt domain docs，并可能写入 docs/agents/* 和 AGENTS.md / CLAUDE.md 的 Agent skills 区块。已经采用 project-docs-system 的仓库要先确认文档入口归属，避免把长期知识拆成两套互相竞争的入口。

主线 Flow

project-docs-system

来源：multicul-silver-wolf/agent-docs-system-skill

用来建立和维护项目文档系统。它强调把知识按项目级、领域级、子领域级分层放好，让 agent 从 AGENTS.md 进入 docs/index.md、docs/DOCS.md 和相关领域文档。

我会在这些场景用它：

• 新仓库需要 agent 可读的文档入口。
• 某个模块出现长期约束，需要沉淀到文档。
• 用户纠正了项目惯例，需要记录给后续 agent 使用。

wayfinder

来源：mattpocock/skills

用来规划一个上下文窗口装不下、而且从现状到目标的路线仍有大量未知的大型工作。它先确定 destination，再把待定问题放进 issue tracker 上的一张共享 map；每个 child issue 都是用来得出决策的 decision ticket，不是直接交付功能的 implementation ticket。Agent 每个 session 只解决一个前沿 decision ticket，逐步把 fog of war 变成明确决策，路线清楚后再交给 to-spec 或后续实现流程。

我会在这些场景用它：

• 绿地项目或大型功能无法在一个 session 内完成规划，且还不能直接写 spec。
• 多个决策互相阻塞，需要让人和并行 agent 都看到当前可推进的 frontier。
• 希望把跨 session 的判断沉淀到共享 issue map，而不是依赖单次对话上下文。

wayfinder 默认只做规划，不直接执行目标工作。它需要 issue tracker 支持 map、child issues、blocking 和 frontier 查询；若要用 GitHub / GitLab 原生 tracker，先运行 setup-matt-pocock-skills 写入对应的 Wayfinding operations，否则会退回 local-markdown tracker。

grill-with-docs

来源：mattpocock/skills

用来把一个方案放到项目已有领域模型里拷问。它依赖 grilling 和 domain-modeling：一边追问术语、边界、场景和决策依据，一边把确定下来的 glossary 或 ADR 写回文档。

我会在这些场景用它：

• 新功能概念还没讲清楚。
• 业务词和代码里的词可能冲突。
• 需要补 CONTEXT.md、glossary 或 ADR。

to-spec

来源：mattpocock/skills

用来把当前对话和代码库上下文整理成 spec。它适合放在讨论已经收敛之后，把问题、方案、用户故事、实现决策、测试决策和排除范围沉淀下来，并先和用户确认测试 seam。

我会在这些场景用它：

• 需求已经讲清楚，但还缺一份能交给 agent 执行的 spec。
• 需要在拆 ticket 之前先统一问题、方案和范围。
• 想在发布 spec 前确认测试边界。

to-tickets

来源：mattpocock/skills

用来把 plan、spec 或当前对话拆成 ticket。重点是按 tracer bullet 垂直切片拆，并明确每个 ticket 的阻塞关系；遇到无法保持单个切片独立通过的宽重构时，改用 expand-contract 顺序。

我会在这些场景用它：

• 一个需求太大，需要拆成可独立领取的任务。
• 想把每个 ticket 都做成可验证、可 demo 的小闭环。
• 需要先厘清任务依赖，再把当前可执行的 frontier 交给 agent。

implement

来源：mattpocock/skills

用来执行 spec 或 ticket。新版 Matt flow 里，真正进入编码时应该由 implement 串起来：在预先确认的 seam 上调用 tdd，定期跑类型检查和测试，完成后调用 code-review，最后提交。

我会在这些场景用它：

• 已经有 spec 或 ticket，需要 agent 按任务实现。
• 想让实现过程自动套上 TDD 和提交前 review。
• 多个 ticket 已拆好，需要每个 ticket 用一个新上下文独立推进。

底层 Skills

grilling

来源：mattpocock/skills

用来对一个 plan 或 design 做连续追问。它的重点是沿着设计树一层层问下去，每次只问一个问题，并给出推荐答案，直到方案边界和依赖关系讲清楚。

我会在这些场景用它：

• 方案还停在“感觉可行”，需要被具体问题压实。
• 设计里有多个互相依赖的选择，需要逐个拆开。
• 想先做纯讨论，不急着写文档或改代码。

domain-modeling

来源：mattpocock/skills

用来主动维护项目领域模型。它会挑战模糊术语、补 edge-case 场景、交叉检查代码和现有 glossary，并在术语或决策定下来时更新 CONTEXT.md 或 ADR。

我会在这些场景用它：

• 项目里的业务词还不稳定，或者同一个词被多个意思复用。
• 需要把用户语言和代码里的概念对齐。
• grill-with-docs 要落地 glossary 或 ADR 时，需要它来维护领域模型。

codebase-design

来源：mattpocock/skills

用来给模块设计和测试边界提供共享词汇。重点是 deep module、interface、seam、adapter、locality 这些概念，适合在进入 TDD 前先决定测试应该穿过哪个接口。

我会在这些场景用它：

• 准备写测试，但还不确定测试 seam 应该放在哪里。
• 模块接口太浅、太散，想先收敛成更深的模块。
• tdd 或架构讨论需要统一 module、interface、seam、adapter 这些词。

tdd

来源：mattpocock/skills

用来按红绿灯推进实现。新版 tdd 更像红绿循环的参考纪律：测试只写在预先确认的 seam，通过公开接口验证行为，避免 implementation-coupled、tautological 和 horizontal slicing 这三类坏测试。重构和提交前检查交给 code-review 或架构流程承接。

我会在这些场景用它：

• 修 bug 时需要先复现行为。
• 新功能有清楚的核心契约。
• implement 进入具体编码，需要一轮一轮写红灯、补绿灯。

code-review

来源：mattpocock/skills

用来对一个固定基点之后的 diff 做两轴 review：一轴看仓库标准和代码味道，一轴看实现是否匹配 spec。新版 implement 会在完成后调用它。

我会在这些场景用它：

• 一个 ticket 做完，需要在提交前检查。
• PR 或分支需要同时看代码质量和 spec 对齐。
• TDD 已经跑完，想把重构、scope creep、遗漏需求在提交前抓出来。

improve-codebase-architecture

来源：mattpocock/skills

用来找架构加深机会。它会关注模块是否太浅、接口是否暴露太多、复杂度是否散在调用方，以及测试面是否真正落在公开接口上。

我会在这些场景用它：

• 代码能跑，但越来越难测、难改、难让 agent 理解。
• 逻辑被拆得很碎，理解一个概念要跳很多文件。
• 想把关键模块做成更深的模块，让小接口承接更多稳定行为。

可选增强项

这些 skill 很有用，但默认不放进主安装块，避免新仓库初始化时膨胀：

• triage：已有外部 issue / PR 请求，需要进入 label 驱动的分诊流。
• diagnosing-bugs：遇到难复现、间歇性、回归类 bug，需要先建立 tight feedback loop。
• prototype：方案靠文字对不齐，需要用一次性原型回答状态、逻辑或 UI 问题。
• research：需要后台 agent 去读 primary sources，并把结论落成 cited Markdown。
• handoff：上下文太大或需要分叉会话，用 Markdown handoff 跨 session 传递上下文。

推荐使用顺序

实际使用时不要一次把所有 skill 都打开。先看任务阶段：

1. 新仓库需要文档入口：先用 project-docs-system。
2. 工作大到无法在一个 session 内规划，而且路线仍有 fog：用 wayfinder 建 decision map；如果使用原生 issue tracker，先配置 setup-matt-pocock-skills。
3. 想把需求和领域语言讲清楚：用 grill-with-docs，它会带上 grilling 和 domain-modeling。
4. 需求方向已经对齐，但还缺 spec：用 to-spec。
5. Spec 或计划已经成型，需要拆任务并声明阻塞关系：用 to-tickets。
6. 已经有 ticket 或 spec，需要进入实现：用 implement。
7. 实现过程中需要红绿循环：implement 内部会用 tdd；单独做小行为也可以直接用 tdd。
8. 测试 seam、deep module、adapter 这些词需要先对齐：用 codebase-design。
9. 代码结构开始拖慢交付：用 improve-codebase-architecture。
10. 一个仓库决定完整采用 Matt issue tracker workflow：再安装并运行 setup-matt-pocock-skills。

这组 skills 和我的 Harness Engineering 配方 是同一条线：让 agent 沿着项目文档、跨 session 决策地图、拷问、领域建模、spec、ticket、implement、TDD、review 和架构反馈持续推进。