mattpocock/skills：用 /grill-with-docs 约束编码代理开发
一套给 Claude Code、Codex 等编码代理用的工程技能文件，比整套流程框架更小、更可组合。
GitHub mattpocock/skills 更新 2026-09-04 分支 main 星标 274.7K 分叉 23.1K
Shell JavaScript Claude Code Codex AI 编码代理

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你用 Claude Code，想从官方 marketplace 安装一套自动更新的只读技能
    Installation 章节称 Claude Code plugin 是官方 marketplace 的 managed, read-only bundle，更新会自动到达
  • 你用 Codex 或其他代理，想把技能复制到项目后自行编辑
    Installation 章节说明 npx skills 会把技能写入 repo，作为你拥有和编辑的 ordinary files
  • 你需要代理在写规格前确认模块范围，并用 /tdd 强化测试反馈
    Why These Skills Exist 的 #3 和 #4 分别介绍 /tdd 与 /to-spec
  • 你希望用 /grill-with-docs 建立共享语言并记录 ADR 决策
    Why These Skills Exist 的 #2 说明 /grill-with-docs 会建立 shared language 并记录 hard-to-explain decisions in ADRs

不适合，如果你

  • 你需要原生 Codex 插件，而不是 npx skills 安装的文件
    Installation 章节明确写着 native Codex plugin is on the roadmap
  • 你必须直接修改 Claude Code 的托管技能副本
    Installation 章节说明 Claude Code plugin 是 managed, read-only bundle
  • 你期待 /improve-codebase-architecture 自动清理成熟代码库的复杂性
    Why These Skills Exist 的 #4 明确说它是 survey, not a rescue，不会 untangle the mud
  • 你不希望安装时选择 issue tracker、triage labels 和文档保存位置
    Installation 的第 2 步说明 /setup-matt-pocock-skills 会询问这三项配置

前置条件

  • 需要 Claude Code、Codex 或其他 coding agent 环境；README 未列出完整兼容清单
  • 安装时二选一：Claude Code plugin 或 npx skills@latest add mattpocock/skills
  • 使用 npx skills 时，安装器会让你选择技能及其要安装到的 coding agents
  • 每个 repo 需要在 agent 中运行一次 /setup-matt-pocock-skills

第一步命令（README 原文）

claude plugins install mattpocock-skills

要注意

  • 安装器必须把 setup-matt-pocock-skills 选入，否则 README 的初始化步骤无法按说明执行
    Installation 的 Codex、other agents 部分明确要求选择 setup-matt-pocock-skills
  • 同一 repo 需要运行一次 /setup-matt-pocock-skills，并完成三项配置问答
    Installation 第 2 步写明 run it once per repo，并列出三项问题
  • skills.sh 文件不会后台更新，需手动执行 npx skills update 获取最新改动
    Installation 的 For tinkerers 部分说明 Nothing updates behind your back，并给出 npx skills update

替代方案

  • GSD：当你希望由一个方法直接拥有开发流程，而不是组合可编辑技能时
    README 的开头对 GSD、BMAD、Spec-Kit 的对比
  • BMAD：当你偏好由 BMAD 这类流程方案统一管理开发过程时
    README 的开头对 GSD、BMAD、Spec-Kit 的对比
  • Spec-Kit：当你希望采用 Spec-Kit 这类拥有整个流程的方案，而非自行组合技能时
    README 的开头对 GSD、BMAD、Spec-Kit 的对比

材料未说明

  • README 未说明 Claude Code、Codex 及其他代理的具体版本兼容范围
  • README 未提供完整技能目录；Reference、Engineering、Productivity 章节内容被省略
  • README 未说明 /grill-me、/tdd 和 /diagnosing-bugs 的输入输出格式与失败行为
  • README 未给出 Shell、JavaScript 运行时依赖的版本要求
  • README 未提供自动化测试结果、性能数字或安全审计信息
  • README 未说明 GitHub、Linear 与 local files 配置完成后的具体集成权限

💡 深度解析

7
不适合 我正在用 Claude Code 或 Codex 维护复杂历史代码库，希望代理扫描出问题后直接完成大规模架构重构；这个项目适合承担自动解开代码泥团的任务吗？
适合读者： 使用 Claude Code 或 Codex 维护复杂历史代码库、希望代理自动完成架构重构的资深工程师

