Skill 的核心作用#

Skill 不能代替你做业务决策。它的价值是让 AI 按可靠流程完成工作，而不是让 AI 自由发挥。

1. /setup-matt-pocock-skills：初始化项目#

**作用：**为当前项目建立统一的工作约定。

它会配置 Issue 追踪器、文档目录、标签和项目规则。后续 /to-prd、/to-issues、/handoff 等 Skill 才知道文档应该写到哪里、任务应该发布到哪里。

**适合什么时候用：**一个仓库第一次安装这套 Skills 时。

**主要产出：**项目级配置、文档目录和 AI 工具规则。

2. /grill-me：需求拷问#

**作用：**让 AI 在动手之前，反过来追问你的计划和设计。

它有三个重要规则：

1. 一次只问一个问题。
2. 每个问题都给出推荐答案。
3. 能从文件和环境中查到的事实直接去查，需要做决定时再询问你。

它会沿着需求的决策分支继续追问，直到双方达成共识。这样可以提前发现遗漏的角色、异常流程、权限边界和数据规则。

**适合什么时候用：**还在讨论一个想法，或者需求比较模糊，但暂时不需要生成项目文档时。

**主要产出：**经过充分澄清的需求和设计共识。

调用示例：

1
/grill-me 我准备开发一个员工考勤功能，请帮我把需求问清楚

3. /grill-with-docs：带文档的需求拷问#

**作用：**在 /grill-me 的基础上，把讨论结果同步写进项目文档。

它通常会维护两类内容：

• CONTEXT.md：记录项目术语、业务规则和共享语言。
• ADR：记录重要且难以逆转的架构决策。

例如，团队确认“补卡”是员工对历史考勤发起的修正申请，这个定义会写进 CONTEXT.md。后续只要提到“补卡”，AI 就能理解它的准确含义。

ADR 不应该记录每个小决定，只记录那些以后缺少背景会令人困惑、修改成本较高的关键决策。

**适合什么时候用：**已经有代码仓库，希望需求共识能够被后续会话和团队成员继续使用时。

**主要产出：**CONTEXT.md、ADR 和经过确认的需求。

调用示例：

1
/grill-with-docs 我要做一个微人事系统，包含员工、部门和考勤管理

4. /to-prd：生成产品需求文档#

**作用：**把已经讨论清楚的内容整理成正式 PRD。

它不会代替需求澄清。正确顺序是先通过 /grill-me 或 /grill-with-docs 达成共识，再让 /to-prd 固化结果。

一份可用的 PRD 应该写清：

• 项目目标和非目标。
• 用户角色。
• 功能范围。
• 主流程与异常流程。
• 权限规则。
• 可以验证的验收标准。

**适合什么时候用：**需求已经基本确定，需要形成正式文档或交给其他人继续执行时。

**主要产出：**PRD 文档或发布到 Issue 追踪器中的产品需求。

调用方式：

1
/to-prd

5. /to-issues：把需求拆成任务#

**作用：**将 PRD 拆成可以独立开发和验证的 Issue。

这个 Skill 强调“垂直切片”，也就是一个 Issue 应该覆盖完成某项用户功能需要的前端、后端、数据和测试，而不是拆成“先写全部数据库，再写全部后端，最后写全部前端”。

例如：

• 好的拆分：员工入职，包含表单、接口、数据保存和验证。
• 不好的拆分：创建所有数据库表。

垂直切片完成后就能独立演示和验收，也更适合在短会话中交给 AI 实现。

**适合什么时候用：**PRD 已经完成，准备进入开发阶段时。

**主要产出：**带依赖关系、验收标准和测试范围的 Issue。

调用方式：

1
/to-issues

6. /tdd：测试驱动开发#

**作用：**约束 AI 按照“红、绿、重构”的循环逐步写代码。

完整循环是：

1. 红：先写一个能够失败的测试。
2. 绿：只写刚好能让测试通过的代码。
3. 重构：清理实现，同时保持测试通过。
4. 再进入下一个行为。

