mattpocock/skills

项目概述

mattpocock/skills 是一个由 Matt Pocock 维护的 AI 智能体技能（Skills）集合，旨在帮助开发者使用 Claude Code、Codex 等编码智能体进行真实的软件工程实践，而非简单的“vibe coding”。该仓库包含一系列小型、可组合、可适配的技能，覆盖从需求澄清、领域建模、测试驱动开发、代码审查到架构改进等完整开发流程。项目以 MIT 许可证开源，主要使用 Shell 语言编写，当前最新版本为 v1.2.3。

核心功能

• 需求澄清与规划：提供 /grill-me、/grill-with-docs、/wayfinder 等技能，通过结构化访谈帮助用户明确需求、建立领域语言并规划大型任务。
• 工程实践：包含 /tdd（测试驱动开发）、/code-review（双轴代码审查）、/diagnosing-bugs（系统化调试）、/resolving-merge-conflicts（合并冲突解决）等技能，强化代码质量与反馈循环。
• 架构与设计：/codebase-design 提供深度模块设计词汇，/improve-codebase-architecture 扫描代码库并生成改进报告。
• 任务管理：/to-spec、/to-tickets、/triage 等技能帮助将对话转化为规格、可执行工单，并管理外部提交的问题。
• 自动化辅助：/wizard 生成交互式 bash 脚本，引导用户完成手动配置步骤；/research 通过后台智能体进行资料调研。
• 多智能体协作：技能支持用户调用与模型自动调用两种模式，并可通过子智能体并行执行任务。

适用与不适用场景

适用场景：

• 使用 Claude Code、Codex 等编码智能体进行真实项目开发，希望提升代码质量与开发流程规范性。
• 需要澄清模糊需求、建立项目领域语言、规划大型功能或重构。
• 希望引入测试驱动开发、代码审查、系统化调试等工程实践。
• 管理外部提交的 issue 或 PR，需要分类、验证和生成可执行任务。

不适用场景：

• 简单的、单次会话即可完成的小改动，无需完整流程。
• 非软件工程领域的一般性任务（部分 productivity 技能除外）。
• 需要严格遵循特定组织流程或工具链的团队，可能需要大量定制。
• 对技能集有强控制需求，不希望智能体自动调用某些技能的场景。

技术架构与依赖

• 语言：Shell（主要），技能文件为 Markdown 格式。
• 依赖：需要 Claude Code 或 Codex 等支持技能（Skills）的编码智能体；部分技能依赖 gh（GitHub CLI）、glab（GitLab CLI）或 npx。
• 安装方式：
  • Claude Code 插件：claude plugins install mattpocock-skills
  • 其他智能体：npx skills@latest add mattpocock/skills
• 配置：通过 /setup-matt-pocock-skills 配置 issue 跟踪器、标签和文档布局。

安装与快速开始

1. 安装技能：
   • Claude Code：运行 claude plugins install mattpocock-skills 或在会话中输入 /plugin install mattpocock-skills。
   • 其他智能体：运行 npx skills@latest add mattpocock/skills，选择需要的技能。
2. 运行设置：在仓库中运行 /setup-matt-pocock-skills，回答关于 issue 跟踪器、标签和文档位置的问题。
3. 开始使用：根据需求调用相应技能，如 /grill-with-docs 进行需求澄清，/tdd 进行测试驱动开发。

典型使用方法

• 需求澄清：在开始新功能前，运行 /grill-with-docs 进行深度访谈，建立领域语言并更新 CONTEXT.md。
• 任务拆分：使用 /to-spec 将对话转化为规格，再用 /to-tickets 拆分为可执行的工单。
• 实现与测试：对每个工单运行 /implement，内部驱动 /tdd 进行测试驱动开发。
• 代码审查：在提交前运行 /code-review，从标准和规格两个维度审查代码。
• 架构改进：定期运行 /improve-codebase-architecture 扫描代码库，发现可深化的模块。

配置与部署要点

