Hotdry.

Article

SKILL.md DSL 与 Shell 片段生成：mattpocock/skills 的上下文工程实践

解析基于 .claude 目录的 SKILL.md 技能格式 DSL，给出 Shell 片段动态生成与上下文工程的工作流参数，覆盖 diagnose 六阶段调试循环与 caveman 令牌压缩模式。

2026-05-16ai-systems

Matt Pocock 的 mattpocock/skills 是一个以 .claude 目录为载体的技能集合，当前已积累 85k GitHub Stars。与 Superpowers 的代理框架、Anthropic Skills 的分层设计不同，mattpocock/skills 的核心定位是「真实工程师的技能」—— 拒绝 vibe coding，通过可组合的小粒度技能实现上下文对齐、反馈循环压缩与 token 消耗优化。其技能以 SKILL.md 文件为载体，本质上是一套文本 DSL，用于约束 AI 行为模式、生成特定上下文的 Shell 片段与工程决策模板。

SKILL.md 格式规范：技能 DSL 的结构设计

每个技能在 .claude/skills/<skill-name>/SKILL.md 中定义，文件头包含结构化元数据：

name        <skill-id>          # 斜杠命令触发符，如 diagnose
description <功能描述>           # 触发场景描述与核心行为

描述字段使用自然语言声明触发条件，AI 依据此字段自动激活技能。例如 diagnose 的描述为："Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says 'diagnose this' / 'debug this', reports a bug..."

正文则采用分层指令结构：第一层是通用原则（如「建立反馈循环」），后续层给出具体策略列表与执行约束。这种 frontmatter + 分层指令的设计，使技能既能作为模式匹配触发器，又能在激活后提供可执行的详细指南。

技能的组织遵循三分类原则：Engineering（代码工作，如 diagnose、tdd、grill-with-docs）、Productivity（通用工作流，如 caveman、handoff、write-a-skill）、Misc（辅助工具，如 git-guardrails、migrate-to-shoehorn）。这种分类决定了技能的调用层级与依赖关系。

diagnose 技能：六阶段调试循环与反馈环构建

diagnose 是 mattpocock/skills 中最核心的技能之一，完整实现了一个结构化调试循环。其核心洞察是：「如果没有快速、确定性、可由 Agent 执行的 pass/fail 信号，无论多少凝视代码都无济于事」。

反馈环构建策略（Phase 1）

Phase 1 的目标是构建一个可靠的反馈循环。diagnose 给出了优先级递减的构建策略清单：

  1. 故障点接缝处的失败测试（单元、集成、e2e）
  2. 针对运行中 dev server 的 curl/HTTP 脚本
  3. 带已知良好快照的 CLI 调用 fixture
  4. Playwright/Puppeteer 无头浏览器脚本
  5. 捕获的网络请求 / Payload / 事件日志回放
  6. 一次性测试工具（启动系统的最小子集）
  7. 属性 / 模糊测试循环（1000 次随机输入）
  8. 二分法测试工具（自动化状态遍历）
  9. 差分循环（旧版本 vs 新版本输出对比）
  10. HITL bash 脚本（人类点击驱动，最后手段）

关键参数：反馈循环的目标是 2 秒内完成、确定性执行、强信号断言。文档指出「30 秒的 flaky 循环几乎没有价值；2 秒的确定性循环是调试超能力」。这直接转化为工程实践中的性能基准。

迭代反馈环本身也是产品：「能更快吗？（缓存 setup，跳过无关初始化，缩小测试范围）」「信号能更锐利吗？（断言具体症状而非『没崩溃』）」「能更确定性吗？（固定时间、种子 RNG、隔离文件系统）」

六阶段执行流程

Phase 2 是复现：运行循环，确认产生的失败模式与用户描述一致，且可跨多次运行复现。

Phase 3 是假设生成：必须生成 3–5 个排序假设后再测试任何一个，单一假设生成会导致锚定效应。每个假设必须是可证伪的，格式为「如果 [假设] 是原因，那么 [操作] 会使 bug 消失 / 恶化」。生成后须向用户展示排序列表，利用用户的领域知识重新排序。