它不会一次性写完所有测试，再一次性实现所有代码。每次只验证一个小行为，避免 AI 根据尚不存在的 API 凭空设计大量测试。

在开始之前，它还会确认测试接缝。接缝是系统对外暴露的稳定边界，例如函数参数和返回值、REST API 或用户操作结果。测试应该验证公开行为，而不是紧盯内部实现。

**适合什么时候用：**实现一个已经明确、可以独立验收的 Issue 时。

**主要产出：**逐步变绿的测试、最小实现和经过重构的代码。

调用示例：

1
/tdd 实现 Issue #1：员工入职

7. /code-review：代码审查#

**作用：**从正确性、安全性、性能、可维护性和测试覆盖等角度审查代码。

它适合在一个 Issue 完成后使用。高质量的 Review 应该给出具体文件、位置、影响和复现依据，并按严重程度排列，而不是只评价代码风格。

**适合什么时候用：**功能完成、测试通过，准备合并或进入下一个 Issue 之前。

**主要产出：**问题清单、风险说明和最小修复建议。

调用示例：

1
/code-review 审查 Issue #1 的全部改动

8. /diagnosing-bugs：纪律化诊断 Bug#

**作用：**让 AI 先复现问题，再定位和修复。

它通常遵循六个阶段：

1. 建立稳定复现。
2. 最小化重现场景。
3. 提出可能原因。
4. 通过日志、断点或实验验证假设。
5. 实施最小修复。
6. 增加回归测试。

最重要的规则是：没有建立反馈循环之前，不允许跳到“猜原因”。反馈循环可以是失败测试、curl 请求、脚本或浏览器自动化，只要能够稳定判断 Bug 是否存在即可。

**适合什么时候用：**Bug 原因不明确，或者已经反复修改仍未解决时。

**主要产出：**复现方式、根因、修复和回归测试。

调用示例：

1
/diagnosing-bugs 员工入职时提示“部门不存在”，但该部门在数据库中可以查到

9. /wayfinder：规划大型项目#

**作用：**把一次对话无法承载的大项目拆成有依赖关系的决策地图。

它不会试图在项目开始时预测所有细节，而是先确定当前必须做出的决策。随着前置决策完成，后续任务会逐渐清晰。

每个决策可以放到一个新的干净会话中处理，避免长对话积累大量无关上下文。

**适合什么时候用：**项目跨多个模块、决策相互依赖，或者一个会话已经无法容纳完整上下文时。

**主要产出：**决策地图、有依赖关系的 Issue 和后续探索路径。

小型功能通常不需要 /wayfinder，使用 /grill-me 和 /to-issues 就够了。

10. /improve-codebase-architecture：架构体检#

**作用：**扫描现有代码库，找出模块边界、依赖关系和可维护性方面的问题。

它重点关注接口复杂但能力有限的“浅模块”、重复逻辑、循环依赖和职责过大的模块。根据 Skill 版本不同，可能会生成带架构图的 HTML 报告，并标注每项建议的优先级。

**适合什么时候用：**项目已经有一定规模，或者每完成几个 Issue 后做一次定期检查。

**主要产出：**架构报告、问题说明和改进建议。

调用方式：

1
/improve-codebase-architecture

报告只是建议。选择具体改进项后，仍然应该走测试和代码审查，不要一次性重构整个项目。

11. /handoff：上下文交接#

**作用：**把当前长对话压缩成下一次会话可以直接读取的交接文档。

交接文档通常包括：

• 已完成的工作。
• 已确认的关键决策。
• 修改过的文件。
• 测试命令和结果。
• 未解决的问题。
• 推荐的下一步和下一次应使用的 Skill。

它还应该移除 API 密钥、密码等敏感信息。

**适合什么时候用：**当前对话过长、准备切换会话、暂停任务或交给其他人继续时。

**主要产出：**HANDOFF.md 或同类交接文档。

调用方式：

1
/handoff

