AI Agent Skill 设计体系：从行为编程到工程化落地

1. Skill 的核心定义

Skill 是自包含的能力包，通过 SKILL.md、脚本、引用资料和资产，把一个通用 Agent 转化为在特定任务上更可靠的专用 Agent。

它提供四类能力：

能力类型	说明	示例
专用工作流	多步骤、可复用的任务流程	写技术方案、处理 PR 评论、生成报告
工具集成	使用特定文件格式、API 或 CLI 的方法	处理 PDF、调用 GitHub、操作表格
领域知识	业务规则、数据口径、组织约定	公司指标口径、内部权限边界
捆绑资源	脚本、模板、参考资料、素材	scripts/、references/、assets/

Skill 与提示词模板的本质区别：提示词模板在模型状态好、上下文充足、任务简单时生效；高质量 Skill 应该在任务复杂、信息不完整、执行压力下，把 Agent 拉回正确路径。

---

2. 三层加载策略：上下文预算管理

上下文窗口是公共资源。Agent 执行任务时，上下文窗口要同时容纳系统提示、用户请求、对话历史、已触发 Skill、工具结果、代码片段和中间推理。Skill 多占一个 token，其他上下文就少一个 token。

因此 Skill 采用渐进披露，而不是把所有信息塞进一个长文件。分为三层：

• 元数据层（frontmatter）：name + description，负责发现和路由。Agent 在触发前只看到这一层，用于判断是否应该加载该 Skill
• 正文层（SKILL.md body）：核心执行流程，Agent 触发后加载
• 引用层（references/）：按需查阅的知识，不抢占上下文

name 和 description 的职责必须分离：description 应该包含"这个 Skill 做什么"和"什么时候使用它"，但不能变成完整工作流摘要。它的职责是让 Agent 正确加载正文，而不是让 Agent 读完描述就开始凭印象执行。

每一段内容都应该经受两个问题挑战：

• Agent 真的需要这段解释吗？
• 这段内容值得它占用的 token 成本吗？

---

3. 资源组织：脚本、引用、资产各司其职

scripts/：确定性任务

当同一段代码会被反复重写，或者任务需要确定性时，放进 scripts/。脚本的价值是减少上下文消耗和行为漂移。让 Agent 每次临时生成旋转 PDF 的代码，和让它调用一个已经验证过的脚本，是不同级别的可靠性。

references/：按需查阅的知识

当信息是任务执行时需要查阅的知识，而不是每次都必须读的流程，就放进 references/。比如用户问销售指标，Agent 只需要读对应的领域文件，不应该同时加载所有规则。这就是渐进披露在真实 Skill 中的价值：信息可发现，但不抢占上下文。

assets/：输出材料

当文件不会被读入上下文，而是作为输出材料被复制、修改或引用时，放进 assets/，例如模板工程、字体、图片、品牌素材。

关键原则：信息只放一个地方。不要在 SKILL.md 和 references/ 中重复同一段规则。重复会带来漂移，漂移会让 Agent 在两个版本之间自行解释，增加维护成本。

---

4. 自由度控制：匹配任务脆弱度

Skill 不是越详细越好，也不是越开放越好。关键是让自由度匹配任务的脆弱度和变化空间。

自由度	控制方式	适用场景
高自由度	结构原则、语气规则、示例引导	写技术文章、创意任务
中自由度	SQL 模板、字段说明控制口径	查询内部指标、数据分析
低自由度	脚本确定性执行、门控	旋转 PDF、格式转换、固定报告

常见错误：脆弱操作写成开放建议，导致 Agent 每次重写一遍容易出错的逻辑。另一个错误：把判断任务写成死流程，导致 Skill 在真实场景里僵硬不可迁移。

门控机制：在条件满足前，明确禁止后续动作。门控不是语气问题，而是执行边界。它能减少 Agent 的解释空间，让 Skill 在关键路径上更像程序，而不是建议。

常见门控类型：

