Harness 工程之道:Skill 原理与最佳实践
阿里妹导读
Agent Skills 是一种轻量、开放的能力扩展规范,用于为 AI Agent 扩展专业知识和工作流。本文从概念原理出发,结合真实的工程化项目 trade-ab-skill,系统性地讲解 Skill 的结构规范、触发机制、作用域优先级,以及最佳实践。(文章内容基于作者个人技术实践与独立思考,旨在分享经验,仅代表个人观点。)
一、Skill 的产生与核心理念
1.1 从 Prompt 工程到 Skill 工程的演进
当前的大模型都存在一个共性:每轮对话都是"失忆"的,必须从零开始构建上下文,由此发展出了 Prompt 工程。比如 CLAUDE.md 将团队的技术选型、编码规范、架构约束等都固化为一份 Agent 可读的配置文档。每次会话启动时,Agent 就会自动加载这些信息,直接进入高效协作模式,不需要每次都从头到尾交代背景。
但是随着复杂性的增加,问题也逐渐暴露出来。传统的 Prompt 工程将所有领域知识一股脑塞进提示词,项目越复杂,Prompt 越臃肿。上下文窗口被撑满,模型的注意力被稀释,真正关键的信息反而容易被"淹没"。并且这些知识和具体项目深度耦合,换个场景就得重写一遍,几乎没有复用性可言。
Agent Skill 的出现正是为了解决这些问题,它将领域知识和工作流封装为可移植、可版本控制的文件夹,用来"教"Agent 如何处理特定任务或工作流,Agent 按需加载。你可以将 Skills 类比成新员工手册。这也是 Anthropic 官方博客用的类比:Skills 是给 AI Agent 的「入职指南」,把领域知识打包成可发现、模块化的能力。
下面是 Agent Skills 的官方定义:
"Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows."
1.2 核心理念:渐进性披露
Skill 体系最核心的设计理念是渐进性披露(Progressive Disclosure),即只在需要时才加载需要的知识,而非一次性加载全部。
Skill 的渐进性披露主要分三阶段:
Discovery(发现)阶段:当会话启动时仅会加载每个 Skill 的 name 和 description,这部分是以常驻方式注入 Agent 上下文中的。
Activation(激活)阶段:当任务匹配上 description 时,将读取完整的 SKILL.md,加载 SKILL.md 中的路由表和全局规则,但还不加载子模块。
Execution(执行)阶段:按路由表加载对应的模块文件,按需读取参考文档,只加载当前任务真正需要的知识。
该模型在实际应用中带来的性能提升是显著的,绝大部分请求仅需要部分资源。渐进性披露用最小的上下文成本,换取了最大的知识覆盖范围,确保上下文窗口留给真正重要的信息,这就是"按需投放知识"的核心经济学优势。同样也保证了决策的精准性和 Skill 的可扩展性。
1.3 System Prompt 与 Skill 的区别
文件类型 | System Prompt | Skill |
定位 | 项目级全局规则、编码规范 | 特定领域能力封装 |
加载策略 | 会话启动时全量加载 | 渐进式按需加载 |
生效范围 | 当前项目 | 可跨项目、跨会话(取决于作用域配置) |
上下文成本 | 恒定占用,与任务无关也会消耗 | 仅在命中时加载,未命中零成本 |
结构化 | 单文件,扁平组织 | 多文件模块化,支持脚本和资源 |
适用场景 | 编码风格、项目约定、通用约束 | 完整工作流、多步骤流程、领域专家知识 |
简单记法:System Prompt 是"这个项目的规矩",Skill 是"一种可复用的能力"。
一个项目可以同时拥有 System Prompt 和多个 Skill:System Prompt 定义全局编码规范和项目约定,Skill 封装特定领域的工作流。两者协同工作——System Prompt 中的规则对所有 Skill 生效,而 Skill 内部的规则仅在激活时叠加。
二、Skill 的结构组成
2.1 目录结构规范
一个 Skill 的核心就是一个包含 SKILL.md 的文件夹:
my-skill/ # 必需:skill名称,短横线分隔├── SKILL.md # 必需:主文件,包括元信息 + 指令,文件名需全大写├── scripts/ # 可选:可执行脚本├── references/ # 可选:参考文档├── assets/ # 可选:模板、资源└── ... # 任意额外文件
这种格式已被 Claude Code、Cursor、GitHub Copilot、Gemini CLI 等 40+ 主流 Agent 产品采纳,成为事实上的开放标准。
一个设计良好的 Skill 目录结构,是渐进性披露能否有效落地的基础。核心思想是主文件做路由,模块文件做执行。
2.2 SKILL.md 文件结构
SKILL.md 是每个 Skill 的唯一入口,也是唯一的"触发器",其结构分为两部分:frontmatter 元信息和正文指令。
frontmatter 是 YAML 格式的元信息块,最核心的两个字段是 name 和 description:
---name: trade-ab-skilldescription: 为用户提供 AB 实验的创建与修改能力,支持实验创建、调流量、 加桶删桶、实验下线等操作。当用户提到创建实验、修改实验、调流量、加桶删桶、 实验下线等场景时触发。---
维度 | 字段 | 是否必填 | 约束 | 用途 |
身份字段(触发机制) |
| 必填 | 最长 64 字符,只能用小写字母、数字和连字符,不能以连字符开头或结尾;若省略默认使用目录名 | Skill 的唯一标识符,同时也是文件夹名。Agent 通过它来定位和管理 Skill |
| 必填 | 最长 1024 字符,不能为空;若省略默认使用 SKILL.md 正文第一段 | Skill 能否被正确触发的关键。Agent 靠这段描述来判断当前任务是否该调用这个 Skill,需要写清楚做什么(WHAT)以及什么时候该用它(WHEN) | |
| 可选 | 参数提示格式,如 | 在 | |
权限字段(权限控制) |
| 可选 | 布尔值( | 设为 |
| 可选 | 布尔值( | 设为 | |
| 可选 | 工具名列表,如 | 工具白名单,精确控制 Skill 执行时可调用的工具及其权限范围 | |
| 可选 | 模型名称,如 | 指定该 Skill 使用的模型;建议简单任务用 Haiku 提升响应速度并降低成本 | |
执行字段(运行时环境) |
| 可选 | 可选值: | 执行上下文;设为 |
| 可选 | 可选值: | 子智能体类型;当 | |
| 可选 | 支持 | 生命周期事件钩子,定义 Skill 激活期间的事件处理逻辑 | |
| 可选 | 语义化版本号(semver),如 1.0.0 | 用于版本控制和追踪迭代,方便团队协作时知道当前用的是哪个版本 |
正文部分可以直接看 Skill 例子的正文,此处不展开赘述。
三、触发机制
Skills 的触发机制是整个系统中最为关键的环节,直接决定了 Skill 能否在恰当时机被激活。这一点甚至比 Skills 内容本身质量更为重要。
3.1 自动触发和手动触发
Skills 支持自动触发(语义匹配)和手动触发两种机制:
自动触发:靠的是 description 字段。当用户的意图和 Skill 描述语义匹配时,Agent 会自己判断"这个任务我有现成的专业流程可以用",然后主动加载…