## 项目概述

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 的日期）。

### 📋 正确的执行顺序

```mermaid
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 直接拆，可能会遗漏需求或拆分不合理。

### 💡 实际使用示例

```text
你：/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` → 逐个实现。这样每一步都有明确的输入和输出，不容易出错。