从 Matt Pocock 的 SKILLs 项目学习工程经验与构建技巧

本计划面向 SKILL 初级使用者，基于对 Matt Pocock SKILLs 项目仓库的深度探索分析，提炼可学习、可实践的工程模式和构建技巧。

一、项目概览：Matt Pocock 的 SKILLs 是什么样的项目？

二、核心工程经验：八个可以从该项目中学到的关键模式

模式 1：六个桶分类法 —— 技能的生命周期管理

Matt Pocock 用 6 个桶目录 来管理技能的"生命周期"：

关键洞察：桶分类法让技能管理变得清晰：

• 渐进式发布：技能先放在 in-progress/ 草稿，成熟后移到正式桶
• 废弃有去处：不用的技能不删除，移到 deprecated/ 留作参考
• 公私分离：个人技能不影响团队

你需要做的：开始构建时，先只使用 engineering/ 和 productivity/ 两个桶，以及 in-progress/ 作为草稿区。

模式 2：三层注册机制 —— 技能发现系统

Matt Pocock 项目使用三层结构让 Agent 发现技能：

第一层：AGENTS.md（或 workspace rules）
  定义：skills/ 下的组织规则
  内容：桶的划分方式、注册要求

第二层：.claude-plugin/plugin.json
  定义：哪些技能被加载给 Agent
  内容：技能路径列表（相对于插件根目录）

第三层：README.md + skills/<bucket>/README.md
  定义：人类可读的技能目录
  内容：每个技能的名称（链接到 SKILL.md）+ 一行描述

关键洞察：

• .claude-plugin/plugin.json 是 Agent 实际加载技能的清单
• README.md 是给人类读者查看的完整目录
• Bucket README 是给在该领域查找工具的快速索引
• 三者的同步规则：engineering/、productivity/、misc/ 下的技能必须同时在 plugin.json 和 README 中注册

你需要做的：

• 在你的项目中创建 .claude-plugin/plugin.json
• 维护 README.md 的技能列表
• 用 AGENTS.md 或 workspace rules 定义你仓库的组织规则

模式 3：SKILL.md 的标准模板 —— 每个技能的基本结构

所有 SKILL.md 都遵循统一的结构：

---
name: <技能名>
description: "<功能描述> Use when <触发条件>."
---

# <标题>

... 内容 ...

YAML frontmatter（元数据区）：

• name: 技能名称（必须）
• description: 描述（最重要的字段，决定 Agent 何时自动触发该技能）

Description 的黄金公式（来自 write-a-skill 的规范）：

<做什么的>. Use when <触发场景>.

具体例子：

规则：

• 第一句：现在时第三人称，说明"什么能力"
• 第二句：以 "Use when" 开头，列出具体的触发词和上下文
• 最多 1024 字符

你需要做的：为每个技能编写清晰的 description。花时间打磨这个字段——它决定了 Agent 能否在正确的时机调用你的技能。

模式 4：渐进式信息披露 —— SKILL.md 只做决策路由

这是 Matt Pocock 项目中最核心的设计模式。

核心原则：SKILL.md 只包含核心流程和决策点，深入细节拆分到独立的引用文件中。

prototype/
├── SKILL.md      ← 决策路由器：选择 LOGIC 分支还是 UI 分支
├── LOGIC.md      ← 逻辑原型的详细实现指南
└── UI.md         ← UI 原型的详细实现指南

tdd/
├── SKILL.md           ← 核心流程：红绿重构循环
├── tests.md           ← 好测试 vs 坏测试示例
├── mocking.md         ← Mock 指南
├── deep-modules.md    ← 深模块概念
├── interface-design.md← 可测试性接口设计
└── refactoring.md     ← 重构候选清单

diagnose/
├── SKILL.md             ← 5 阶段调试流程
└── scripts/
    └── hitl-loop.template.sh  ← 人机交互循环模板

何时拆分（write-a-skill 给出的量化阈值）：

• SKILL.md 超过 100 行 → 考虑拆分
• 全部内容超过 500 行 → 必须拆分
• 引用深度限制为 一层（SKILL.md → 引用文件），不出现更深嵌套

你能学到的：

• 不要试图把所有内容塞进一个文件
• 用 SKILL.md 做"导航员"，引用文件做"执行者"
• 用量化标准来判断何时拆分，而不是凭感觉

模式 5：流程的严谨性 —— 门控阶段 + Checklist

Matt Pocock 的复杂技能都使用阶段式流程，每个阶段有明确的进入/退出条件。