不适合把它当作自动重构引擎，因为项目提供的是架构调查和代理行为指导，不是替你完成大规模迁移的工具。

  • 项目洞察明确将 improve-codebase-architecture 定义为定期扫描代码库、识别模块加深和职责调整候选点的机制。
  • 同一洞察说明它是调查工具，不负责自动解开老旧代码库的复杂泥团。
  • README 的定位是 small、easy to adapt、composable 的 skills，并强调不应像 GSD、BMAD、Spec-Kit 那样接管整个过程。
  • /diagnosing-bugs 关注分阶段调试，不等于架构迁移或批量重构执行器。

如果目标是让代理提出候选改进并保留工程师决策权，它适合；如果目标是无人值守完成重构，则不适合。

  • 项目洞察 solution_analysis.key_features：improve-codebase-architecture 定期扫描代码库，识别模块加深、职责调整等架构候选点
  • 项目洞察 user_experience.usage_limitations：架构审查只能提供候选改进方向，不能自动完成系统性迁移
  • README「Skills For Real Engineers」：These skills are designed to be small, easy to adapt, and composable
  • README「Skills For Real Engineers」：GSD, BMAD, and Spec-Kit try to help by owning the process
npx skills@latest add mattpocock/skills
材料未说明：README 未说明架构扫描的具体规则、输出格式以及是否能接入现有 issue tracker。；README 未说明任何自动重构、迁移回滚或变更影响分析能力。
适合 我在维护真实应用，想让 Claude Code 或 Codex 在实现前先澄清需求、建立 CONTEXT.md 和 ADR，再用 red-green-refactor 开发；这个项目能覆盖这条流程吗？
适合读者： 维护真实应用的资深工程师，希望把需求澄清、CONTEXT.md、ADR 和 TDD 纳入日常代理流程

适合，因为 README 直接把需求盘问、共享语言、ADR 和 /tdd 作为连续的工程实践，而不是只提供代码生成提示。

  • /grill-with-docs 用于在开始变更前与 agent 对齐，并帮助建立共享语言和 ADR。
  • README 以 CONTEXT.md 示例说明，术语统一后变量、函数和文件命名更一致，agent 也能减少思考 token。
  • /tdd 明确鼓励 red-green-refactor：先写失败测试，再修复测试，最后重构。
  • /diagnosing-bugs 将调试包装为分阶段、带门槛的循环，适合把实现后的反馈接回流程。

它不会替代测试框架、类型系统或浏览器环境；这些反馈源仍需你的项目本身提供。

  • README「#1: The Agent Didn't Do What I Want」：Use /grill-me and /grill-with-docs；Use them every time you want to make a change
  • README「#2: The Agent Is Way Too Verbose」：helps you build a shared language with the AI, and document hard-to-explain decisions in ADR's
  • README「#3: The Code Doesn't Work」：a red-green-refactor loop is critical；/tdd skill
  • README「#3: The Code Doesn't Work」：/diagnosing-bugs skill wraps best debugging practices into a disciplined loop
npx skills@latest add mattpocock/skills
材料未说明：README 未说明你的具体测试框架、类型检查器或浏览器工具是否有专门适配。；README 未规定 CONTEXT.md 和 ADR 的具体模板、字段或目录结构。
适合 我希望在每个仓库首次启用技能时选择 GitHub、Linear 或 local files 作为 issue tracker，自定义 `/triage` 使用的 labels，并指定文档保存位置；这个项目能满足这些仓库级约束吗？
适合读者： 需要在 GitHub、Linear 或本地文件中管理任务，并希望每个仓库独立保存代理文档的开发者

适合，因为项目提供了按仓库执行一次的 setup 流程，直接询问 issue tracker、标签和文档目录，而不是把这些选择写死。

  • README 要求在 agent 中运行 /setup-matt-pocock-skills，并说明每个 repo 运行一次。
  • setup 会让你在 GitHub、Linear 或 local files 之间选择 issue tracker。
  • 它还会询问 ticket triage 使用的 labels，以及保存所创建文档的位置。
  • skills.sh 模式把文件写入你的 repo 并允许编辑，适合把配置和文档纳入项目自己的版本控制；Claude Code 托管插件则是只读模式。

