说到 Agent Skills，很多人第一反应是"这不就是给 Claude 加个插件吗"。表面上看确实有点像，但真把它当插件理解，后面用起来会踩一堆坑。我在实际项目里测过几版之后，发现它的架构思路和传统的 prompt 注入、Function Calling 都不一样，更适合把它理解为"模型主动按需领取的说明书+工具箱"。
这篇文章我打算把它拆成两层来聊：先讲清楚 Agent Skills 到底是什么、和 MCP 那些概念怎么划分边界，再带你把官方全套技能过一遍，最后手把手写一个自己的 Skill。老实说，Claude 官方在 2025 年 10 月推出这个功能之后，社区里讨论热度一直很高，但真正把架构原理讲明白的资料并不多。这篇我更想以自己实测的视角，给你一套能直接上手的理解框架，顺便把容易翻车的细节都标记出来。
如果你正在做 Agent 应用、Claude Code 的自动化工作流，或者单纯好奇"模型怎么学会一个新技能"，这篇文章应该能帮你省不少试错时间。
1. Agent Skills 到底是干嘛的
1.1 一句话讲清楚
Agent Skills 是让 Claude 通过 API 或 Claude Code 获得某项专项能力的机制。每个 Skill 由 Annotated 托管，本质上是一个带SKILL.md说明文件的技能包，里面装着完成某类任务所需的指令、代码脚本和资源文件。模型在执行任务时，如果判断需要某个技能，会主动向系统请求加载它，而不是系统在每次对话里硬塞给它。
这句话读起来不长，但有两个关键点容易被忽略：
第一，"主动请求"意味着加载时机由模型决定。这跟传统"把所有工具描述一次全塞进上下文"的做法有本质区别。上下文窗口更干净、token 占用更少，模型也能更精准地把技能用在刀刃上。
第二，SKILL.md 是一份说明书，不是 prompt。它教模型"怎么用这个技能"，包括输入输出格式、边界条件、常见坑，而工具的具体执行逻辑在配套脚本里。说明书写得好不好，直接决定模型能不能正确触发和正确使用。
1.2 和 MCP、Function Calling 有什么不一样
这个概念是我觉得最值得先聊清楚的。社区里经常有人把 Agent Skills、MCP、Function Calling 混在一起，但它们其实是三个层次的东西。
Function Calling 是模型输出一个结构化调用请求，由你这边自己执行逻辑，再把结果拿给模型。它解决的是"模型怎么跟外部函数对话"的协议问题，也就是模型负责决策，执行还是靠你自己的代码。
MCP 是给 Agent 提供外部工具和数据访问的统一协议。它解决的是"Agent 怎么接入外部系统"的问题，比如连数据库、查内部 API、访问第三方服务。一个 MCP server 可以托管很多工具，Agent 通过标准化的接口调用它们。
Agent Skills 解决的是另外一件事：把"完成某一类任务的方法论"打包进去。PDF 解析怎么做、PPT 怎么重新排版、视频怎么批量剪辑，这些复杂的、多步骤的、需要特定代码库支持的技能，打包成 Skill 之后，模型能在几秒钟内学会，而且用完就释放，不影响后续上下文。
用个不那么精确但很好懂的类比：Function Calling 是给模型递电话，MCP 是给模型配一个能随时拨号的通讯录，Agent Skills 则是直接给模型发了一本"岗位培训手册+工具箱"。三者互补，不是替代关系。
2. 架构原理拆开看
2.1 一个 Skill 的包结构
一个标准的 Skill 包，通常包含三类东西：一份SKILL.md、若干辅助脚本、若干资源文件。目录结构大概是这样的：
my-skill/ ├── SKILL.md ├── scripts/ │ ├── process.py │ └── utils.py └── assets/ ├── template.docx └── font.ttfSKILL.md是整个技能包的入口，也是模型最先读取的文件。它的头部有一小段 YAML frontmatter 格式的元信息，包含name（技能名）和description（技能描述），下面就是正文。正文里写清楚这个技能解决什么问题、在什么情况下用、输入输出是什么格式、有哪些限制和注意事项。
脚本和资源可有可无，取决于技能复杂度。比如一个简单的"把 Markdown 表格转成 CSV"技能，可能只需要 SKILL.md 里几行说明就够了；但一个"解析 PDF 并导出结构化数据"的技能，往往需要配合特定 Python 库去完成。
2.2 模型怎么“发现”技能
模型不是预先知道所有技能的全部内容，它只会在系统层面看到一份"技能清单"。
开发者在 API 调用时通过skills参数声明可用的技能列表，Claude Code 里则是通过--skills参数或配置文件声明。这个列表里每个技能项只有名称和描述，没有完整实现。模型在思考过程中，会根据当前任务的语义去判断"哪个技能描述与当前需求匹配"。
这里有个很关键的机制：技能描述的质量直接决定模型触发技能的成功率。描述写得太泛，模型可能在不需要时乱触发；写得太窄，模型该用时又想不到。官方最佳实践是"描述要覆盖使用场景、触发条件、不适用情况"，最好举一两个具体例子。
2.3 加载与服务端注入的流程
整个加载流程可以拆成四步：
- 请求发起时携带技能清单（名称+描述）。
- 模型在推理过程中决定"我需要用某个技能"。
- 系统端收到模型的加载请求后，把对应的
SKILL.md全文和必要的上下文注入到对话中。 - 模型按照技能说明，调用脚本或执行代码，完成任务。
这个流程在设计上有个微妙之处：加载前只暴露技能名和描述，加载后才注入完整内容。好处前面说了，省 token、省上下文；坏处是模型对技能的"预判"完全依赖 description 质量。从架构上看，Agent Skills 本质上是一个"按需加载的上下文管理系统"，只是它的加载单位不是普通文档，而是可执行技能包。
2.4 命名冲突与安全边界
有人的地方就有江湖，技能多了也会打架。
官方实现里，如果多个技能包使用了相同的name，系统会报错而不是静默选择其中一个。这其实是个很有远见的设计：模型并不知道"哪个是对的"，如果静默加载了错误版本，后续行为就是全错。宁可失败，也不容忍歧义。
安全边界方面，官方 Skill 是托管在 Annotated 服务端的，所以模型加载技能包时拿到的内容是受控的。对于非官方的 marketplace 技能，就要自己注意审查了——技能内容本质上是可以执行的 Python 脚本，等于把代码交给了模型去调用。如果你的 Agent 运行在管理员权限环境，一个恶意的 Skill 金额可能带来代码注入风险。这点后面实操部分我再细说。
3. 全系列速览：官方技能库扫一遍
3.1 文档处理系：PDF、DOCX、PPTX、XLSX
这是官方最早推出、也是被社区用得最多的一个系列。它们解决的都是现代办公场景里极其高频的问题，而且都是你直接用"通用 Claude"很难做好的事。
PDF 技能：提取文本、表格、图表数据，并能输出成 JSON、CSV 等结构化格式。实测下来，对于扫描版 PDF 它也能处理（依赖底层 OCR 库），排版复杂的双栏论文也能相对正确地还原阅读顺序。不过我建议拿到结果后仍要抽查——表格跨页、多级标题混排的场景还是会出错。
DOCX 技能：读写 Word 文档。除了基础文本，还能提取表格、图片、超链接、样式信息。常见的用法是批量从多个 docx 里抽取关键字段，或者按照模板批量生成结构化文档。注意它对.doc老格式支持不好，老文件先转成.docx再处理。
PPTX 技能：读和改 PowerPoint。实际工作中我用过它做两件事：一是把几十页的 PPT 演讲者备注整理成摘要，二是把零散的会议记录自动排成一份可交付的 PPT 提纲。它可以读取母版和动画信息，但不能完全保留复杂的自定义版式，交付前还是要人工过一遍视觉细节。
XLSX 技能：处理 Excel 的高频操作。数据清洗、列匹配、多表合并、公式计算都能做。我最常用的场景是"把三个报表按关键字段拼成一张总表"，它比手写 pandas 脚本效率高不少，因为模型能自己根据表头语义推测合并逻辑。
这四个文档技能对任何做数据整理、内容运营、咨询分析的人来说都是刚需。它们的共同特点是：如果不用 Skill，靠普通对话让模型"写一段代码来处理文件"，每次都要重复描述需求、调试代码、确认输出格式，而用了 Skill 之后是一次性拿到完整方法。
3.2 内容生成与创意系：SVG、图像工具、PDF 报告
这个系列偏"生成创造"方向。
SVG 技能：基于矢量路径生成图标、插画、数据可视化的 SVG 图形。它的价值在于，SVG 本身就是代码，模型可以直接生成、修改、优化。我试过让 Claude 用这个技能画一个多层的技术架构图，效果相当不错，而且可以反复微调细节而不失真。这里有个真实的体验：模型对 SVG 语法掌握得很好，但复杂贝塞尔曲线的美感还是一言难尽，建议做"概念草图"用，做正式产品图还得人来收拾。
图像工具技能：基于 Pillow 等图像库做裁剪、格式转换、滤镜、拼图、加文字等操作。它更像是一个"图像批处理工具箱"，不追求生成艺术效果，但做自动化处理非常稳。比如批量压缩产品图、统一加水印、切出缩略图，一条龙搞定。
PDF 报告生成技能：这不是"读 PDF"，而是"造 PDF"。你给数据，它生成排版良好的 PDF 报告。底层用的类似 FPDF2 方案，可以定制字体、颜色、表格样式，中英文混排也没问题。这个技能特别适合自动生成日报、周报、测试报告、账单这类"结构化程度高，重复性强"的文档。
3.3 自动化与联网系：视频编辑、网络搜索
视频编辑技能：基于 ffmpeg 的批量视频处理能力。裁剪、拼接、转码、提取音频、加字幕、调节速，它都能做。我实测过用它把一段长视频按静音片段自动切分成多个短视频，效果很理想。但要注意，它本身没有"基于画面内容的智能理解"，所谓剪辑更多是"按时间轴的规则化处理"，你需要给它明确的规则参数。
网络搜索技能：这个解决的是 Claude 训练数据截止之后的新鲜信息问题。它通过搜索 API 抓取网页内容，再返回给模型分析。值得留意的是：模型只拿搜索结果做上下文，并不能像浏览器那样交互浏览复杂页面。对"查最新版本的文档"、"找某个产品的当前价格"这类场景很顺手，但想让它"打开页面点击某个按钮"，那就是另一回事了。
官方技能远不止这些，而且还在陆续扩充。整体观察下来，官方选技能的方向非常务实：不追求"什么都能干"，而是挑"确定性的、代码可复现的、操作复杂度高但规则明确的"任务做技能化。这也侧面说明，Agent Skills 最适合的场景是"把成熟的方法论固化下来，让模型随手可用"。
4. 实操手记：从零定义一个自己的 Skill
4.1 目录与最小文件结构
先上手写一个极简的 Skill，感受一下整个链路。以"把 Markdown 表格批量转成 JSON"为例：
table-to-json/ ├── SKILL.md └── scripts/ └── md_table_to_json.pySKILL.md长这样：
--- name: table-to-json description: 将 Markdown 格式的表格转换为 JSON 数组。适用于数据抽取、格式转换等场景。当用户给出包含 markdown 表格的文本或文件并要求数据结构化时使用。不适用于 HTML 表格、Excel 文件。 --- # 用途 将 Markdown 文本中的表格提取为 JSON 数组。每张表格输出一个对象数组，字段名为表头，值为每行内容。 # 输入 - markdown 文本或 .md 文件路径 # 输出 - JSON 数组，格式为 [{header: value}, ...] - 如果文本包含多张表格，输出二维数组 # 注意事项 - 仅处理标准管道符表格，不处理 HTML table - 表头合并、嵌套表格等情况不适用，直接报错优于瞎转换 - 如在脚本执行过程中发现输入不是 Markdown 表格，立即告知用户配套的md_table_to_json.py就是一段普通 Python 脚本，用标准库就行，这里不展开贴了。写完这两个文件，一个 Skill 就成型了。
写完之后你可能会想："就这么点东西？"对，这就是它的精髓。Skill 的本质不是复杂工程，而是把"模型已经知道怎么做、但不够稳定熟练"的事情，用文档+代码变成"稳定熟练"。
4.2 SKILL.md 怎么写，模型才愿意用
这是整个实操里最有技术含量的一步。我调试了很多轮之后总结出三条心得：
描述里要有触发条件和反触发条件。只写"把表格转成 JSON"是不够的，模型在自己庞大的能力库里对比时无法确定什么时候该用你。要写明"当用户给出包含 markdown 表格的文本并要求结构化时使用"，同时写清"不适用于 HTML 表格、Excel 文件"——反例能帮模型排除错误选项。
正文要模板化，越细越好。不要只写"转换表格"，要写清楚输入格式、输出格式、失败时怎么办。模型在执行时相当于"照着说明书办事"，说明书写得越像操作手册，执行越稳定。
一个 Skill 只做一件事。如果它既做表格转换又做图片压缩，模型的触发判断会混乱。单职责原则在这里比在软件工程里更重要，因为模型没有"路由层"，它只能靠描述里的关键词做触发决策。
4.3 在 Claude Code 里怎么加载自己的 Skill
写完 Skill 目录后，在 Claude Code 里加载非常直接。命令行下：
claude --add-skill ./table-to-json或者把多个技能放到统一目录，通过配置文件加载。你还可以把 Skill 打包进 marketplace 分发给团队，通过--install-marketplace命令安装。
我建议在项目初始化时就声明好技能集，而不是临时添加。这样 Claude Code 在每次会话开始时就知道"哪些技能可用"，模型才能跑得更顺。临时添加不是不行，只是模型在会话中途可能没有机会重新评估技能清单，触发率会低很多。
4.4 API 调用时的参数写法
如果你在自建 Agent 应用里用 Agent Skills，API 调用的写法如下：
{ "model": "claude-3-7-sonnet-latest", "skills": ["table-to-json", "pdf"], "messages": [ {"role": "user", "content": "这个 md 文件里的表格转成 json"} ] }通过skills参数声明可用技能，然后正常发消息。模型自行决定是否加载、加载哪个。你在服务端不需要额外处理加载逻辑，Annotated 的服务端会完成注入。
有一点要注意：skills参数声明的是"允许使用的技能池"，不是"强制使用的技能"。模型会根据对话语义来决定是否触发。如果你希望它"一定使用某个技能"，只能通过 prompt 显式引导，比如在系统提示词里写明"优先使用 table-to-json 技能处理表格类任务"。
5. 常见问题与避坑实录
5.1 技能描述写不好，模型就是不触发
这是最常遇到的问题：技能明明写好了，模型就是不用。
排查思路很简单，先检查 description 里的场景关键词和用户提问是否匹配。比如你的描述里只有"表格转 JSON"，而用户说的是"帮我整理这个 markdown 里的数据"，模型可能就不会联想到。把"整理、结构化、抽取、导出"这类语义相近的词都写进描述里，触发率会明显提升。
再检查描述是否过于"广告化"。有些人在 description 里堆"高效、强大、一步到位"这类形容词，对模型识别毫无帮助，反而稀释了有效语义。description 里只写"什么时候用、处理什么类型的数据、产出什么格式"，是最稳的。
5.2 脚本跑不起来的常见原因
Skill 里带 Python 脚本时，最容易出问题的是依赖环境。官方托管的技能有受控的依赖环境，但你自定义的 Skill 跑在本地环境，Python 版本、库版本、系统依赖不一样，脚本就可能直接挂。
我的习惯是：在 SKILL.md 里明确标注依赖项和安装命令，并且在脚本开头做依赖检测，缺了就给出清晰的报错提示，而不是让模型面对一个默认的 ImportError 自己猜。另外，路径问题也很常见——脚本里尽量使用相对路径，并且让模型知道当前工作目录是什么。否则模型自己生成的待处理文件在哪，脚本可能在另一个目录找文件。
5.3 选型建议：Skill 还是 MCP 还是普通工具
做 Agent 应用时，工具选型可以按这个思路判断：
需要跟外部系统做身份认证、需要连数据库、需要访问私有服务，走 MCP。MCP 的核心价值是"连接"，它的标准化协议适合开放的、需要双方握手的数据交换场景。
需要多步骤的方法论、需要私有代码库支持、需要稳定的输出格式，走 Skill。尤其是那些"你用人肉做也能做、但很繁琐且结果不稳定"的任务，技能化之后收益最大。
只是一次性的简单调用，直接 Function Calling 或普通代码调用即可。没必要为一个"算两个数"的功能包一层 Skill，那是在给自己增加维护成本。
这三者不是互斥的。一个成熟的 Agent 应用完全可以同时挂 MCP server 连接数据库，配几个处理文档的 Skill，再用 Function Calling 处理那些零散的单次交互。
5.4 团队治理与团队协作里的几个坑
最后聊点实际工程中容易忽略的。Agent Skills 技术门槛不高，但治理门槛不低。团队里一旦开始大规模用 Skill，下面这几个问题马上会冒出来：
技能版本管理。Skill 也是代码，得进 Git 仓库、打版本标签、写变更记录。否则你没法知道"上周客户端用的 PDF 技能到底是哪一版"，出了问题都没法回溯。
技能冲突。前面说过，两个人各写了一个同名技能，Claude Code 会直接报错。所以团队里最好有个技能命名规范，比如按前缀区分业务归属，并且搞一个集中的技能仓库或 marketplace。
权限边界。Skill 本质是让模型执行本地代码，所以权限控制要做细。我的建议是：自定义 Skill 运行在受限用户下，不要给它 root 权限；涉及外部网络请求的 Skill，要在描述里明确标注会联网，让用户知情。
成本控制。虽然 Agent Skills 的按需加载机制省了上下文 token，但技能执行过程中模型的推理轮数并不少。复杂的技能任务，单次调用的成本可能比普通对话高几倍。做精细化运营的话，建议在日志里记录每个技能的触发次数和耗时，找出那些"触发频率高但回报低"的技能做优化或下线。
从整体体验来看，Agent Skills 最大的价值不是"多了一个工具"，而是把 Agent 的能力边界从"对话"推进到了"熟练工种"。以前让模型做 PDF 解析、PPT 整理这类多步骤任务，你得反复调试、逐字讲需求；现在一个技能包扔过去，模型就能照着手册把事情做了，而且做得有模有样。我个人比较看好后续社区会把各种成熟的工作流都沉淀成 Skill，到时候开发 Agent 应用拼的就不再是"怎么调模型"，而是"沉淀了多少高质量技能包"。如果你手头正好有一些反复在做、步骤明确、产出可预期的任务，找个时间把它技能化，可能比继续调 prompt 划算得多。