12. /teach：让 AI 带你学习#

**作用：**把 AI 变成一位能够规划课程、整理资料和跟踪进度的学习助手。

它会先确认学习目标，再寻找资料、设计课程和练习，并将过程保存在文件中。常见产出包括 MISSION.md、RESOURCES.md 和 lessons/ 目录。

**适合什么时候用：**需要系统学习一个新框架、概念或工具，而不是只想得到一个简短答案时。

**主要产出：**学习目标、资源清单、课程和练习记录。

调用示例：

1
/teach 我想系统学习 Spring Security，并最终为微人事系统实现角色权限

1. create-spring-boot-java-project：创建项目骨架#

**作用：**从零生成 Spring Boot 项目的基础结构、Maven 配置、依赖和开发环境文件。

它适合项目刚开始时使用，可以根据技术约束生成 Web、数据访问、校验、测试、接口文档等依赖，并协助准备 Docker Compose 和 application 配置。它解决的是“从空目录搭好地基”的问题，不负责实现具体业务。

**使用时机：**项目初始化阶段。

**主要产出：**可编译的 Spring Boot 项目、依赖配置、基础配置文件和 README。

2. java-springboot：Spring Boot 编码规范#

**作用：**像一位 Spring Boot 编码监督员，让 AI 按统一的工程规范生成和修改 Java 代码。

它重点约束：

• 按业务功能组织目录，而不是把所有 Controller、Service、Repository 混在一起。
• 使用构造器注入和 private final 依赖，避免字段注入。
• Controller 使用 DTO 和参数校验，不直接暴露 Entity。
• Service 层负责事务，Repository 层只负责数据访问。
• 使用统一异常处理、SLF4J 日志和环境变量配置敏感信息。
• 密码使用 BCrypt，单元测试和集成测试覆盖关键行为。

**使用时机：**每次新增或修改 Spring Boot 代码时。

**主要产出：**结构统一、边界清晰、便于维护和测试的 Spring Boot 代码。

3. springboot-patterns：Spring Boot 架构模式#

**作用：**为具体业务提供生产级的架构和实现模式。

它可以帮助 AI 设计 REST API、分页查询、DTO 映射、事务边界、统一错误响应、缓存、异步任务、重试、限流和监控等能力。它解决的是“功能能写出来，但怎样写得更像生产代码”的问题。

**使用时机：**设计员工、部门、考勤等业务模块，或需要处理缓存、并发和外部服务调用时。

**主要产出：**Controller、Service、Repository、DTO、异常处理和基础设施代码的设计建议。

三个 Spring Skill 的关系可以概括为：

1
create-spring-boot-java-project  ->  搭建项目骨架
2
java-springboot                  ->  约束编码规范
3
springboot-patterns              ->  选择架构模式

例如实现“员工入职”时，可以这样组合调用：

1
请使用 /tdd 实现员工入职功能，同时遵循 java-springboot 和 springboot-patterns 的规范。
2
如果当前项目尚未创建，请先使用 create-spring-boot-java-project 生成项目骨架，不要直接生成业务代码。

第一步：安装与初始化#

在准备创建项目的目录中打开终端，执行：

1
mkdir micro-hr
2
cd micro-hr
3
git init
4
npx skills@latest add mattpocock/skills
5
npx skills@latest add github/awesome-copilot@create-spring-boot-java-project
6
npx skills@latest add github/awesome-copilot@java-springboot
7
npx skills@latest add affaan-m/everything-claude-code@springboot-patterns

安装程序会让你选择要安装的 Skill 和目标 AI 编程工具。务必选中：

1
/setup-matt-pocock-skills

安装完成后，在 Claude Code、Codex 或其他支持的 AI 编程工具中运行：

1
/setup-matt-pocock-skills

AI 会询问：

• 使用哪种 Issue 追踪器：GitHub、Linear 或本地 Markdown 文件。
• Triage 使用什么标签。
• 文档存放在哪里。
• 项目规则保存到哪个文件。

