Agent 技能系统设计模式
Agent 技能系统设计模式
学习目标
- 理解 agent-skills 项目的 SKILL.md 标准章节流及其设计意图
- 掌握三层层级披露在技能包中的具体实现
- 学习触发描述字段的关键约束（为什么不能包含流程步骤）
- 掌握验证非协商性原则在每个技能中的落地方式
前置知识
本章涉及 Skill 渐进式知识管理的通用原理，建议先阅读：
下文假设你已理解上述概念，直接聚焦 agent-skills 的具体实现。
项目实践
标准章节流：从”知识文档”到”工作流指令”
agent-skills 项目的核心创新是将 Skill 从”参考文档”转变为”工作流指令”。每个 SKILL.md 遵循标准章节流：
# Skill Title## Overview → 1-2 句电梯演讲## When to Use → 触发条件 + 排除条件## Core Process → 编号步骤或阶段的工作流## Techniques/Patterns → 详细技术指南## Common Rationalizations → 反合理化表## Red Flags → 违反行为的可观察信号## Verification → 退出标准检查清单与通用 Skill 系统的差异：大多数 Skill 系统（如 Claude Code 原生 Skill）将 SKILL.md 视为”知识参考”——Agent 在需要时查阅。agent-skills 将每个 Skill 设计为Agent 必须执行的工作流——每一步都有进入条件和退出标准。
等价标题可接受：How It Works、Workflow、Steps、Core Process 等当它们传达相同目的时都可以使用。agent-skills 不强制固定标题，而是强制职责分离。
触发描述的关键约束
agent-skills 的 description frontmatter 字段有一条关键约束：不应包含流程步骤。
# 错误：描述中包含流程步骤description: First check for applicable skill, then read the SKILL.md, follow the steps in order, and verify at the end
# 正确：只写触发条件和用途description: Conducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human.原因：Agent 首先读取 description。如果 description 中包含流程摘要，Agent 会认为”我已经知道要做什么了”，从而跳过阅读 SKILL.md 正文。这导致渐进式披露机制被破坏——关键的反合理化表和验证检查被忽略。
三层层级披露的具体实现
agent-skills 的三层披露不是理论概念，而是通过具体的文件组织实现的：
skills/ incremental-implementation/ SKILL.md # 入口（~240 行） doubt-driven-development/ SKILL.md # 入口（~240 行） idea-refine/ SKILL.md # 入口（~80 行） frameworks.md # 支撑文件（~200 行） examples.md # 支撑文件（~150 行） refinement-criteria.md # 支撑文件（~100 行）references/ # 项目级参考，不被任何技能独占 orchestration-patterns.md # ~370 行 testing-patterns.md security-checklist.md performance-checklist.md accessibility-checklist.md关键设计决策：
references/在项目根目录，不在技能目录内——这避免了参考文件被单个技能独占- 支撑文件只在内容超过 100 行时才创建（如
idea-refine有三个支撑文件） - 不含 runnable helpers 的技能不创建空的
scripts/目录
六条写作原则的落地
agent-skills 在 docs/skill-anatomy.md 中定义了六条写作原则，这些原则直接体现在 23 个技能中：
| 原则 | 体现 | 示例 |
|---|---|---|
| 过程优于知识 | 每个技能的核心是编号步骤，不是概念解释 | spec-driven-development 的四阶段工作流 |
| 具体优于一般 | ”运行 npm test” 而非 “验证测试” | incremental-implementation 的 Increment Checklist |
| 证据优于假设 | Verification 检查框要求证据 | ”All tests pass (npm test)“ |
| 反合理化 | 每个技能都有 Rationalizations 表 | 23 个技能，23 个表 |
| 渐进式披露 | SKILL.md < 500 行，支撑文件按需读取 | idea-refine 拆分 3 个支撑文件 |
| Token 意识 | 描述不超过 1024 字符，不包含流程摘要 | 所有 description 只写触发条件 |
问题与规避
| 陷阱 | 表现 | 对策 |
|---|---|---|
| SKILL.md 过长 | 每次触发都浪费上下文，Agent 跳过阅读 | 超过 500 行时拆分到支撑文件 |
| 描述包含流程 | Agent 看摘要而不读全文 | 描述只写”做什么”和”什么时候用” |
| 支撑文件空目录 | 增加噪音不改变工作方式 | 不创建空的 scripts/ 目录 |
| 验证无证据 | ”看起来对”不算通过 | 每个检查框指定证据形式 |
设计取舍
为什么用 Markdown 而非 JSON/YAML？
Markdown 对人类和模型都友好。agent-skills 的 23 个技能全部是纯 Markdown，没有 JSON schema 或 YAML 工作流定义。这意味着：
- 人类可以直接在 GitHub 上阅读和编辑
- 模型可以直接理解自然语言指令
- 不需要额外的解析层
代价是无法用类型系统验证正确性——依赖测试和 code review 来保证质量。
为什么每个技能都是独立的，而非一个大型工作流定义？
独立技能支持渐进式披露：Agent 只加载当前需要的技能，而非一次性加载整个工作流。这使得 token 使用量最小化。如果需要组合多个技能（如 spec → plan → build），由用户或斜杠命令编排，而非在技能内部硬编码。
参考来源
- 源码验证:
docs/skill-anatomy.md— 技能解剖学官方文档 - 源码验证: 23 个
skills/*/SKILL.md— 标准章节流的具体实现