xufang5219/agent-skills

Ask Matt

你不可能记住每一个技能，所以直接问吧。

在说明某个技能的作用或建议跳过某个步骤之前，请先阅读该技能的 SKILL.md：此处的摘要仅用于初步了解。

流程 是贯穿各个技能的一条路径。大多数路径沿着一条主流程行进，并由两条入口流程汇入。其余的都是独立技能，或是在底层运行的词汇层。

主流程：从想法到发布

这是大多数工作会走的路线。你有一个想法，并希望把它构建出来。

1. /grill-with-docs 通过访谈来打磨想法。当你在工作目录中工作时，从这里开始：它是有状态的，会将学到的东西保留在 GLOSSARY.md 和 ADR 中。（没有工作目录？那就改用 /grill-me，它在独立技能部分介绍。两者都运行相同的 /grilling 原语；grill-with-docs 是会留下书面记录的那个，因此只要有仓库存在，它就是更好的选择。）
2. 分支：你能在对话中解决所有问题吗？ 如果一个问题的答案需要可运行的程序（状态、业务逻辑、必须看到的 UI），则绕道进行原型开发，通过 /handoff 在双向之间桥接（原型存放在自己的目录中，这正是 /handoff 的用途；参见阶段边界）：
   • 先使用 /handoff 向外传递，然后针对该文件开启一个新的会话，
   • 使用 /prototype 用可丢弃的代码来回答问题，
   • 使用 /handoff 将你学到的东西带回来，并在原始想法线程中引用它。
3. 分支：这是一个需要多个会话才能完成的构建吗？
   • 是 → /to-spec（将线程转化为规格说明），然后 /to-tickets 将其拆分为包含目标验证的任务，每个任务声明其阻断依赖边。然后通过以下两种方式之一处理这些任务：
     • 针对每个任务使用 /implement，并在任务之间使用 /clear 清空上下文。在本地追踪器上，这是 .scratch/<feature>/issues/ 下每个任务一个文件，按阻断依赖优先手动处理；在真正的追踪器上，依赖边会成为原生的阻断链接，因此任何依赖项已完成的任务都可以被领取。每个任务是自包含的，所以最后一个任务的上下文是可丢弃的。
     • 针对整个规格说明一次性使用 /implement-spec。它将任务视为任务图，并行地在准备好的前沿上运行实施子代理，并将所有内容合并到一条集成分支上。当你更倾向于编排构建过程而不是自己驱动每个任务时，请使用它。
   • 否 → 就在当前上下文窗口中使用 /implement。

无论哪种方式，代码都是通过驱动 /tdd（一次一个红-绿循环）来构建的，并以 /code-review 结束，后者是对差异（diff）进行二维检查（标准 + 规格）。/implement 为每个任务运行这两者；/implement-spec 的实施者各自驱动 /tdd，并在集成分支上运行一次 /code-review。当你只想在没有完整规格说明的情况下，通过测试驱动来构建一个具体行为时，请单独使用 /tdd；当你想要针对某个固定点审查一个分支或 PR 时，请单独使用 /code-review。

当工作以拉取请求（PR）的形式提交时，/pr 会塑造 PR 的主体：最小化展示变更的可视化内容、证明变更生效的前后对比证据，以及单向或双向决策标记。它由模型调用，因此代理在编写 PR 时会自动使用它。

4. /retro 完成循环。在构建之后，特别是当构建出现问题时，它会回顾整个会话，并建议更改代理的环境，而不是代码：导航指示、自动化检查、/code-review 强制执行的编码标准、辅助文件、工具配置。机械性错误变成确定性检查；设计决策变成编码标准。下一次构建将从更好的环境开始。

上下文卫生

将步骤 1-3 保持在一个连续不间断的上下文窗口中（在完成 /to-tickets 之前不要压缩或清空上下文），以便访谈、规格说明和任务都建立在相同的思考基础上。然后，每个 /implement 从任务开始，以全新的上下文执行。在你清空上下文之前，在它所回顾的那个会话中运行 /retro；清空上下文后，让它指向该会话的日志。