个人项目可以选择本地 Markdown 文件，文档目录使用默认的 docs/。初始化完成后，后续 Skill 会自动沿用这些约定。

第二步：用 /grill-with-docs 把需求问清楚#

此时只有一个模糊想法：“我要做一个微人事系统。”

在对话中输入：

1
/grill-with-docs 我要做一个微人事系统，包含员工管理、部门管理和考勤记录

AI 会开始一次只问一个问题，例如：

• 员工入职需要审批，还是由 HR 直接录入？
• 一个员工是否只能属于一个部门？
• 部门之间是否存在上下级关系？
• 考勤按天记录，还是保存每次打卡时间？
• 员工能否申请补卡？
• 系统需要哪些角色和权限？

每个问题都会附带推荐答案。你只需要逐个确认、修改或补充，不需要一次写出完整需求。

讨论结束后，重点检查两个产出：

CONTEXT.md

记录项目中的共享语言，例如：

ADR

只记录重要且难以逆转的决定，例如“部门采用树形结构”“首版使用角色权限模型”。

从这一刻起，后续会话都应该先读取 CONTEXT.md。这样你只要说“实现补卡”，AI 就知道它在当前项目中的准确含义。

第三步：用 /to-prd 生成产品需求文档#

需求讨论完成后，输入：

1
/to-prd

AI 会把刚才确认的内容整理成一份 PRD，并保存到初始化时配置的文档目录或 Issue 追踪器中。

你需要重点检查：

• 是否只包含已经确认的功能。
• 员工、HR、部门负责人分别能做什么。
• 员工入职、部门管理和考勤记录的主流程是否完整。
• 异常情况和权限边界是否写清。
• 每个功能是否有可以验证的验收标准。

这一步的价值是把对话中的共识固化下来。即使换一个新会话，也不需要从头解释产品目标。

第四步：用 /to-issues 拆解任务#

PRD 确认后，输入：

1
/to-issues

AI 会把 PRD 拆成可以独立完成的垂直切片，例如：

1
Issue #1：员工入职
2
- 后端：创建员工接口
3
- 前端：员工入职表单
4
- 数据：保存员工和所属部门
5
- 验收：成功创建员工；缺少姓名时报错；部门不存在时报错
6

7
Issue #2：部门创建
8
- 后端：创建和查询部门接口
9
- 前端：部门管理页面
10
- 数据：保存部门及上下级关系
11
- 验收：部门名称必填；不允许形成循环层级
12

13
Issue #3：员工打卡
14
- 后端：上班和下班打卡接口
15
- 前端：打卡按钮和当天状态
16
- 数据：保存打卡时间
17
- 验收：同一时段不能重复打卡
18

19
Issue #4：考勤查询
20
- 后端：按员工和日期查询
21
- 前端：考勤列表
22
- 数据：分页读取考勤记录
23
- 验收：员工只能查看自己，HR 可以查看全部

每个 Issue 都包含一个完整的用户功能，而不是把工作拆成“全部前端”“全部后端”“全部数据库”。

这一步结束后，先选择 Issue #1，不要让 AI 同时实现四个 Issue。

在开始实现 Issue 之前，先用 create-spring-boot-java-project 创建项目骨架：

1
请使用 create-spring-boot-java-project 创建 micro-hr 的 Spring Boot 项目骨架。
2
使用 Java 21 和 Maven，加入 Web、Validation、JPA、PostgreSQL、Flyway、Security 和测试依赖。
3
只创建项目结构和基础配置，不要生成员工、部门或考勤业务代码。
4
完成后运行测试，报告结果。

骨架生成后，再让 java-springboot 和 springboot-patterns 检查一次：

1
请读取 docs/CONTEXT.md。使用 java-springboot 和 springboot-patterns 审查刚生成的项目骨架。
2
重点检查按业务功能分包、构造器注入、DTO、统一异常、事务边界、敏感配置和测试配置。
3
先列出问题，确认后再修改。

