Matt Pocock 的 skills 仓库代表了 AI Agent 技能定义的一种主流范式 —— 将工程实践封装为可组合的指令单元。与传统的系统提示词不同，这些技能以结构化文档形式存在，支持模型在运行时动态加载并执行特定工作流。本文从该仓库的技能定义格式出发，提取其核心设计模式，并推导出一套可用于多框架迁移的 YAML 规范。
技能仓库的目录结构与加载机制
mattpocock/skills 采用分类目录组织技能，顶层分为 engineering、productivity 和 misc 三个类别。每个技能对应一个独立的文件夹，内部仅保留一个核心文件 SKILL.md。这种极简结构的设计意图在于降低技能加载的认知开销 —— 模型只需读取一个文件即可获取完整的技能描述与执行指南。
技能被发现与加载的流程遵循以下逻辑：Agent 在启动或会话初始化时扫描预设的技能目录，解析每个 SKILL.md 中的元数据（主要是 name 和 description 字段），建立技能名称到触发条件的映射。当用户输入与某个技能的描述相匹配时，Agent 将该技能的完整内容加载到上下文窗口中，然后按照文件中定义的步骤执行。这种基于描述匹配的触发机制与 ComposioHQ 的 awesome-codex-skills 仓库保持一致，后者额外支持 scripts/、references/ 和 assets/ 子目录，用于存放可执行脚本与参考资料。
从工程实践角度看，这种结构的优势在于版本控制友好 —— 每个技能是一个独立的提交单元，便于追踪变更历史。同时，由于技能内容以 Markdown 形式存储，开发者可以直接在编辑器中预览和编辑，无需特殊的 DSL 工具链。
SKILL.md 的内部结构解析
打开一个具体的技能文件，例如 skills/engineering/tdd/SKILL.md，可以观察到其内部采用多层渐进式披露（Progressive Disclosure）的组织方式。文件开头是 YAML frontmatter，仅包含两个必填字段：name 提供技能的可读标识，description 则以自然语言描述技能的适用场景和触发条件。description 的写作质量直接决定了技能能否被正确触发，因此需要尽可能覆盖用户可能表达需求的多种表述方式。
文件主体通常由三个部分组成。第一部分是 Philosophy 或 Principles，阐述该技能背后的工程哲学 —— 以 TDD 技能为例，它详细解释了什么是好的测试（通过公共接口验证行为）和什么是坏的测试（耦合实现细节），并用反模式说明（如水平切片 vs 垂直切片）来强化概念。第二部分是 Workflow，这是技能的核心执行逻辑，通常以编号步骤的形式呈现，例如 TDD 技能的「规划 → tracer bullet → 增量循环 → 重构」四阶段流程。每个阶段都有明确的输入、输出和检查点。第三部分是 Checklist，提供每个执行周期的自检清单，帮助模型在自动化执行时保持质量意识。
这种三段式结构的妙处在于，它同时满足了模型在两个不同阶段的认知需求：加载阶段通过 description 快速判断是否应该激活该技能，执行阶段则通过哲学阐述理解为什么这样做的深层原因，再通过工作流清单确保每一步都落实到位。
可复用命令模式库的设计思路
基于对 mattpocock/skills 和 awesome-codex-skills 的结构分析，可以提炼出一套可复用的命令模式库设计原则。
第一，触发条件的描述应当采用「意图 + 场景」的二元组表达。意图描述用户想要达成的目标（如「进行测试驱动开发」），场景描述触发时的上下文特征（如「用户提到 red-green-refactor」「用户要求先写测试」）。在设计技能时，可以将常见的同义表述预先写入 description，降低模型匹配失败的概率。
第二，工作流步骤应当遵循「最小闭环」原则。每个步骤必须有明确的入口条件和出口状态，步骤之间通过显式的产物传递来衔接。以 TDD 技能为例，「写一个测试」的出口状态是「测试失败且失败原因与被测行为相关」，这一步的输出直接作为下一步「写最小实现代码」的入口条件。这种设计使得技能在自动化执行时具备可重试性 —— 如果某一步失败，可以回到上一步重新来过。
第三，检查点清单应当与工作流步骤一一对应。TDD 技能在每个循环周期结束时提供了五个检查项，涵盖测试是否验证行为而非实现、是否仅使用公共接口、代码是否足够简洁等维度。这种设计相当于在技能内部嵌入了一个微型测试框架，确保执行过程不偏离既定原则。
跨框架迁移的 YAML 规范提案
为了使技能定义能够在不同 Agent 框架之间迁移，本文提出一个精简的 YAML 规范。该规范在保留 mattpocock/skills 核心要素的基础上，增加了框架无关的元数据字段。
name: tdd
description: |
Test-driven development with red-green-refactor loop. Use when user wants
to build features or fix bugs using TDD, mentions "red-green-refactor",
wants integration tests, or asks for test-first development.
triggers:
- "red-green-refactor"
- "test-first development"
- "TDD"
- "write tests first"
philosophy:
- |
Tests should verify behavior through public interfaces, not implementation
details. Code can change entirely; tests shouldn't.
- |
Good tests are integration-style: they exercise real code paths through
public APIs.
anti_patterns:
- name: "Horizontal Slices"
description: "DO NOT write all tests first, then all implementation."
workflow:
- name: "Planning"
steps:
- "Confirm with user what interface changes are needed"
- "Confirm with user which behaviors to test (prioritize)"
checklist:
- "Test describes behavior, not implementation"
- "Test uses public interface only"
- name: "Tracer Bullet"
steps:
- "Write ONE test that confirms ONE thing about the system"
- "Write minimal code to pass"
- name: "Refactor"
steps:
- "Extract duplication"
- "Deepen modules"
checklist_per_cycle:
- "Test describes behavior, not implementation"
- "Test uses public interface only"
- "Test would survive internal refactor"
- "Code is minimal for this test"
该规范的关键改进在于：引入 triggers 数组显式列出触发关键词，与 description 形成双重匹配机制；将 philosophy 和 anti_patterns 独立为数组，便于模型在推理时引用具体原则；将 workflow 分解为带有 checklist 的子步骤，使每个阶段的完成条件更加清晰。对于希望构建内部技能库的开发团队，这个规范可以直接作为目录结构设计的参考 —— 只需将 YAML 转换为对应框架要求的格式（如 Claude Code 的 prompts 目录或 Codex 的 skills 目录）。
资料来源：GitHub - mattpocock/skills: Skills for Real Engineers；GitHub - ComposioHQ/awesome-codex-skills: A curated list of practical Codex skills。