因此，仓库级配置与本地拥有模式匹配良好；但不同 tracker 的实际 API 权限和自动化深度，README 没有展开。

  • README「2. Run /setup-matt-pocock-skills」：In your agent, run it once per repo
  • README「2. Run /setup-matt-pocock-skills」：Ask you which issue tracker you want to use (GitHub, Linear, or local files)
  • README「2. Run /setup-matt-pocock-skills」：Ask you what labels you apply to tickets when you triage them
  • README「2. Run /setup-matt-pocock-skills」：Ask you where you want to save any docs we create
/setup-matt-pocock-skills
材料未说明：README 未说明 GitHub、Linear 和 local files 三种模式分别支持哪些具体命令或操作。；README 未说明配置是否会写入哪个文件，以及是否支持多个 issue tracker 并存。
适合 我正在用 Claude Code 开发真实应用，希望直接获得完整技能集并在新版本发布时自动更新，同时不想让项目里出现一份可编辑副本；这个项目适合我吗？
适合读者： 使用 Claude Code 开发真实应用、希望技能自动更新但不想维护本地副本的个人开发者

适合，因为 Claude Code 插件正好提供了托管、只读并自动更新的完整技能集。

  • README 的 Installation 说明，插件模式会安装 whole set，并在作者发布更新时自动获取更新。
  • 安装入口来自 Claude Code 官方 marketplace，不需要先添加其他源。
  • 技能本身是小型、可组合且支持 any model 的 agent skills，适合按命令调用，而不是接管整个研发过程。
  • 需要避免同时使用 skills.sh；README 明确说两种方式并存会导致每个技能出现两次。

这种模式的代价是你不能直接编辑托管技能；如果组织需要审计或项目级定制，应改用可复制的本地文件模式。

  • README「Installation (30-second setup)」：Claude Code plugin installs the whole set as a managed, read-only bundle that updates when I ship
  • README「Installation (30-second setup)」：It's in Claude Code's official marketplace
  • README「Skills For Real Engineers」：small, easy to adapt, and composable. They work with any model
  • README「Installation (30-second setup)」：installing both leaves you with every skill twice
claude plugins install mattpocock-skills
材料未说明：README 未说明自动更新是否支持组织级审批、锁定版本或离线使用。；README 未列出 Claude Code 插件对所有技能的具体调用兼容性。
适合 我使用 Claude Code、Codex 或其他编码代理，但不想让 GSD、BMAD 或 Spec-Kit 接管整个研发流程；我只想组合 `/grill-with-docs`、`/tdd` 和架构审查技能，这个项目是否更符合我的约束？
适合读者： 使用任意模型和 Claude Code、Codex 或其他编码代理、拒绝采用封闭式全流程框架的个人开发者或小型团队

适合，因为项目的明确定位就是以小粒度、可组合、可编辑的 skills 介于自由提示词和重型全流程框架之间。

  • README 说这些技能 work with any model，并强调 small、easy to adapt、composable。
  • 安装器允许选择想要的 skills，因此可以只引入 /grill-with-docs、/tdd 或其他特定能力。
  • 项目明确批评由 GSD、BMAD、Spec-Kit owning the process 所带来的控制权损失，设计目标是让用户 hack on them、make them your own。
  • skills.sh 会把技能复制成仓库中的普通文件；这使团队可以审查、修改和版本控制流程，而不是接受不可变的黑盒。

需要注意的是，选择性组合也意味着你要自己决定哪些阶段如何衔接；项目不会替你拥有完整流程。

  • README「Skills For Real Engineers」：small, easy to adapt, and composable. They work with any model
  • README「Installation (30-second setup)」：The installer lets you choose which skills to take
  • README「Skills For Real Engineers」：GSD, BMAD, and Spec-Kit try to help by owning the process；take away your control
  • README「Installation (30-second setup)」：writes the skills into your repo as ordinary files you own and can edit
npx skills@latest add mattpocock/skills
材料未说明：README 未说明同时选择多个技能时的调用顺序、冲突处理或共享状态机制。；README 未给出 Codex、Claude Code 和其他 agents 在技能行为上的完整差异。
视情况 我使用 Codex 开发真实应用，偏好官方原生插件而不是把技能文件复制到仓库；当前这个项目能满足我的安装约束吗？
适合读者： 使用 Codex 开发真实应用、希望像 Claude Code 一样安装官方原生插件的开发者