以 diagnose 为例：

Phase 1: REPRODUCE    → 条件：必须先稳定复现
Phase 2: MINIMISE     → 条件：必须有一个最小的复现
Phase 3: HYPOTHESISE  → 条件：必须有可验证的假设
Phase 4: INSTRUMENT   → 条件：确认测量方式
Phase 5: FIX          → 条件：确认根因
Phase 6: VERIFY       → 有 checklist 验证修复

每个阶段都有 Do not proceed to Phase N until... 的门控条件。

模式要点：

• 阶段编号：用 Phase 1-6、Step 1-5 等明确的编号
• 门控条件：写清楚"什么情况下才能进入下一阶段"
• Checklist：关键阶段用 - [ ] 列出检查项
• 反模式（Anti-pattern）：指出常见的错误做法

适用于你的：

• 简单技能（10-30 行）不需要阶段
• 中等技能（30-80 行）可以用 3-5 个 Step
• 复杂技能（80-120+ 行）用 Phase + 门控条件

模式 6：元技能 write-a-skill —— 自我描述的质量控制

write-a-skill 是 Matt Pocock 项目中最特别的技能——它是一个关于如何创建技能的技能（元技能）。

它包含的内容：

1. 创建技能的流程（收集需求 → 起草 → 审查）
2. SKILL.md 模板（YAML frontmatter + 章节结构）
3. Description 字段的详细写法规范（好例子 vs 坏例子）
4. 何时拆分文件的量化标准（100 行 / 500 行阈值）
5. Review Checklist（质量检查清单）

关键洞察：元技能的存在意味着：

• 一致性：所有技能遵循相同的结构和质量标准
• 可教学性：新手可以通过运行这个技能学会如何创建技能
• 可扩展性：当标准变化时，只需要更新这一个技能

你需要做的：在你的项目中尽早创建你的 write-a-skill（或类似的元技能）。这是保证技能质量最有效的手段。

模式 7：CONTEXT.md + ADR 的领域语言系统

Matt Pocock 项目用两个文档构建了一套共享语言系统：

CONTEXT.md 的规则（来自 CONTEXT-FORMAT.md）：

• 每个术语有定义 + Avoid 列表（明确禁止使用的同义词）
• 要有主见：选择最佳词汇，其他列为 Avoid
• 保持精炼：最多一两句话
• 只包含项目特有的术语，不包含通用编程概念

ADR 的规则（来自 ADR-FORMAT.md）：

• 极简主义：只有标题和 1-3 句话
• 三个条件（全部满足才创建 ADR）：
  1. 难以逆转
  2. 脱离上下文会令人惊讶
  3. 是真正权衡的结果
• 编号规则：0001-xxx.md、0002-xxx.md

你能学到的：

• 不要等到项目做大了才建立术语表
• ADR 不需要冗长的模板——1-3 句话足够记录一个决策
• 关键是有"Avoid"列表（告诉 Agent 不要用什么词）

模式 8：可组合的脚本基础设施

Matt Pocock 在 scripts/ 下提供了三个辅助脚本：

设计特点：

• 安全守卫：链接脚本会检查目标目录是否指向本仓库，防止污染仓库
• Windows 兼容：JS 脚本使用 junction 类型的符号链接，在 Windows 上无需管理员权限
• 幂等性：多次运行结果一致

你能学到的：

• 脚本用来解决基础设施问题（安装、列举），不解决业务问题
• 用 Node.js（而非 Bash）做跨平台支持更好
• 添加安全守卫防止误操作

三、构建你自己的 SKILLs 系统：渐进式学习路径

以下是推荐的学习与实践路线，分为四个阶段：

第一阶段：建立基础结构（1-2 天）

目标：搭建项目的骨架结构，建立第一个可用的技能。

1. 创建项目目录结构

   your-skills/
   ├── .claude-plugin/
   │   └── plugin.json
   ├── skills/
   │   ├── engineering/     # 工程技能
   │   ├── productivity/    # 生产力技能
   │   └── in-progress/     # 草稿技能
   ├── AGENTS.md            # 组织规则
   ├── CONTEXT.md           # 领域术语
   └── README.md            # 技能目录
   

2. 编写 AGENTS.md

   • 参考 Matt 的 AGENTS.md，定义你仓库的规则
   • 明确 bucket 分类、注册要求、README 链接规范

3. 创建第一个简单技能

   • 从 caveman 级别的简单指令型技能开始
   • 练习：写一个 format-output 技能，要求 Agent 输出时使用特定格式