Phase 4 是仪器化：每个探针必须对应 Phase 3 的具体预测。工具优先级是调试器 / REPL > 针对性日志 > 绝不「日志一切然后 grep」。每个调试日志须带唯一前缀如 [DEBUG-a4f2]，清理时只需 grep [DEBUG- 即可移除全部临时日志。

Phase 5 是修复与回归测试：修复前先写回归测试，但仅在「正确的接缝」存在时才写。正确接缝指测试能真实复现 bug 发生的调用链路模式，而非浅层单调用方测试制造虚假信心。若正确接缝不存在，代码库架构本身就在阻止 bug 被锁定，这本身就是发现。

Phase 6 是清理与复盘：原始复现不再出现、所有 [DEBUG-...] 已移除、临时原型已删除、正确假设已在 commit/PR 消息中说明。然后问「什么能阻止这个 bug？」若答案是架构变更，则将其传递给 /improve-codebase-architecture 技能，且建议在修复进入后再提出而非之前 —— 因为此时拥有更多信息。

caveman 技能：Token 压缩与 Shell 片段模式

caveman 是 mattpocock/skills 中的令牌压缩技能，目标是削减约 75% 的 token 使用量，同时保持技术准确性。其核心机制是系统性地移除语言冗余。

移除规则体系

caveman 定义了明确的移除规则：

  • 文章移除：a、an、the 全部删除
  • 填充词移除：just、really、basically、actually、simply
  • 客套语移除：sure、certainly、of course、happy to
  • 修饰词移除：hedging 表达
  • 长词替换：big 替代 extensive，fix 替代「implement a solution for」
  • 常用术语缩写：DB/auth/config/req/res/fn/impl
  • 连词精简：使用箭头表达因果（X -> Y）
  • 句式压缩：单字足够时用单字

保留规则：技术术语保持精确、代码块原样不动、错误信息精确引用。

模式与自动豁免

模式：[thing] [action] [reason]. [next step]. 例如：「Bug in auth middleware. Token expiry check use < not <=. Fix:」而非「Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by...」

自动豁免条款：遇到安全警告、不可逆操作确认、多步骤序列（片段顺序易误解）、用户要求澄清时，暂时退出 caveman 模式，完成后恢复。例如危险操作前的警告会使用正常模式，但之后仍返回 caveman。

从 Shell 片段生成角度看，caveman 提供了一套文本压缩规则集，可用于预处理 AI 响应或作为提示工程中的输出约束模板。

.claude 目录的上下文工程架构

mattpocock/skills 的安装通过 npx skills@latest add mattpocock/skills 完成，安装过程会执行 /setup-matt-pocock-skills 技能，该技能询问三个配置维度：

  1. Issue Tracker 选择：GitHub、Linear 或本地文件
  2. Triage 标签词汇：用于 /triage 技能的标签体系
  3. 文档保存路径：技能创建的文档存放位置

这些配置形成每个仓库的 .claude/skills/ 目录结构，技能之间通过共享配置实现协同。例如 /grill-with-docs 会读取 issue tracker 配置、标签词汇与文档路径，以生成符合项目规范的 PRD 与 ADR。

关键工程参数：

  • 技能以 /<skill-name> 斜杠命令形式触发
  • 技能间存在依赖关系：/improve-codebase-architecture 被 diagnose 的 Phase 6 调用
  • CONTEXT.md 作为项目术语共享文档，与 docs/adr/ 中的架构决策记录（ADR）共同支撑技能上下文
  • 每次会话复用 CONTEXT.md 中的领域语言，减少 token 消耗与理解偏差

与其他 AI 技能的差异化定位

mattpocock/skills 与今天已覆盖的 Superpowers（代理技能框架）、Anthropic Skills（分层设计）、Scientific Agent Skills（工具组合）存在本质区别：

设计哲学差异：Superpowers 提供框架与泛化能力，Anthropic 提供标准与层级，Scientific 提供研究工具包。而 mattpocock/skills 的设计哲学是「约束即自由」—— 通过小粒度、高度具体的技能约束 AI 行为，避免 AI 拥有过多自主权后产生 misalignment。

粒度差异：每个技能聚焦单一行为模式（如诊断、压缩、移交），而非构建完整开发方法论。技能之间通过配置共享实现组合，而非通过功能叠加。

上下文工程重心：mattpocock/skills 将大量精力投入上下文维护 ——CONTEXT.md 定义领域语言、ADR 文档化决策、/setup-matt-pocock-skills 配置项目特定参数。这些都是传统「技能」概念之外但对 AI 对齐至关重要的上下文工程要素。

工程实践参数总结

集成 mattpocock/skills 到工程流程时，建议关注以下参数：

参数 建议值 说明
diagnose 反馈环耗时 ≤2s 确定性、sharp signal
caveman token 压缩率 ~75% 保留技术准确性
假设生成数量 3–5 个 排序后展示给用户
调试日志前缀 [DEBUG-<hash>] 便于批量清理
Triage 标签粒度 按项目定制 通过 /setup-matt-pocock-skills 配置
CONTEXT.md 更新频率 每次 grill-with-docs 后 持续维护领域语言

mattpocock/skills 的核心价值在于：不是提供一个更强大的 AI，而是提供一个约束 AI 行为的结构化语言，使 AI 的输出更符合工程师的真实需求。Shell 片段生成、上下文工程、反馈循环压缩 —— 这些都服务于同一个目标：让 AI 成为真正的工程伙伴而非制造技术债务的加速器。

参考来源：mattpocock/skills - GitHub（85k Stars，SKILL.md DSL 格式，.claude/ 目录结构）

ai-systems

内容声明：本文无广告投放、无付费植入。

如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。