视情况：Codex 可以通过 skills.sh 使用这些技能，但 README 明确表示原生 Codex 插件仍在路线图中，因此目前不能按“官方原生插件”这一约束确认满足。

  • README 为 Codex 和其他 agents 提供了 npx skills@latest add mattpocock/skills 安装路径。
  • 安装器允许选择技能以及要安装到哪些 coding agents，因此不必引入完整集合。
  • 复制模式会把技能写入仓库，作为你拥有并可编辑的普通文件；这与“不落地文件”的偏好相冲突。
  • setup-matt-pocock-skills 必须在选择安装时一并选中，否则后续项目配置无法按 README 的流程完成。

如果你接受本地文件，项目现在可用；若必须等待原生插件，则当前不满足。

  • README「Installation (30-second setup)」：Codex, and other agents；npx skills@latest add mattpocock/skills
  • README「Installation (30-second setup)」：A native Codex plugin is on the roadmap
  • README「Installation (30-second setup)」：It writes the skills into your repo as ordinary files you own and can edit
  • README「Installation (30-second setup)」：make sure setup-matt-pocock-skills is one of them
npx skills@latest add mattpocock/skills
材料未说明：README 未说明当前 skills.sh 对 Codex 的具体目录布局、命令加载方式和功能覆盖差异。；README 未给出原生 Codex 插件的发布时间。
视情况 我使用 Claude Code 开发真实应用，经常遇到 agent 没有理解需求、跳过测试并直接修改代码的情况；我能否用 `/grill-me`、`/grill-with-docs` 和 `/tdd` 针对这些约束建立反馈闭环？
适合读者： 正在处理需求经常被误解、代码缺少测试反馈的 Claude Code 使用者，希望先用非代码需求盘问再实现

视情况：这些技能覆盖需求对齐和测试反馈，但它们只能指导 agent，不能保证 agent 一定执行完整流程。

  • README 将 misalignment 视为常见失败模式，并推荐 /grill-me 处理 non-code uses、/grill-with-docs 处理工程变更。
  • /tdd 提供 red-green-refactor 指导，目标是先有失败测试，再获得实现反馈。
  • README 同时要求真实反馈源，包括 static types、browser access 和 automated tests；如果项目没有这些条件，agent 仍可能处于盲飞状态。
  • 项目洞察明确指出技能不是编译器、测试框架或代码质量平台，也不能消除模型幻觉和执行不可靠。

所以它适合作为流程约束层，不适合作为“自动保证正确”的质量门禁。

  • README「#1: The Agent Didn't Do What I Want」：The most common failure mode ... is misalignment；use /grill-me and /grill-with-docs
  • README「#3: The Code Doesn't Work」：You need ... static types, browser access, and automated tests
  • README「#3: The Code Doesn't Work」：a red-green-refactor loop is critical
  • 项目洞察 user_experience.usage_limitations：本质上是 agent 行为指导和工作流资产，不是编译器、测试框架、代码质量平台
claude plugins install mattpocock-skills
材料未说明：README 未说明 agent 跳过技能阶段时是否存在强制检查、失败退出或 CI 集成。；README 未说明 `/tdd` 对无测试遗留项目的具体迁移策略。

✨ 核心亮点

  • 248,424 星，覆盖 Claude Code、Codex 等代理
  • /grill-with-docs 将提问、共享语言和 ADR 结合
  • /tdd 内置 red-green-refactor 测试循环
  • 安装 Claude Code 插件与 skills.sh 会产生两份技能

🔧 工程化

  • /setup-matt-pocock-skills 配置 GitHub、Linear 或本地文件
  • /to-spec 在生成规格前询问涉及哪些模块
  • /diagnosing-bugs 将调试拆成分阶段流程
  • 共享语言示例把 materialization cascade 固化为术语

⚠️ 风险

  • Claude Code 插件是只读托管包，不能直接修改技能文件
  • README 明确说插件与 skills.sh 同装会让每个技能出现两次
  • /improve-codebase-architecture 只是调查，不会解开旧代码泥团
  • 原生 Codex 插件仍在 roadmap，当前依赖 npx skills 安装

👥 适合谁？

  • 使用 Claude Code 并希望官方市场自动更新的开发者
  • 使用 Codex 或其他代理并要编辑普通技能文件的团队
  • 需要 /tdd、/to-spec 和 ADR 工作流的工程项目
  • 希望让代理掌握项目术语与模块边界的开发者