xtl
Back to writing

/ Skills

[Skills-01] Start with the Map: Composing Agent Engineering Workflows

A map of the 41 skills in mattpocock/skills: the main flow, on-ramps, routing, project setup, and principles for predictable skills.

2 minSkill · AI Agent · Workflow · Engineering

这套仓库最值得学习的不是某一句 prompt，而是它把软件工程活动拆成了可以组合的工作流。本文基于仓库提交 2ab9580（2026-07-28）整理；当时共有 41 个 SKILL.md，包括 stable、in-progress、misc、personal 和 deprecated 五种状态。

这篇先看全局，并提炼三个直接负责“系统如何运转”的 skill：ask-matt、setup-matt-pocock-skills、writing-great-skills。

1. 不是大一统框架，而是小型可组合能力#

仓库的立场很明确：不要让一个庞大框架接管全部开发过程。每个 skill 只负责一个可命名的动作，通过共享术语和产物连接起来。

主流程可以压缩成：

想法
  -> grill-with-docs：把模糊问题问清楚
  -> to-spec：固化用户目标、设计与测试决策
  -> to-tickets：切成有依赖关系的纵向切片
  -> implement：逐个实现
       -> tdd：红-绿循环
       -> code-review：标准与规格双轴审查
  -> 交付

还有三条常见入口：

  • issue 堆积时从 triage 进入；
  • 难复现的故障从 diagnosing-bugs 进入；
  • 大到单个上下文装不下的工作从 wayfinder 进入。

关键点是“产物即接口”。访谈输出 domain glossary 和 ADR，spec 输出稳定的决策，tickets 输出依赖图，handoff 输出跨上下文摘要。后一步不依赖前一步的聊天记忆，而依赖可检查的工件。

2. ask-matt：Skill 多了以后需要路由器#

ask-matt 解决的是 skill 的发现成本。用户调用它，不是为了执行工作，而是问“我现在处于什么状态，下一步应该走哪条 flow”。

它把能力分成五类：

区域适用问题代表 skill
Main flow从想法走到交付grill-with-docs -> to-spec -> to-tickets -> implement
On-ramps从 bug、issue 或大型未知进入diagnosing-bugs、triage、wayfinder
Codebase health主动改善可维护性improve-codebase-architecture
Vocabulary统一业务与架构语言domain-modeling、codebase-design
Standalone原型、研究、教学、上下文交接prototype、research、teach、handoff

这体现了一个实用规则：用户手动触发的 skill 变多后，不要把每个 skill 都改成自动触发；增加一个路由器，把“记住所有命令”的认知负担集中到一个入口。

3. setup-matt-pocock-skills：先把环境契约写下来#

很多 workflow 会读写 issue、标签、CONTEXT.md 和 ADR。如果这些位置没有统一约定，skill 每次都要重新猜。

初始化 skill 一次性确定三件事：

  1. issue tracker 是 GitHub、GitLab、本地 Markdown，还是其他系统；
  2. needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix 分别映射到什么标签；
  3. domain glossary 与 ADR 存放在哪里，以及 Agent 何时必须读取它们。

最终约定写进项目已有的 AGENTS.md 或 CLAUDE.md。它不是业务配置，而是 workflow 的依赖注入：同一套 skill 可以适配不同 tracker 和文档布局，后续 skill 只读取契约，不重复询问。

4. writing-great-skills：可预测性比文采重要#

这个 skill 是整个仓库的元方法。它将优秀 skill 的目标定义为：从随机系统中提取过程上的确定性。输出内容不必相同，但每次都应该走相同的可靠路径。

4.1 先决定谁能触发#

  • Model-invoked：description 会常驻上下文，Agent 可自动选择；适合必须自动发现或会被其他 skill 调用的能力。
  • User-invoked：只有用户显式调用；节省上下文，但要求用户记得它存在。

因此 description 不是普通简介，而是路由规则。它应以前导词开头，每个真实分支只写一个触发条件，避免把同义句重复堆进去。

4.2 把信息放在正确层级#

立即执行的动作       -> SKILL.md 中的 step
每次都可能查询的规则 -> SKILL.md 中的 reference
仅特定分支才需要     -> 外部 reference + 清晰的 context pointer

Step 需要可检查的完成条件。例如“处理所有修改过的 model”比“检查 model”更不容易提前结束。外部参考则用于 progressive disclosure：只有进入相应分支才加载细节。

4.3 用前导词压缩行为#

仓库大量使用已有工程概念作为 leading word：

  • red 代表能明确失败的反馈信号；
  • tight loop 代表低成本、可重复的验证闭环；
  • tracer bullet 代表端到端纵向切片；
  • fog of war 代表尚不能准确表述的问题空间。

这些词既压缩 token，也让 Agent 借用预训练中已有的概念结构，比反复写一长串规则更稳定。

4.4 常见失败模式#

  • Premature completion：步骤还没真正完成，Agent 已经开始追逐“结束”；应先强化完成条件。
  • Duplication：同一规则出现在多个位置，修改时会漂移；应保持单一事实来源。
  • Sediment：旧规则不断沉积，只加不删；应逐句执行 no-op test。
  • Context load：自动触发 skill 的描述长期占用上下文；只有独立发现能力值得这个成本。

5. 41 个 skill 的阅读地图#

后续文章按工作问题重组，而不是照文件夹机械翻译：

文章主题覆盖数量
Skills-02访谈、对齐与领域语言4
Skills-03Spec、ticket 与大型工作规划4
Skills-04原型、TDD、实现、调试、审查、冲突解决6
Skills-05深模块、架构体检、研究、triage、TS 边界5
Skills-06交接、教学、写作与交互式流程实验9
Skills-07Git、测试迁移、课程脚手架与个人工具6
Skills-084 个 deprecated skill 及其演化原因4

加上本文的 3 个，共计 41 个，不忽略实验性或已废弃目录。阅读时最重要的区分是：stable 表示作者日常使用；in-progress 可能随时破坏性变化；deprecated 适合研究演化，不应直接照搬。

参考#