什么是技能（skill）

约 2975 字大约 10 分钟

2026-04-18

两个故事

故事一：工具箱爆炸

你开发了一个 Agent，一开始，客户说我们想让AI能查询实时天气，于是你封装了一个查询天气的工具，后来，客户说我们想联网搜索，于是你封装了一个搜索的工具……后来，你有了10086个工具。

为了让大模型知道你有哪些可用的工具，每次你都需要把全部的工具列表发送给大模型，光是列出这些工具，已经占了大模型70%的上下文窗口，大模型还没开始干活，就已经累趴了。为什么工具列表会占用这么多上下文？因为一个工具不仅仅是一个名字，还包括了详细介绍、输入输出参数、示例等，这些描述本身就占用 token 。

你在想，有没有办法，在不砍掉工具的前提下做精简？也许按需加载是一个方法，但又该如何做？

故事二：技能包分享

你为了让 AI 完成一项复杂的任务，写了一篇绝妙的提示词，下次你还要让 AI 完成相同的任务时，就再使用一次这个提示词。你自然会想到，把这个提示词保存起来，当需要的时候就拿出来用，也方便分享给别人。

如果这个任务，中间步骤需要执行一个你自己写的 python 脚本来计算某个结果，同时可能需要用到你提供的参考文档，你会想到，把这个脚本和参考文档，跟提示词一起打包成一个文件夹。需要的时候一起传给 AI 就好了。

你把这个文件夹叫做一个技能包。

你会不会想，有没有办法让大家都按相同的形式来存放这样的技能包？让 AI 按相同的方法来读取，这样大家的技能包就可以互相分享了。

Skill（技能）

Skill 就是用来解决上面两个问题的。

什么是 Skill

Skill 的概念由 Anthropic 公司提出，并在 2025 年 10 月首次在 Claude Code 中引入。同时，他们提出了一套 Skill 的规范，只要按这个规范开发的 Agent ，都能够使用 Skill。

Skill 本质上就是一个文件夹，结构如下：

my-skill/
├── SKILL.md          # 必须: 说明文档 + 元数据
├── scripts/          # 可选: 可执行代码
├── references/       # 可选: 参考文档
└── assets/           # 可选: 模板、资源等

SKILL.md 文件大概长这样：

---
name: pdf-processing
description: 解析PDF文本，填写表单，合并文件。在处理PDF文档时使用。
---

# PDF 处理

## 何时使用此 skill
当用户需要处理 PDF 文件时，使用此 skill...

## 如何提取文本
1. 使用 pdfplumber 提取文本...

## 如何填写表单
...

Skill 是如何工作的？

秘诀在于：渐进式加载（progressive disclosure）

流程在于：发现（Discovery）、激活（Activation）、执行（Execution）

发现阶段：一开始，Agent 只需要将 SKILL.md 中的 name 和 description 字段发送给大模型就行，大模型不需要提前了解整个文件夹的内容，这样就能够节省很多上下文空间。目的是让大模型知道有哪些工具存在就行了。当然，Agent 还要给一段系统提示词，告诉大模型这些是可用的 skill 以及他们的路径。
激活阶段：当大模型推理发现某个任务可以用某个 skill 来处理时，它自己会让 Agent 去调取对应 skill 的完整 SKILL.md 文件。
执行阶段：大模型拿到 SKILL.md 的完整描述后，严格按照描述来执行任务。如果需要，它还会调用 skill 里的脚本或者读取参考文档。

SKILL.md 的编写规范

官方编写了一套 SKILL.md 的编写规范，可直接参考：Specification

简而言之，name 和 description 必须要有，其他的都是可选的，name 必须用小写英文。

对于具体的内容，尽量用简洁、清晰的语言描述该怎么做即可，不要太多废话，也不需要把大模型已经知道的常识写进去。

skills 文件夹放在哪

如果你按照上面的规范，写了一个 skill 技能包，通常会放在两个地方。

对于项目级的 skill

如果这个 skill 你只想在某个项目里使用，那么就放在项目目录里，如：

myProject/.agents/skills/{你的skill文件夹}

对于个人级的 skill

如果这个 skill 你想在多个项目里共用，你可以放在个人目录中，这样多种 AI 工具都能读取到。如果你用的是 Windows 系统，它一般在：

C:\Users\{你的用户名}\.agents\skills\{你的skill文件夹}

通常，如果有一个 skill 在个人级目录和项目级目录中都存在，那么项目级的 skill 会覆盖个人级的 skill。

参考：Quickstart

编写 Skill 的最佳实践

这一节是官方文档的 AI 总结，建议有时间的可以读一遍原文，写得更详细：Best practices

一、实践出真知

