什么是技能(skill)
约 2129 字大约 7 分钟
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 的最佳实践
一、 Skill 的核心来源
- 立足真实专业知识: 不要仅依赖大模型的通用知识。你应该给出特定领域的专业知识、API 接口、边界情况和项目规范,而不是泛泛而谈的内容。
- 从实际任务中提取: 先在对话中手动完成一次任务,记录下有效的步骤、你做出的修正、输入输出格式以及你补充的特定上下文,再将其转化为skill。
- 合成项目产物: 利用现有的内部文档、运行手册、API 规范、代码审查评论和版本控制历史来合成skill,这比通用指南更具实战价值。
- 通过实际执行不断改进: 在真实任务中运行skill,阅读执行痕迹(Traces),针对误报或低效步骤进行迭代优化。
二、 优化上下文使用
- 只补充 AI 缺失的知识: 专注于项目特定的惯例和非显而易见的边界情况。不要浪费 Token 解释 AI 已经掌握的基础知识(如 HTTP 工作原理)。
- 设计内聚的单元: skill应该像函数一样,封装一个连贯的工作单元。范围太窄会导致频繁加载多个skill,范围太广则难以精准触发。
- 保持适度细节: 简洁、分步骤的指导配合示例效果最好。避免详尽但冗长的文档,以免干扰 AI 提取关键信息。
- 采用渐进式披露: 核心指令保持在 500 行 / 5,000 Token 以内。将详细的参考资料放在独立文件中,并告知 AI 何时去读取它们。
三、 精确校准控制力
- 匹配精确度与脆弱性: 对于有多种可行方法的任务,给予 AI 自由度;对于流程固定、容易出错的脆弱操作,指令必须具有强制性。
- 提供默认值而非菜单: 明确推荐一个默认工具或方法,而不是罗列一堆等价选项让 AI 自选。
- 注重流程而非结果陈述: 教会 AI “如何处理一类问题”的通用方法,而不是针对某个具体实例的死板指令。
四、 高效指令的常用模式
- 设置注意事项 (Gotchas) 模块: 列出那些违反直觉的环境特定事实(例如:某数据库表使用软删除、不同服务间 ID 名称不一致等)。
- 使用输出格式模板: 提供具体的 Markdown 或结构化模板,AI 对具体结构的模式匹配能力非常强。
- 工作流检查清单: 使用显式的复选框帮助 AI 跟踪多步骤任务的进度,防止跳步。
- 建立验证循环: 要求 AI 在完成工作后运行验证脚本或对照参考清单进行自查,修复问题后再提交。
- 计划-验证-执行: 对于破坏性操作,要求 AI 先生成计划,经校验无误后再执行。
- 打包可重用脚本: 如果发现 AI 在反复重新编写相同的逻辑(如绘图、解析格式),应将其固化为测试过的脚本并打包在skill中。
这一节使用 AI 总结了官方文档,建议有时间的可以读一遍原文:Best practices