4. 注册并测试

   • 在 plugin.json 中添加路径
   • 在 README.md 中添加条目
   • 验证 Agent 能否触发

第二阶段：学习中等复杂度技能（3-5 天）

目标：掌握流程型技能的编写方法。

1. 模仿 to-issues 的技能结构

   • 学习：线性 5 步流程的写法
   • 实践：写一个 create-api-skill，引导 Agent 一步步创建 API

2. 练习添加 XML 标签块

   • 使用 <rules>、<template> 等标签包裹关键指令
   • 这既清晰又便于解析

3. 练习使用 Checklist

   • 在技能的关键步骤添加 - [ ] 检查项

4. 学习编写 description 字段

   • 反复修改，直到描述清晰、触发条件明确

第三阶段：掌握复杂技能模式（1-2 周）

目标：学习文件拆分、分支决策、门控阶段等高级模式。

1. 练习渐进式信息披露

   • 将技能内容拆分为 SKILL.md + 引用文件
   • 用 write-a-skill 中提到的 100 行 / 500 行阈值检查

2. 学习分支路由模式

   • 参考 prototype 的 LOGIC/UI 分支
   • 实践：写一个 deploy-skill，根据环境（生产/测试）走不同分支

3. 学习门控阶段模式

   • 参考 diagnose 的 Phase 门控
   • 每个阶段有明确的进入/退出条件

4. 建立 CONTEXT.md 和 ADR

   • 为你的项目定义 3-5 个核心术语
   • 记录 1 个架构决策作为 ADR

第四阶段：元技能与自我进化（持续）

目标：创建元技能，让系统能够自我改进。

1. 创建你的 write-a-skill

   • 包含 SKILL.md 模板
   • 包含 description 写法规范
   • 包含 Review Checklist

2. 定期审查和重构

   • 将 in-progress/ 中的技能按标准审查
   • 将不再使用的技能移到 deprecated/
   • 更新 CONTEXT.md 中的术语

3. 建立个人最佳实践

   • 在 CONTEXT.md 中添加你的项目中特有的术语
   • 记录你的 ADR

四、初学者最容易踩的坑

五、Matt Pocock 项目的核心哲学

1. 越小越好：每个技能只做一件事。如果一个技能需要做两件事，拆成两个技能。

2. 先用再优化：先在 in-progress/ 中快速创建一个可用版本，再逐步完善。

3. 一致性比完美更重要：所有技能遵循相同的结构、相同的前置条件格式、相同的反模式写法。用户（和 Agent）不需要重新学习。

4. 写给人看，也写给 AI 看：README 是给人看的目录，SKILL.md 是给 AI 读的指令。plugin.json 是给系统用的注册表。三者各司其职。

5. 渐进式信息披露：不在 SKILL.md 中一次展示所有信息。只展示当前阶段需要的，更深的内容在引用文件中。

6. 量化决策标准：不要用"太多"或"太大"这样模糊的词。用"100 行"、"500 行"这样明确的数字。

7. 术语即约束：CONTEXT.md 不只是词汇表，更是"什么不准说"的约束列表。Agent 输出错误术语时，是 CONTEXT.md 需要更新。

六、推荐的动手练习

做完以下练习，你会对 SKILL 构建有扎实的理解：

1. 练习一（★☆☆）：创建一个 20 行以内的指令型技能，如 terse-mode（要求 Agent 每次回复不超过 3 句话）
2. 练习二（★★☆）：创建一个 50 行左右的流程型技能，包含 3 个步骤和 1 个 checklist
3. 练习三（★★★）：创建一个有引用文件的技能，SKILL.md 做路由，2 个引用文件做细节
4. 练习四（★★★★）：创建你的 write-a-skill 元技能，包含模板和 review checklist
5. 练习五（★★★★★）：将现有的 1-2 个技能重构，使其遵循 Matt Pocock 的工程模式

七、验证清单

完成本计划的学习后，你可以用以下清单检查自己的掌握程度：

• 我能解释 6 个 bucket 的分类方式及其用途
• 我能写出符合规范的 SKILL.md description 字段
• 我知道 SKILL.md 超过 100 行时应该做什么
• 我能在技能中使用门控阶段和 checklist
• 我能在技能中添加反模式和好/坏例子对比
• 我能在 CONTEXT.md 中定义术语和 Avoid 列表
• 我知道什么时候该创建 ADR
• 我能维护 plugin.json 和 README.md 的同步
• 我理解渐进式信息披露的设计原则
• 我能创建和使用元技能

八、参考资源