为 Agent 添加 Skills 支持
为 AI Agent 或开发工具添加 Agent Skills 支持的指南。
本指南介绍如何为 AI Agent(智能体)或开发工具添加 Agent Skills 支持,涵盖完整的生命周期:发现 Skill、向模型介绍可用 Skill、将 Skill 内容载入上下文,以及在后续对话中持续保留这些内容的作用。
无论 Agent 采用什么架构,集成的核心流程都相同。实现细节取决于两个因素:
- Skill 存放在哪里? 本地运行的 Agent 可以扫描用户文件系统中的 Skill 目录。云端托管或沙箱中的 Agent 则需要其他发现机制,例如 API、远程注册中心或随程序打包的资源。
- 模型如何访问 Skill 内容? 如果模型具备文件读取能力,可以直接读取
SKILL.md。否则,需要提供专用工具,或通过程序将 Skill 内容注入 Prompt。
本指南会在相关位置说明这些差异。无需支持所有场景,选择适合你的 Agent 的实现路径即可。
前提条件:熟悉 Agent Skills 格式规范,其中定义了 SKILL.md 的文件格式、前置元数据字段和目录约定。
核心原则:渐进式披露
所有兼容 Skills 的 Agent 都遵循相同的三层加载策略:
层级 | 加载内容 | 加载时机 | token 开销 |
|---|---|---|---|
1. 目录 | 名称与描述 | 会话开始时 | 每个 Skill 约 50–100 个 token |
2. 指令 | 完整的 | Skill 激活时 | 建议少于 5,000 个 token |
3. 资源 | 脚本、参考资料、素材 | 指令引用这些资源时 | 视情况而定 |
模型从会话开始就能看到目录,知道有哪些 Skill 可用。判断某个 Skill 与任务相关后,才加载完整指令。如果指令引用了辅助文件,模型再按需逐一加载。
这样既能保持较小的基础上下文,又能让模型按需获取专业知识。即使 Agent 安装了 20 个 Skill,也不必在开始时就承担 20 套完整指令的 token 开销,只需加载当前对话中实际使用的 Skill。
第 1 步:发现 Skill
会话启动时,查找所有可用的 Skill,并加载其元数据。
扫描哪些位置
扫描哪些目录,取决于 Agent 的运行环境。多数本地运行的 Agent 至少会扫描两个范围:
- 项目级(相对于工作目录):特定项目或仓库使用的 Skill。
- 用户级(相对于用户主目录):该用户在所有项目中均可使用的 Skill。
还可以支持其他范围,例如管理员统一部署的组织级 Skill,或 Agent 自带的 Skill。具体支持哪些范围,取决于 Agent 的部署方式。
在每个范围内,可以同时扫描客户端专用目录和约定的 .agents/skills/ 目录:
范围 | 路径 | 用途 |
|---|---|---|
项目级 |
| 客户端的原生存储位置 |
项目级 |
| 支持跨客户端互操作 |
用户级 |
| 客户端的原生存储位置 |
用户级 |
| 支持跨客户端互操作 |
.agents/skills/ 路径已成为跨客户端共享 Skill 的通行约定。Agent Skills 规范并未规定 Skill 目录必须存放在哪里,只定义了目录内部的内容;不过,扫描 .agents/skills/ 后,其他遵循这一约定的客户端安装的 Skill 就会自动对你的客户端可见,反之亦然。
注意
许多现有 Skill 安装在
.claude/skills/中,因此部分实现也会扫描项目级和用户级的这一目录,以兼容现有使用方式。还可以扫描从当前目录向上直到 Git 根目录的各级祖先目录(适用于 monorepo)、XDG 配置目录,以及用户自行配置的路径。
扫描什么内容
在每个 Skills 目录中,查找包含名为 SKILL.md 的文件的子目录,文件名必须完全一致:
~/.agents/skills/
├── pdf-processing/
│ ├── SKILL.md ← 识别为 Skill
│ └── scripts/
│ └── extract.py
├── data-analysis/
│ └── SKILL.md ← 识别为 Skill
└── README.md ← 忽略(不是 Skill 目录)实用的扫描规则:
- 跳过
.git/、node_modules/等不会包含 Skill 的目录。 - 可以遵循
.gitignore,避免扫描构建产物。 - 设置合理的边界,例如最大深度为 4–6 层、最多扫描 2,000 个目录,避免在大型目录树中无节制地扫描。
处理名称冲突
如果两个 Skill 的 name 相同,应采用确定的优先级规则。
现有实现普遍遵循的约定是:项目级 Skill 覆盖用户级 Skill。
在同一范围内,例如 <project>/.agents/skills/ 和 <project>/.<your-client>/skills/ 下都发现了名为 code-review 的 Skill,可以让先发现的或后发现的优先,选择一种并保持一致即可。发生冲突时,应记录警告,让用户知道某个 Skill 因同名而未能生效。
信任问题
项目级 Skill 来自当前处理的仓库,而仓库可能尚不可信,例如刚克隆的开源项目。可以在加载项目级 Skill 之前检查信任状态,只加载用户已标记为可信的项目文件夹中的 Skill。这样可以防止不可信仓库在用户不知情的情况下,向 Agent 的上下文注入指令。
云端托管与沙箱中的 Agent
如果 Agent 运行在容器或远程服务器中,就无法访问用户的本地文件系统。不同范围的 Skill 需要采用不同的发现方式:
- 项目级 Skill 通常最容易处理。如果 Agent 操作的是克隆的仓库,即使仓库位于沙箱内,项目级 Skill 也会随代码一同进入环境,可以从仓库目录树中扫描。
- 用户级和组织级 Skill 并不存在于沙箱中,需要从外部来源提供。例如,克隆配置仓库,在 Agent 设置中接受 Skill URL 或安装包,或允许用户通过 Web 界面上传 Skill 目录。
- 内置 Skill 可以作为静态资源打包进 Agent 的部署产物,无需从外部获取,每次会话都可使用。
只要 Agent 能访问 Skill,后续的解析、披露和激活流程就与其他环境相同。
第 2 步:解析 SKILL.md 文件
从发现的每个 SKILL.md 文件中提取元数据和正文。
提取前置元数据
SKILL.md 文件分为两部分:两条 --- 分隔线之间的 YAML 前置元数据,以及结束分隔线之后的 Markdown 正文。解析步骤如下:
- 找到文件开头的
---,以及后续作为结束标记的---。 - 解析两者之间的 YAML 块,提取必需的
name和description,以及其他可选字段。 - 结束标记
---之后的全部内容,去除首尾空白后,就是 Skill 的正文。
所有前置元数据字段及其约束,详见格式规范。
处理格式错误的 YAML
为其他客户端编写的 Skill 文件,可能包含严格来说无效的 YAML,只是恰好能由那些客户端的解析器接受。最常见的问题是字段值含有冒号,却没有加引号:
# 严格来说无效的 YAML:冒号会导致解析失败
description: 在以下情况下使用此 Skill: 用户询问 PDF可以提供回退机制,为这类值补上引号,或转换成 YAML 块标量,再重试解析。这样只需很小的成本,就能改善跨客户端兼容性。
宽松校验
遇到问题时发出警告,但尽可能继续加载 Skill:
- 名称与父目录名不一致 → 警告,仍然加载。
- 名称超过 64 个字符 → 警告,仍然加载。
- 描述缺失或为空 → 跳过该 Skill,并记录错误;描述是向模型披露 Skill 的必要信息。
- YAML 完全无法解析 → 跳过该 Skill,并记录错误。
记录诊断信息,以便通过调试命令、日志文件或界面展示给用户;不要因为表面格式问题就阻止 Skill 加载。
注意
格式规范 对
name字段有严格约束,包括与父目录名一致、允许的字符和最大长度。上述宽松策略有意放宽这些限制,以改善与其他客户端所用 Skill 的兼容性。
存储哪些信息
每条 Skill 记录至少需要三个字段:
字段 | 说明 |
|---|---|
| 来自前置元数据 |
| 来自前置元数据 |
|
|
将这些信息存入以 name 为键的内存映射中,便于激活时快速查找。
可以在发现 Skill 时一并存储正文,也就是前置元数据之后的 Markdown 内容;也可以等到激活时,再从 location 读取。提前存储能加快激活速度;激活时读取则能减少整体内存占用,并及时获取两次激活之间 Skill 文件的修改。
后续解析相对路径、列出附带资源时,还需要 Skill 的基础目录,即 location 所在的父目录;需要时从 location 推导即可。
第 3 步:向模型披露可用 Skill
让模型知道有哪些 Skill,但暂不加载其完整内容。这是渐进式披露的第一层。
构建 Skill 目录
为发现的每个 Skill 提供 name、description,以及可选的 location(SKILL.md 文件的路径)。结构化格式可以根据技术栈选择,XML、JSON 或无序列表均可:
<available_skills>
<skill>
<name>pdf-processing</name>
<description>提取 PDF 文本、填写表单、合并文件。处理 PDF 时使用。</description>
<location>/home/user/.agents/skills/pdf-processing/SKILL.md</location>
</skill>
<skill>
<name>data-analysis</name>
<description>分析数据集、生成图表并创建汇总报告。</description>
<location>/home/user/project/.agents/skills/data-analysis/SKILL.md</location>
</skill>
</available_skills>location 字段有两个用途:支持通过读取文件来激活 Skill(见第 4 步),并为模型解析正文中的相对引用提供基础路径,例如 scripts/evaluate.py。如果专用激活工具会在返回结果中提供 Skill 目录路径(见第 4 步的结构化包装),就可以省略目录中的 location;否则,应保留该字段。
每个 Skill 大约为目录增加 50–100 个 token。即使安装了数十个 Skill,目录仍然很紧凑。
将目录放在哪里
常见的做法有两种:
系统提示词中的独立小节:在系统提示词中添加带标题的目录小节,并在前面用简短指令说明如何使用 Skill。这种方式最简单,适用于任何能调用文件读取工具的模型。
工具描述:将目录嵌入专用 Skill 激活工具的描述中(见第 4 步)。这样可以保持系统提示词简洁,也能自然地将发现和激活衔接起来。
两种方式都可行。放在系统提示词中更简单,兼容范围更广;已有专用激活工具时,嵌入工具描述会更简洁。
行为指令
在目录旁加入简短的指令块,告诉模型何时、如何使用 Skill。具体措辞取决于支持的激活机制(见第 4 步):
如果模型通过读取文件来激活 Skill:
以下 Skill 为特定任务提供专门的操作指令。
任务与某个 Skill 的描述匹配时,先用文件读取工具加载
所列位置的 SKILL.md,再继续处理任务。
Skill 引用相对路径时,以其目录(SKILL.md 的父目录)
为基准解析,并在工具调用中使用绝对路径。如果模型通过专用工具激活 Skill:
以下 Skill 为特定任务提供专门的操作指令。
任务与某个 Skill 的描述匹配时,调用 activate_skill 工具,
传入 Skill 名称,以加载其完整指令。这些指令应保持简短,目的是让模型知道 Skill 的存在及其加载方式。具体的操作指令会在 Skill 加载后由其内容提供。
筛选
部分 Skill 应从目录中排除。常见原因包括:
- 用户在设置中禁用了该 Skill。
- 权限系统拒绝访问该 Skill。
- Skill 已声明不允许由模型自行激活,例如设置了
disable-model-invocation标志。
应从目录中完全隐藏筛除的 Skill,不要先列出来,再在激活阶段阻止使用。这样能避免模型浪费交互轮次,反复尝试加载无法使用的 Skill。
没有可用 Skill 时
如果没有发现任何 Skill,应完全省略目录和行为指令。不要展示空的 <available_skills/> 块,也不要注册没有任何有效选项的 Skill 工具,否则会让模型困惑。
第 4 步:激活 Skill
模型或用户选中某个 Skill 后,将其完整指令载入对话上下文。这是渐进式披露的第二层。
由模型自主激活
多数实现依靠模型自身的判断来决定激活,而不在 Harness(Agent 的运行框架)一侧实现触发条件匹配或关键词检测。模型读取目录(见第 3 步),判断某个 Skill 与当前任务相关后,自行加载。
有两种实现方式:
通过读取文件激活:模型使用标准文件读取工具,读取目录中给出的 SKILL.md 路径。无需专门的基础设施,Agent 现有的文件读取能力就足够。模型会以工具返回结果的形式收到文件内容。如果模型能够访问文件,这是最简单的方式。
通过专用工具激活:注册一个接收 Skill 名称并返回其内容的工具,例如 activate_skill。模型无法直接读取文件时,必须使用这种方式;即使模型能够读取文件,这也仍是一个有用的可选方案。与直接读取原始文件相比,它有以下优势:
- 控制返回哪些内容,例如移除或保留 YAML 前置元数据,详见下文模型会收到什么。
- 用结构化标签包裹内容,便于在上下文管理时识别。
- 在指令旁列出附带的资源,例如
references/*。 - 执行权限检查,或请求用户同意。
- 记录激活情况,供后续分析。
提示
如果使用专用激活工具,应将
name参数限制为有效 Skill 名称的集合,例如在工具 Schema 中使用枚举。这能防止模型编造不存在的 Skill 名称。如果没有可用 Skill,就不要注册该工具。
用户显式激活
用户也应能直接激活 Skill,无需等待模型判断。最常见的方式是由 Harness 拦截斜杠命令或提及语法,例如 /skill-name 或 $skill-name。具体语法可以自行决定,关键是由 Harness 负责查找和注入,让模型无需自行执行激活动作,就能收到 Skill 内容。
还可以提供自动补全控件,在用户输入时列出可用 Skill,帮助用户发现这一功能。
模型会收到什么
Skill 激活后,模型会收到其中的指令。具体返回哪些内容,有两种选择:
完整文件:模型看到整个 SKILL.md,包括 YAML 前置元数据。通过读取文件激活时,模型读取的就是原始文件,因此自然会得到完整内容;专用工具也可以采用这种方式。前置元数据中的某些字段在激活阶段仍有价值,例如 compatibility 会说明环境要求,可能影响模型执行 Skill 指令的方式。
仅返回正文(移除前置元数据):Harness 解析并移除 YAML 前置元数据,只返回 Markdown 指令。现有使用专用激活工具的实现大多采用这种方式:在发现阶段提取 name 和 description,随后去除前置元数据。
两种方式在实践中都可行。
结构化包装
如果使用专用激活工具,可以用带有标识作用的标签包裹 Skill 内容。例如:
<skill_content name="pdf-processing">
# PDF 处理
## 何时使用此 Skill
用户需要处理 PDF 文件时,使用此 Skill……
[SKILL.md 正文的其余部分]
Skill 目录:/home/user/.agents/skills/pdf-processing
此 Skill 中的相对路径均以 Skill 目录为基准。
<skill_resources>
<file>scripts/extract.py</file>
<file>scripts/merge.py</file>
<file>references/pdf-spec-summary.md</file>
</skill_resources>
</skill_content>这样做有几个实际好处:
- 模型能清楚地区分 Skill 指令与其他对话内容。
- Harness 能在压缩上下文时识别 Skill 内容(见第 5 步)。
- 附带资源对模型可见,但不会提前加载。
列出附带资源
专用激活工具返回 Skill 内容时,也可以列出 Skill 目录中的辅助文件,包括脚本、参考资料和素材,但不应提前读取这些文件。指令引用某个文件时,再由模型通过文件读取工具按需加载。
如果 Skill 目录很大,可以限制列出的文件数量,并注明清单可能不完整。
将 Skill 目录加入权限白名单
如果 Agent 的权限系统会限制文件访问,应将 Skill 目录加入白名单,让模型读取附带资源时无需反复请求用户确认。否则,每次引用附带脚本或参考文件都会弹出权限对话框,打断包含 SKILL.md 以外资源的 Skill 的工作流程。
第 5 步:持续管理 Skill 上下文
Skill 指令进入对话上下文后,应确保它们在整个会话期间持续有效。
在上下文压缩时保留 Skill 内容
如果 Agent 会在上下文窗口填满后截断或总结旧消息,应将 Skill 内容排除在裁剪范围之外。Skill 指令提供的是持续有效的行为指导;如果对话中途丢失这些指令,Agent 的任务效果会悄然下降,却不会出现明显报错。模型仍会继续工作,只是失去了 Skill 提供的专门指令。
常见做法包括:
- 将 Skill 工具的返回结果标记为受保护内容,让裁剪算法跳过。
- 使用第 4 步中的结构化标签识别 Skill 内容,并在压缩时保留。
避免重复激活
可以记录当前会话中已经激活的 Skill。如果模型或用户尝试加载已在上下文中的 Skill,就跳过再次注入,避免同一套指令在对话中出现多次。
委派给子 Agent(可选)
这是仅有部分客户端支持的高级方式:不把 Skill 指令注入主对话,而是在独立的子 Agent 会话中运行 Skill。子 Agent 接收 Skill 指令、执行任务,再将工作摘要返回主对话。
如果 Skill 的工作流较为复杂,适合在专门的会话中集中处理,就可以采用这种方式。