这一做法的上限是 智能区域：模型仍能清晰推理的窗口（在最新模型上约为 150k tokens）。如果一个会话在到达 /to-tickets 之前已接近这个上限，不要继续在性能下降状态下工作；在最近的阶段边界处使用 /compact 并继续（参见阶段边界）。

入口

指那些能产生工作，然后汇入主流程的起始场景。

• 错误和请求堆积如山 → /triage。它将问题通过分诊角色进行处理，并生成代理可直接处理的问题，之后由 /implement 接手。

分诊仅适用于不是你创建的问题：错误报告、收到的功能请求，任何原始到达的内容。由 /to-tickets 产生的任务已经是代理就绪状态，所以不要对它们进行分诊。

• 某个地方坏了 → /diagnosing-bugs。用于处理那些棘手的问题：一眼看不出原因的 bug、间歇性闪烁、在两个已知正常状态之间悄悄引入的回归。它拒绝在没有紧反馈循环（一个能够立即针对此 bug 变红的命令）的情况下进行理论分析，然后通过回归测试进行修复。修复完成后，在同一会话中运行 /retro 来询问是什么本可以阻止这个 bug；如果真正的发现是缺乏一个良好的隔离点来锁定它，那么这就是 /improve-codebase-architecture 的任务。

• 一个庞大而模糊的工作：全新的项目或巨大的功能构建，单个会话无法完成 → /wayfinder，这是这里认知要求最高的流程。当从此处到目的地的路径尚不可见时，它会在问题追踪器上绘制一个由决策任务组成的共享地图，并逐一解决这些任务，产生决策，而非可交付物，直到迷雾散去，路径清晰。当 /grill-with-docs 打磨的是一个可以在单个会话中掌握的想法时，wayfinder 适用于你无法掌握的想法，它更慢、更密集，所以请务必将其用于确切的情况，绝不要用于范围明确的功能。

当地图清晰后，它会进行交接，而不是构建：汇入主流程的 /to-spec，后者将地图中相互关联的决策压缩成一个可构建的计划，然后按常规执行 /to-tickets 和 /implement。直接将地图循环到 /implement 会跳过这个压缩步骤，并丢弃关联的细节，所以只有当工作量确实很小时，才直接进入 /implement。

代码库健康

不是功能开发，只是维护。

• /improve-codebase-architecture 在你空闲时运行，以保持代码库对代理的良好操作性。它揭示了深化机会；选择一个机会会_产生一个想法_，你可以带着这个想法进入主流程的 /grill-with-docs。它是发现候选对象的调查；下面的 /codebase-design 是你设计选定方案的工作台。

底层词汇

两个由模型调用的参考组件，运行在其他技能之下，每个都是其词汇的单一事实来源。当词语而非流程本身成为问题时，直接使用它们；或者让上面的技能自动调用它们。

• /domain-modeling：打磨项目的领域语言：质疑模糊术语，解决重载词汇（例如，“账户”承担了三个职责），将难以撤销的决策记录为 ADR。这是 /grill-with-docs 驱动的主动规范，以保持 GLOSSARY.md 成为一份干净的词汇表。
• /codebase-design 是深度模块词汇表（模块、接口、深度、隔离点、适配器、杠杆作用、局部性），用于设计模块的形状：在一个干净的隔离点后，用一个小接口封装大量行为。/tdd 和 /improve-codebase-architecture 都使用了它。

阶段边界

阶段 是会话内的一块工作：访谈、实现、质量验证。在两个阶段之间的边界处，你有五个选项，选择哪一个可能是整个技能地图中最模糊的决策：

