Matt Pocock Skills Deep Dive — Claude Code Skill Architecture
Codex 核验（2026-10-09）：Claude skills 文档中的
disable-model-invocation: true让技能在用户调用前不进入模型目录上下文，调用后完整指令仍消耗上下文。技能可编排子 agent，不能仅凭 SKILL.md 格式断言没有多 agent。星标数属于具体仓库的原日期快照，不是作者个人账号的通用指标。
来源: github.com/mattpocock/skills | 研究日期: 2026-07-13
概述
Matt Pocock（133K+ GitHub ⭐）是 TypeScript 领域的顶级教育者。他维护了一个专门的 Claude Code / AI Agent Skills 仓库，包含 17+ 技能，分为 Engineering 和 Productivity 两类。这不是普通的配置合集——而是一套经过实战检验的技能工程哲学。
每个 skill 通过 npx skills@latest add mattpocock/skills 安装，由 skills.sh 工具链管理。安装后会生成 /setup-matt-pocock-skills 初始化命令（配置 issue tracker、triage labels、doc 存储位置）。
技能架构
调用模型（核心概念）
Matt 将技能分为两种调用方式：
| 类型 | 描述 | 触发方式 | 上下文成本 |
|---|---|---|---|
| User-invoked | 仅通过 /command 手动触发 | /grill-me | ❌ 零 context load |
| Model-invoked | Agent 可自动触发 + 手动可用 | 自动匹配 | 🟡 永久 context load（description 常驻） |
Router skill：当 user-invoked skills 太多时，用一个 /ask-matt 技能做路由。
Skill 文件结构
每个 skill 是一个目录，核心文件：
skills/engineering/tdd/SKILL.md # 主文件（YAML frontmatter + markdown body）
skills/engineering/tdd/GLOSSARY.md # 可选：术语表（references 披露）
skills/engineering/tdd/templates/ # 可选：模板文件
Frontmatter 格式：
---
name: tdd
description: Test-driven development with a red-green-refactor loop.
disable-model-invocation: true # user-invoked 的关键
---关键技能清单
Engineering（工程类）
| Skill | 类型 | 用途 |
|---|---|---|
/grill-with-docs | User | 最受欢迎 — 深度采访计划/设计，同时生成 ADR 和术语表 |
/grill-me | User | 轻量版 grilling，不生成文档 |
/triage | User | Issue 状态机流转 |
/improve-codebase-architecture | User | 扫描代码库 → HTML 报告 → 逐项重构 |
/to-spec | User | 对话 → 规范文档 → 同步到 issue tracker |
/to-tickets | User | 计划 → tracer bullet tickets（含 blocking edges） |
/implement | User | 按 spec/tickets 构建，驱动 TDD + code review |
/wayfinder | User | 规划超大型工作为可探索的 ticket 地图 |
/setup-matt-pocock-skills | User | 初始化配置 |
tdd | Model | 红-绿-重构循环 |
diagnosing-bugs | Model | 复现→最小化→假设→仪表→修复→回归测试 |
research | Model | 查询高信任度一手来源，生成引用 Markdown |
code-review | Model | 双轴并行审查：代码标准 + spec 符合度 |
domain-modeling | Model | 主动构建和完善领域模型 |
codebase-design | Model | 深度模块设计原则 |
prototype | Model | 构建一次性原型验证设计 |
Productivity（生产力类）
| Skill | 类型 | 用途 |
|---|---|---|
/grill-me | User | 轻量级深度采访 |
/handoff | User | 对话压缩为交接文档 |
/teach | User | 多 session 教学 |
/writing-great-skills | User | 元技能 — 编写技能的原则和词汇表 |
grilling | Model | grilling 循环引擎（被 grill-me / grill-with-docs 调用） |
技能设计哲学（writing-great-skills 核心提炼）
根本原则：Predictability（可预测性）
技能的价值在于让 Agent 每次运行都采用相同的过程（不是相同的输出）。同一个技能每次执行的行为模式应该一致。
核心概念
| 概念 | 解释 |
|---|---|
| Leading Word (Leitwort) | 一个模型预训练中已有的简洁概念（如 tracer bullets, fog of war），用最少 token 锚定行为。比自己定义新词省 token |
| Completion Criterion | 步骤完成的检查条件。必须 checkable（可判断完成/未完成）+ exhaustive（“每个修改的模型都已说明”而非”产生变更列表”） |
| Legwork | Agent 在步骤内幕后的工作——读文件、查代码、挖掘信息。通过 completion criterion 的 demand 控制 |
| Progressive Disclosure | 将 reference 推送到 context pointer 后面，保持顶层简洁 |
| No-op Test | 每行都要通过：去掉这行，Agent 行为会变吗？不会 → 删掉 |
信息层级（Information Hierarchy）
1. In-skill step (SKILL.md) ← 核心操作步骤
2. In-skill reference (SKILL.md) ← 按需查阅的定义/规则
3. External reference (文件) ← 通过 context pointer 按需加载
故障模式
| 模式 | 含义 | 修正 |
|---|---|---|
| Premature Completion | Agent 没做完就跳到下一步 | 收紧 completion criterion；隐藏后续 steps |
| Duplication | 同一含义出现多次 | 提取为 Single Source of Truth |
| Sediment | 旧内容沉积不清理 | 定期 pruning 检查 |
| Sprawl | 技能太长 | Progressive disclosure → 分层 |
| No-op | 说了等于没说 | 删除该行 |
| Negation | 用否定句指导（“不要写冗长注释”） | 改写成肯定句（“写一行注释”） |
调优策略
- Granularity（粒度）：模型调用技能多 → context load 高；用户调用技能多 → cognitive load 高
- Branching（分支）：不同运行走不同路径时，用 context pointer 披露分支专属内容
- Co-location（局部聚集）：相关概念放在同一个 heading 下
- Pruning（修剪）：定期检查每行的 relevance 和 no-op 状态
我们可以直接借鉴的实践
1️⃣ Skill 调用模型
将我们的 skill 系统也分为两类：
- User-invoked：用户手动触发的复杂流程（如
/research,/grill） - Model-invoked：Agent 自动调用的原子技能（如
code-review,diagnosing-bugs）
当前我们的 skill 系统已经分 category，但没有 invocation 维度。
2️⃣ Completion Criterion
每条 sticky note 应该加 done_when 字段——明确什么条件下算完成。这是 Loop-Engineering 护栏的核心。
3️⃣ Leading Words
用模型预训练中已有的概念（如 “red-green-refactor”、“tracer bullet”）锚定行为模式，减少 token 开销。
4️⃣ Writing-Great-Skills 元技能
他的 writing-great-skills 本身就是个 Skill，可以被加载来指导其他技能编写。我们也可以做一个类似的元技能或加到 skill-factory 里。
5️⃣ Pruning Discipline
定期检查技能文件的 no-op、sediment、duplication——这是我们的 skill-factory 可以做的事情。
6️⃣ Skill 热安装
npx skills@latest add + skills.sh 这套工具链很有意思——类似我们通过 gbrain 管理技能，但实现了跨项目复用。
7️⃣ 信息层级
将技能中的 reference（大量规则/定义）通过 context pointer 外链，减少主文件 token 开销。
与 Yunlu 技能系统的对比
| 维度 | Matt Pocock | Yunlu |
|---|---|---|
| 存储 | skills.sh + GitHub | gbrain + Hermes profile |
| 安装 | npx skills@latest add | skill_manage / skill factory |
| 调用 | /command slash 命令 | skill_manage / skill_view |
| 编写 | SKILL.md（YAML frontmatter） | SKILL.md（YAML frontmatter）✅ 相同格式 |
| 分类 | Engineering / Productivity | 按 category 分组 |
| 元技能 | writing-great-skills | skill-factory（更偏生成而不是编写原则） |
| 热加载 | skills.sh CLI | gbrain MCP + skill_view |
| 多 Agent | ❌ 单 Agent | ✅ 多 Agent（Manas/Alaya/Anchor/Mano） |
关键差距：他的 invocation 模型（user/model invoked）增加了一个维度，我们也应该加上。同时他的 writing-great-skills 包含的编写原则（leading words、no-op test）比我们的 skill-factory 更深入。