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 实验的创建与修改能力,支持实验创建、调流量、  加桶删桶、实验下线等操作。当用户提到创建实验、修改实验、调流量、加桶删桶、  实验下线等场景时触发。---
下面是以 Claude Code 为例的完整 frontmatter 字段:

维度

字段

是否必填

约束

用途

身份字段(触发机制)

name

必填

最长 64 字符,只能用小写字母、数字和连字符,不能以连字符开头或结尾;若省略默认使用目录名

Skill 的唯一标识符,同时也是文件夹名。Agent 通过它来定位和管理 Skill

description

必填

最长 1024 字符,不能为空;若省略默认使用 SKILL.md 正文第一段

Skill 能否被正确触发的关键。Agent 靠这段描述来判断当前任务是否该调用这个 Skill,需要写清楚做什么(WHAT)以及什么时候该用它(WHEN)

argument-hint

可选

参数提示格式,如 [source directory] [output format]

在 / 菜单中显示,帮助用户了解该 Skill 接受的输入格式

权限字段(权限控制)

disable-model-invocation

可选

布尔值(true/false)

设为 true 时,禁止模型自动调用该 Skill,仅允许用户手动触发

user-invocable

可选

布尔值(true/false)

设为 false 时,用户不能直接调用该 Skill,只有模型可以自动调用

allowed-tools

可选

工具名列表,如 Read, Grep, Glob, Write, Bash(python:*)

工具白名单,精确控制 Skill 执行时可调用的工具及其权限范围

model

可选

模型名称,如 haiku、sonnet

指定该 Skill 使用的模型;建议简单任务用 Haiku 提升响应速度并降低成本

执行字段(运行时环境)

context

可选

可选值:fork

执行上下文;设为 fork 时,将在隔离的子智能体中执行,确保不污染主对话上下文

agent

可选

可选值:Explore、Plan、general-purpose 或自定义 Agent

子智能体类型;当 context 设为 fork 时生效

hooks

可选

支持 PreToolUse、PostToolUse 等钩子事件

生命周期事件钩子,定义 Skill 激活期间的事件处理逻辑

version

可选

语义化版本号(semver),如 1.0.0

用于版本控制和追踪迭代,方便团队协作时知道当前用的是哪个版本

正文部分可以直接看 Skill 例子的正文,此处不展开赘述。

三、触发机制

Skills 的触发机制是整个系统中最为关键的环节,直接决定了 Skill 能否在恰当时机被激活。这一点甚至比 Skills 内容本身质量更为重要。

3.1 自动触发和手动触发

Skills 支持自动触发(语义匹配)和手动触发两种机制:

自动触发:靠的是 description 字段。当用户的意图和 Skill 描述语义匹配时,Agent 会自己判断"这个任务我有现成的专业流程可以用",然后主动加载…

— 以上为试看内容(约 40%),开通会员后阅读全文 —