• 继续：保持不变。不消耗成本，也不损失什么。
• /clear：清空窗口，当当前窗口的内容对下一步无关紧要时使用。
• /handoff 写入一个可移植的 markdown 文件。用途狭窄：仅用于新的工作环境、新的目录、同事，或在阶段中分支出一个旁支任务。它带来的是可移植性。
• 子代理：将一个范围明确的任务发送到它自己的窗口，并取回一份报告。
• /compact 压缩当前上下文，并用它来启动一个全新的会话。这是默认选项，位于决策树的底部，而不是首选。

阅读 PHASE-BOUNDARIES.md 了解有序的决策树：五个问题、每个分支背后的理由，以及为什么主要来源成本使得“继续”成为需要首先排除的选项。在边界处做出决策；在阶段中途，要么继续，要么将剩余部分拆分为子代理。

独立技能

完全独立于主流程。

• /grill-me：与 /grill-with-docs 相同的不懈访谈，但无状态：它不会在本地保存任何内容，也不会构建 GLOSSARY.md。当你不在工作目录中工作时使用它（打磨一个计划、一个设计、一篇文章，任何没有仓库与之相关的内容）。如果你在工作目录中，请改用 /grill-with-docs：它运行相同的访谈并留下书面记录，因此它严格来说是更好的选择。
• /grilling 是访谈原语本身：回合、前沿、事实是代理的工作，决策是你的工作。/grill-me 和 /grill-with-docs 是两种命名入口，/triage、/wayfinder 和 /improve-codebase-architecture 都在内部运行它。仅当你想要没有包装器的原始访谈时，才直接使用它。
• /prototype 是一个小型、可丢弃的程序，用于回答一个设计问题：这个状态模型感觉对吗？或者这个 UI 应该是什么样子？可丢弃是对代码编写方式的约束，而不是销毁它的承诺：答案会融入真实代码中，原型本身会作为主要来源保存在从主分支切出的 prototype/<name> 分支上，并从实现问题中引用。它是主流程步骤 2 中的绕道，但任何时候你发现某个设计问题很难在纸面上确定时，都可以使用它。
• /research：将阅读工作委托给后台代理：它会针对主要来源调查一个问题，然后在仓库中留下一份带有引用的 Markdown 文件。在它阅读的同时，你可以继续工作。它产生的文件是可以带入主流程 /grill-with-docs 的材料，因为研究为思考提供养分，而不是替代思考。
• /to-questionnaire 在你遇到的阻碍不在你脑中也不在代码库中，而是在别人的脑中时发挥作用，它会为他们编写一份问卷来填写。它是 /grill-me 的反向操作：不是向你询问关于主题的问题，而是向你询问关于发送对象（问卷发给谁，你需要什么样的反馈）的问题，并将问题瞄准信息空白。返回的材料是供 /grill-with-docs 或 /to-spec 使用的。
• /wizard 用于只有人类才能完成的步骤：配置基础设施、设置凭证或 CI 密钥、点击陌生第三方仪表板、执行一次性迁移或切换。它会生成一个交互式 bash 脚本，打开每个 URL，捕获每个值，并将其写入 .env 文件和 GitHub 密钥，这样该过程就不再需要每次向代理重新解释。由模型调用，因此代理在遇到只有你能通过的障碍时会自动使用它。如果代理自己能完成，它就应该自己完成；这个技能适用于人类确实需要参与循环的情况。
• /wait-what 是处理未正确理解的消息的纠正措施。在对话中途，在任何其他技能内部使用它，代理会使用你缺少的上下文，用简单的英语，使用 GLOSSARY.md 中的词汇，重新阐述它刚刚说过的话。它是事后弥补措施；/grill-with-docs 是前期解决方案，因为早期达成共识的共同语言正是阻止术语产生误解的根本。
• /teach：通过多个会话学习一个概念，使用当前目录作为有状态的工作空间。
• /writing-for-agents 是编写代理消费的文档的参考：技能、AGENTS.md、指向的文档。

前置条件

/setup-matt-pocock-skills：在运行你的第一个工程流程之前执行，以配置其他技能所依赖的问题追踪器、分诊标签和文档布局。自定义问题追踪器也可以工作。