说到 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. 实操手记从零定义一个自己的 Skill4.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 SkillsAPI 调用的写法如下{ 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 划算得多。 
长河君 · 2026/11/3 7:47:02 · 阅读 1.2k Agent Skills 与 MCP、Function Calling 辨析及实操指南
说到 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. 实操手记从零定义一个自己的 Skill4.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 SkillsAPI 调用的写法如下{ 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 划算得多。