什么是技能（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