立足真实专业知识： 不要仅依赖大模型的通用知识。你应该给出特定领域的专业知识、API 接口、边界情况和项目规范，而不是泛泛而谈的内容。
从实际任务中提取： 先在对话中手动完成一次任务，记录下有效的步骤、你做出的修正、输入输出格式以及你补充的特定上下文，再将其转化为skill。
合成项目产物： 利用现有的内部文档、运行手册、API 规范、代码审查评论和版本控制历史来合成skill，这比通用指南更具实战价值。
通过实际执行不断改进： 在真实任务中运行skill，阅读执行痕迹（Traces），针对误报或低效步骤进行迭代优化。

二、合理使用上下文

只补充 AI 缺失的知识： 专注于项目特定的规范和非显而易见的边界情况。不要浪费 Token 解释 AI 已经掌握的基础知识（如 HTTP 工作原理）。
设计内聚的单元： skill应该像函数一样，封装一个连贯的工作单元。范围太窄会导致频繁加载多个skill，范围太广则难以精准触发。
保持适度细节： 简洁、分步骤的指导配合示例效果最好。避免详尽但冗长的文档，以免干扰 AI 提取关键信息。
采用渐进式披露： 核心指令保持在 500 行 / 5,000 Token 以内。将详细的参考资料放在独立文件中，并告知 AI 何时去读取它们。

三、该放的放、该收的收

匹配精确度与脆弱性： 对于有多种可行方法的任务，给予 AI 自由度；对于流程固定、容易出错的脆弱操作，指令必须具有强制性。
提供默认值而非菜单： 明确推荐一个默认工具或方法，而不是罗列一堆等价选项让 AI 自选。
注重流程而非结果陈述： 教会 AI “如何处理一类问题”的通用方法，而不是针对某个具体实例的死板指令。

四、高效指令的常用模式

设置注意事项： 列出那些违反直觉的环境特定事实（例如：某数据库表使用软删除、不同服务间 ID 名称不一致等）。
使用输出格式模板： 提供具体的 Markdown 或结构化模板，AI 对具体结构的模式匹配能力非常强。
工作流检查清单： 使用显式的复选框帮助 AI 跟踪多步骤任务的进度，防止跳步。
建立验证循环： 要求 AI 在完成工作后运行验证脚本或对照参考清单进行自查，修复问题后再提交。
计划-验证-执行： 对于破坏性操作，要求 AI 先生成计划，经校验无误后再执行。
打包可重用脚本： 如果发现 AI 在反复重新编写相同的逻辑（如绘图、解析格式），应将其固化为测试过的脚本并打包在skill中。

如何让你开发的 Agent 支持 Skill

首先想清楚两个问题：

skill 放在哪里：这取决于你的 Agent 运行在云端还是本地。如果是本地，skill 放在用户目录，用文件系统来读取。如果是云端，skill 放在云存储上，用 API 来读取。
大模型如何访问 skill 中的内容：如果大模型支持原生 Function calling，直接用 file-reading 能力读取 skill.md。如果不支持，只能考虑往提示词中注入或者自己开发专有工具来拼接。

总共分为5步：

步骤一：发现 skills

扫描项目级和用户级的 .agents/skills 目录，读取所有 skill 的 name 和 description。

范围	路径	用途
Project	`<project>/.<your-client>/skills/`	客户端路径
Project	`<project>/.agents/skills/`	项目路径
User	`~/.<your-client>/skills/`	客户端路径
User	`~/.agents/skills/`	用户路径

步骤二：转换 SKILL.md 文件

将提取出来的 name 和 description 以及对应 SKILL.md 的路径，转换成特定格式（JSON或XML等）。

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extract PDF text, fill forms, merge files. Use when handling PDFs.</description>
    <location>/home/user/.agents/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>Analyze datasets, generate charts, and create summary reports.</description>
    <location>/home/user/project/.agents/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>

步骤三：告诉大模型可用的 skills

将转换后的可用 skill 列表信息注入到大模型的系统提示词或工具描述字段中，并给出一段指导提示词告诉大模型这些是什么，如何用。例如：

文件读取方式的指令：

以下 skills 为特定任务提供专门的指令。
当任务与 skill 的描述匹配时，在继续操作前，请使用 file-read 工具读取对应 skill 的 SKILL.md。
当 skill 引用相对路径时，请根据该 skill 的目录（SKILL.md 的父目录）解析它们，并在工具调用中使用绝对路径。

专用工具方式的指令：

以下 skills 为特定任务提供专门的指令。
当任务与 skill 的描述匹配时，请通过调用 activate_skill 工具（传入 skill 名称）来加载其完整指令。

当没有可用的 skill 时，不要向大模型披露 skill 的存在，否则会误导模型。

当压缩上下文时，不要清理 skill 的内容，否则模型可能会正常运行，但失去这个 skill 的能力。
当一个 skill 重复激活时，可以做去重，避免浪费 token 。
在一些多 agent 的实践中，也可以把 skill 放到 subAgent 中单独执行，保持主 agent 的简洁。

参考：

官方文档：How to add skills support to your agent