这样，三个 Spring Skill 就分别参与了“创建骨架、约束编码、提供架构模式”三个环节。

第五步：用 /tdd 逐个实现 Issue#

打开一个新会话，让 AI 读取 CONTEXT.md、PRD 和 Issue #1，然后输入：

1
/tdd 实现 Issue #1：员工入职

AI 会按照红、绿、重构的顺序逐步实现。

第一个循环：创建员工成功

1
红：写测试“输入合法员工信息后，创建成功”
2
绿：写刚好能让测试通过的最少代码
3
重构：清理命名和重复代码，保持测试通过

第二个循环：姓名不能为空

1
红：写测试“创建员工时缺少姓名，返回错误”
2
绿：增加姓名校验
3
重构：整理校验逻辑，保持测试通过

第三个循环：部门必须存在

1
红：写测试“创建员工时部门不存在，返回错误”
2
绿：增加部门存在性检查
3
重构：清理实现，保持全部测试通过

AI 不会一口气写完所有测试和业务代码，而是完成一个可验证的小行为后再进入下一个。Issue #1 全部验收标准通过后，再运行：

1
/code-review 审查 Issue #1 的全部改动

解决 Review 中有证据的问题，运行完整测试，然后再开始 Issue #2。后续部门创建、员工打卡和考勤查询都重复同样的流程。

开发中遇到 Bug 怎么办#

假设员工入职时出现错误：页面提示“部门不存在”，但数据库中明明有这个部门。

输入：

1
/diagnosing-bugs 员工入职时报错“部门不存在”，但该部门已经存在

AI 会依次完成：

1. 用失败测试、接口请求或页面操作稳定复现。
2. 缩小到最小重现场景。
3. 提出可能原因。
4. 通过日志或实验验证假设。
5. 实施最小修复。
6. 补回归测试。

在复现成功之前，不允许直接猜原因和修改代码。这能避免 AI 在多个文件中反复试错。

定期给代码做一次体检#

完成几个 Issue 后，运行：

1
/improve-codebase-architecture

AI 会扫描代码库，找出重复逻辑、职责过大的模块、混乱的依赖和可以简化的接口。根据 Skill 版本不同，它可能生成带图表的 HTML 报告。

先阅读报告，再选择一项值得实施的建议。不要让 AI 根据整份报告一次性重构所有代码。

对话太长时及时交接#

如果一个会话已经积累了大量内容，运行：

1
/handoff

让 AI 生成交接文档。新会话先读取这份文档，再继续下一个 Issue。这样可以保持上下文清晰，也不会丢失已经确认的决策和测试结果。

完整工作流一览#

1
/setup-matt-pocock-skills
2
            |
3
            v
4
/grill-with-docs -> /to-prd -> /to-issues -> create-spring-boot-java-project
5
        |              |           |                    |
6
        v              v           v                    v
7
 CONTEXT.md + ADR      PRD      垂直切片       /tdd + java-springboot
8
                                                     + springboot-patterns
9
                                                          |
10
                                                          v
11
                                                   可运行代码
12
                                                          |
13
                                                          v
14
                                                   /code-review
15
                                               |
16
                            +------------------+------------------+
17
                            |                                     |
18
                            v                                     v
19
                   /diagnosing-bugs                /improve-codebase-architecture
20
                            |
21
                            v
22
                        /handoff

这套流程的核心很简单：先让 AI 把需求问清楚，再把共识变成文档和任务，最后按小步测试循环逐个实现。

如果需求很小而且已经非常明确，可以跳过 /to-prd，直接使用 /to-issues；如果只是修改一个边界清楚的小功能，也可以直接从 /tdd 开始。Skill 是为了减少沟通和返工，不是为了给每个任务增加不必要的步骤。

现在，你可以在自己的项目目录中输入：

1
/grill-with-docs 我要做一个微人事系统，包含员工管理、部门管理和考勤记录

从第一个问题开始，让 AI 按工程流程与你一起把项目真正做出来。