门控类型	作用	示例
依赖门控	前置条件未满足时禁止执行	未规划好资源前不要创建 SKILL.md
顺序门控	强制步骤顺序	未验证前不要交付
验证门控	输出未通过检查时禁止继续	格式验证不通过不要提交
安全门控	高风险操作前要求确认	涉及生产环境操作前暂停并请求人工

---

5. 创建流程：从例子到 Skill

六步流程：

1. 理解具体使用例子
2. 规划可复用资源
3. 初始化 Skill
4. 编辑 SKILL.md 和资源
5. 验证 Skill
6. 基于真实使用迭代

关键原则：不要从抽象能力开始写 Skill。先问：用户会怎么触发它？哪些请求应该触发？哪些不应该触发？任务输入是什么？成功输出是什么？哪些步骤最容易出错？

对每个例子，从零执行一遍，识别可复用部分。当 Skill 包含非线性判断、循环、回退或容易提前终止的步骤时，流程图比纯文本更稳定。

初始化 Skill 时，应使用初始化脚本，而不是手写目录结构。初始化脚本的意义是减少结构错误，并生成符合规范的模板。

---

6. 验证方法：基于 TDD 的 Skill 测试

基础验证

完成基础验证至少应覆盖：YAML frontmatter 合法性、name 和 description 是否存在、命名是否符合规则、资源目录是否合理、脚本是否能运行、UI 元数据是否与 SKILL.md 同步。格式验证不能证明 Skill 好用，但可以排除低级错误。

前向测试

用子代理模拟真实用户任务，但要把它当评估面，而不是审稿人。

正确做法：使用位于 /path/to/skill-x 的 @skill-x 来解决问题 y。

不好做法：审查这个 Skill，我认为它存在问题 A，预期修复方案是 B。

后者会泄露诊断和预期答案，测试结果会被污染。

合理化防御

AI Agent 在压力下会给跳过规则找到听起来合理的理由。Skill 需要提前写出这些借口，并给出反驳。审查循环应该围绕真实失败风险，而不是措辞偏好。

应该阻塞的问题：触发条件模糊、资源引用缺失、脚本不可运行、验证流程缺失、自由度设置错误、关键信息重复且容易漂移。

不应该阻塞的问题：纯粹风格偏好、不影响执行的标题顺序、可由 Agent 自行判断的轻微表达差异。

---

7. 生态边界

发现机制

description 是路由器，不是教程。它应该覆盖 Skill 做什么、何时使用、典型触发词、相关症状、输入或任务类型，但不要写完整执行流程。

Skill 间引用

声明关系，不硬编码路径，不强制加载大文件。引用分为三层：必需子 Skill、推荐、另见。不要用一次性强制加载大量内容的方式组合 Skill，那会破坏渐进披露。

平台适配

不同平台的工具名、hook、插件机制和子 Agent 能力可能不同。Skill 应该尽量写行为规则，再用平台层适配具体工具。平台能力不足时优雅降级。真正应该稳定的是行为规则，而不是某个平台的私有工具名。

---

8. 反模式与自查表

常见反模式：

反模式	特征	后果
文档式 Skill	把背景知识完整搬进 Skill	占用大量上下文，Agent 找不到关键指令
一次性 Skill	针对单一任务设计，不可复用	维护成本高，技能库膨胀
过度设计	把简单任务写成复杂流程	执行成本高，容错率低
无验证 Skill	写完即冻结，不测试	上线后行为不可控

交付前自查：如果多数问题答不上来，Skill 还不是能力包，只是一份草稿。

---

9. 总结

好 Skill 是小而准的行为系统。设计一个 Skill 要回答三个问题：

• Agent 在什么情况下应该发现并加载它？
• Agent 应该获得多少自由度，哪些部分必须被脚本或门控固定？
• 如何用真实任务证明它确实改变了行为？

核心提醒：简洁、分层、可验证、可迭代。上下文窗口是公共资源，SKILL.md 只放核心流程；脚本承接确定性，引用承接领域知识，资产承接输出材料；复杂 Skill 要通过真实任务前向测试，而不是靠作者自信。