• Issue 跟踪器：支持 GitHub、GitLab、本地 Markdown 文件，通过 /setup-matt-pocock-skills 配置。
• 标签：默认使用 needs-triage、needs-info、ready-for-agent、ready-for-human、wontfix 等标签，需在跟踪器中手动创建。
• 领域文档：默认使用单上下文 CONTEXT.md 和 docs/adr/，多上下文需配置 CONTEXT-MAP.md。
• 部署：技能文件可复制到项目中，或通过插件方式订阅更新；插件方式为只读，更新自动。

限制、风险与许可证

• 许可证：MIT。
• 已知问题：部分技能存在已知 bug，如 code-review 与 Claude Code 内置命令冲突、research 可能嵌套子智能体导致 token 消耗过高、to-tickets 在 GitHub 上可能无法创建子 issue 等。
• 风险：技能可能过度触发，导致不必要的流程；生成的文档可能过时或包含错误；使用 diagnosing-bugs 时需注意敏感信息泄露。
• 限制：技能集主要针对 Claude Code 和 Codex 优化，其他智能体兼容性有限；部分技能依赖特定工具（如 gh）。

官方链接

• GitHub 仓库：https://github.com/mattpocock/skills
• 最新版本：https://github.com/mattpocock/skills/releases/tag/v1.2.3
• 技能安装工具：https://skills.sh/mattpocock/skills
• 作者新闻通讯：https://www.aihero.dev/s/skills-newsletter

信息来源和分析时间

• 信息来源：GitHub 仓库 README、CHANGELOG、文档目录（docs/engineering、docs/productivity）及最新发布信息。
• 分析时间：2026年8月6日（基于最新发布 v1.2.3 的日期）。

📋 正确的执行顺序

flowchart LR
    A["/grill-with-docs<br>（对齐需求）"] --> B["/to-spec<br>（生成规格说明）"]
    B --> C["/to-tickets<br>（拆解为工单）"]
    C --> D["/tdd<br>（逐个实现）"]

步骤	技能	输入	输出
第一步	/to-spec	你刚才和 AI 讨论的所有内容（需求、设计决策等）	一份结构化的 Spec（规格说明），记录“做什么”
第二步	/to-tickets	刚才生成的 Spec	多个 Ticket（工单），每个都是可独立开发的任务单元

🔍 为什么是这个顺序？

1. /to-spec 负责“写什么”：它把你零散的想法、对话中的决策整理成一份完整、清晰的规格文档。这份文档是后续所有工作的“宪法”。

2. /to-tickets 负责“怎么拆”：它基于这份完整的 Spec，智能地切割成相互独立、有明确依赖关系的工单。如果没有 Spec 直接拆，可能会遗漏需求或拆分不合理。

💡 实际使用示例

你：/grill-with-docs 我想做一个用户积分系统
AI：（追问细节...）
你：（回答问题，确认需求）

你：/to-spec
AI：已根据对话生成 Spec.md，包含：
- 功能概述：用户可通过签到、评论获得积分
- 业务规则：每日签到得1分，评论得2分（每日上限10分）
- 非功能需求：积分变动需记录日志
...（等待你确认或修改）

你：确认无误

你：/to-tickets
AI：已根据 Spec 拆解为以下工单：
- T-1: 创建积分记录表（数据库迁移）
- T-2: 实现签到积分逻辑（依赖 T-1）
- T-3: 实现评论积分逻辑（依赖 T-1）
- T-4: 积分变动日志记录（依赖 T-2, T-3）
- T-5: 用户积分查询接口（依赖 T-1）

✅ 跳过 /to-spec 直接 /to-tickets 行吗？

虽然技术上可以（有些 AI 能根据对话上下文直接拆），但不推荐。原因：

• Spec 是“设计蓝图”，能帮你提前发现需求矛盾或遗漏
• 直接拆出来的工单可能质量不高，遗漏细节
• Spec 文档本身也是重要的项目资产，方便后续查阅和团队对齐

最稳妥的流程：/grill-with-docs → /to-spec → /to-tickets → 逐个实现。这样每一步都有明确的输入和输出，不容易出错。