★ FEATURED ARTICLE 最近社区里到处都在刷agent-skills这个词。尤其那篇《Claude Agent Skills: A First Principles Deep Dive》出来之后一堆做 Agent 开发的朋友开始反复问同一个问题Skills 到底是什么跟 Tools 有什么区别为什么我模型接得挺顺还是觉得 Agent 干不了正经活其实不光新手很多已经跑通 demo 的团队也会在这个概念上卡壳。我当时也是花了不少时间才真正搞明白Agent Skills 不是多封装一层 API而是把解决某一类问题的方法本身装进 Agent 手里的一个文件包。这篇文章我准备从第一性原理出发结合我实际开发 Agent 项目时踩过的坑把 skill 的底层逻辑、主流框架的落地机制、完整开发流程以及生态里怎么找、怎么装、怎么避坑一次讲透。无论你是刚接触 Agent 的前端开发、正在折腾自己的技能库的独立开发者还是已经做多 Agent 编排的团队都能在这里找到可以直接上手的东西。1. Skill 的底层逻辑给 Agent 装上一套肌肉记忆1.1 那个让所有人困惑的问题模型都那么强了为什么还要 Skills先说一个很反直觉的现象。我身边不少朋友在做 Agent 项目时标配思路是ChatGPT/Claude 这类大模型已经这么聪明了我只要把工具接上它什么任务都能干。于是他们给 Agent 接了一堆 API然后让它自由发挥。结果呢Agent 确实能干活但每次干活的路径完全不一样质量忽高忽低而且同一个错误会反复犯。就拿生成短视频分镜脚本来说。今天你让 Agent 按镜头号 景别 运镜 台词 备注的结构输出明天它可能就给你输出成场景描述 画面细节 台词的另一个格式。模型本身的能力没有变变的是它对分镜脚本这个词的理解方式。这个问题的根源在于大模型的推理是一次性的它没有上一回我是怎么把这件事做好的这种记忆。你要它稳定输出就得把做这件事的套路沉淀下来。Skills 解决的就是这个问题。它把针对某类任务的执行路径、判断标准、输出格式、常用代码片段封装成一个独立的模块。Agent 在遇到对应场景时不再从零开始推理而是直接读取这套已经验证过的方法论按部就班地执行。说得直白一点模型是大脑Tools 是手脚而 Skills 就是大脑里逐渐形成的肌肉记忆。1.2 从第一性原理拆解Reasoning、Tools 与 Skills 的分工很多人第一次看到 Agent Skills 这个名字会自然把它归类成又一种工具调用方式。这个理解偏差很大。我们回到第一性原理把 Agent 做一件事到底需要什么拆开看。首先一定有 Reasoning这是模型本身的推理能力负责理解用户意图、拆解任务、决定下一步做什么。然后是 Tools它负责执行具体的原子操作比如查数据库、调外部接口、执行一段搜索。但只有这两层会出现一个明显的问题模型知道要写分镜脚本也知道自己可以调用脚本、搜索参考案例但它不知道一份好的分镜脚本应该按照什么顺序、包含哪些要素、在每个环节注意什么。它必须现场摸索。Skills 把现场摸索变成按图索骥。一个 Skill 本质上是三个部分的组合一段写在文档里、专门给模型看的过程性知识一组可调用的辅助脚本以及一些模板或参考资产。它们被放在同一个目录下由 Agent 按需加载。这样做带来的效果是正确率明显提升输出格式稳定token 消耗下降因为模型不用再反复试错。在架构上我给 Agent 设计能力层时一直遵循一个原则让模型做决策把执行和经验外置。Tools 提供的是我能做什么的选项Skills 提供的是这一类事该怎么做的路径。两者不是一回事也无法互相替代。1.3 SKILL.md 的本质一份写给语言模型读的操作手册一个 Skill 目录里最关键的文件是SKILL.md这也是 Agent Skills 命名格式的核心。它本质上是一份操作手册但阅读对象不是人而是语言模型。这里面有个很多人没意识到的设计点大模型对文本的理解能力远远强于对代码的理解能力所以与其把执行逻辑写死在程序里不如把流程和经验写成一篇文章让模型读完后自行执行。一份合格的SKILL.md通常包含两部分。前面是 YAML 格式的 frontmatter也就是元信息写清楚这个 Skill 的名字和 descriptiondescription 是给模型判断我这个场景要不要用这个 Skill的关键依据。后面是正文部分详细描述这个任务的完整工作流、每一步的注意事项、输入输出的规范、常见错误的规避方式。比如写分镜 Skill正文里面就要讲清楚拿到需求之后第一步做什么第二步做什么景别怎么划分运镜怎么衔接一个镜头包含哪几个字段输出格式是什么。这些内容是模型自己很难凭空推理出来的写上之后它就能直接照着做。我始终觉得理解SKILL.md是理解整个 Agent Skills 概念的分水岭。一旦意识到技能的本质是给模型写操作手册你就会明白为什么 Skills 能显著提升 Agent 的表现也就会明白为什么写不好这份文件Skill 就形同虚设。2. Tools、Workflow、Skills三者的边界与选型判断2.1 一个原子动作一套完整打法很多教程喜欢把 Tools 和 Skills 放在一张表里做对比但真正做项目时边界往往没那么好划。我自己常用一个类比Tools 是工具箱里的锤子和螺丝刀Skills 是怎么把一张桌子组装好的完整流程。你不会把拧螺丝当做一个项目来管理但你要交付一张桌子靠一把螺丝刀是不够的。落到 Agent 的开发里Tools 普遍是单一、无状态的原子能力比如查询天气执行 SQL调用某个 API。Skills 则是面向一个完整交付物的能力集合它内部常常会调用多个 Tools还包含业务判断和排序逻辑。比如我做一个行业周报生成的 Skill它会先分析用户要求的行业范围再决定去搜索哪些新闻源然后筛选重点事件最后按固定模板生成周报。这个流程里每一步都需要决策不是单纯按顺序调 API 就能完成。技能目录的颗粒度也是个经验问题。颗粒度太粗一个 Skill 里塞了十几个场景模型加载之后不知道先执行哪一步颗粒度太细光是让模型判断该用哪个 Skill 就消耗了大量上下文。一般来说按一次会话可以交付完的任务划分最合适。比如生成分镜脚本是一个 Skill生成完整的短视频策划案是另一个 Skill虽然两者有重叠但不要强行合并。2.2 什么该做成 Tool什么该做成 Skill这个判断我踩过不少坑。早期做项目时我习惯把所有可能用到的函数都注册成 Tools结果工具列表动辄几十个模型经常选错工具上下文也被工具描述占掉一大截。后来我给自己定了一条判断标准这个能力是无脑执行还是需要方法论。如果这个功能只需要固定的输入和输出几乎不需要业务判断就做成 Tool。典型例子是天气查询、汇率转换、文本翻译这种输入参数明确返回值确定模型只要知道什么时候调用、传什么参数就够了。但如果这个功能需要模型根据情况做多步决策需要了解业务背景、遵循特定行业规范那就应该做成 Skill。比如写一个成功概率更高的职位 JD或者生成符合平台调性的小红书笔记这些都不能靠一个 API 完成需要模型掌握一套方法。还有一个更简单的判断方法如果你发现自己在给同一个 Tool 反复写使用说明希望它被正确调用那大概率这个能力应该升级成 Skill。因为使用说明本身就是要给模型读的过程性知识这正是 Skill 的核心内容。把它从工具描述里解放出来独立成文档反而是更清晰的做法。2.3 MCP、Workflow 与 Skills 的关系讨论 Skills 时一定会有人问那 MCP 呢Workflow 呢它们不都是干这个的吗先说 MCP。MCP 是工具接入层的协议它解决的是一堆工具怎么标准化地暴露给模型的问题。你可以把 MCP 理解成 USB 接口不管里面接的是键盘还是摄像头插口是统一的。MCP Server 里面暴露的是 ToolsSkills 则是在这些 Tools 之上多出来的一层业务方法。换句话说MCP 负责让 Agent 能用到工具Skills 负责让 Agent 知道怎么用一套工具做出一个像样的结果。两者可以共存而且实际项目中经常是配合使用的。Workflow 和 Skills 的区别更微妙。Workflow 是预先编排好的固定流程节点和分支都是人画好的模型只要按图执行就行几乎没有自由决策空间。Skills 恰好相反它提供的是方法和经验但具体路径由模型临场决定。比如一个发布文章的 Workflow 可能规定死了步骤登录、写标题、上传封面、点击发布。而一个发布文章的 Skill 只会告诉模型发布前要检查标题长度、封面比例是否符合平台要求、正文有没有违禁词然后让模型自己调用工具去完成。前者适合确定性的流程后者适合需要应变的任务。真实项目里复杂任务的正确做法往往是Workflow 搭骨架、Skills 填血肉。3. 主流 Agent 框架的 Skills 机制对比从 Claude 到 Codex 再到第三方工作台3.1 Claude Agent Skills目前最接近事实标准的那一套这一轮 Agent Skills 概念能火起来Anthropic 功劳很大。他们在 2025 年开源了anthropics/skills仓库同时发布了 Agent Skills 的设计规范直接定下了SKILL.md加辅助资源文件的目录结构。这个设计目前已经成了很多框架参照的标准包括社区里大量讨论都在围绕它展开。Claude 系框架的加载方式也比较直接。在 Claude Code 这类工具里你把 Skill 目录放进项目的.claude/skills下或者放到用户级的~/.claude/skills目录下它就能被 Agent 识别。每个 Skill 是一个独立子目录目录里放SKILL.md和所需的脚本、模板。设计者希望达到的效果是Agent 在对话过程中自动感知到相关 Skill 的存在并在合适的时机自主加载。实际体验下来有两点值得注意。第一SKILL.md的 description 写得越好Agent 的触发率越高。description 不是一个给人类看的简介它是模型判断是否调用该技能的开关。第二官方还提供了很多已经写好的 Skill 用于参考这些示例本身就是学习怎么写 SKILL.md 的好素材直接去读比看任何教程都来得快。3.2 Codex、GitHub 与其他框架的 Skills 实现OpenAI 的 Codex 也加入了这场竞赛。Codex CLI 作为命令行编程代理主打的是在终端环境里辅助完成编码任务它支持通过AGENTS.md之类的项目级配置文件来声明 Skills也可以把常用脚本和命令封装成可复用的技能。跟 Claude 那种通用工作流技能相比Codex 的 Skills 更偏向工程实践比如按特定规范写单元测试执行一轮代码审查这类。GitHub 那边的 Skills 要稍微区分一下。GitHub Skills 官方产品本身是一条交互式学习路径跟 Agent Skills 不是一回事。但社区里确实涌现了大量围绕 GitHub 工作流的 Agent 技能比如自动生成 Commit 规范、创建 PR 时自动填模板、扫描仓库里的安全配置等。这类技能被大家叫作github skills的时候指的已经是 Agent 技能库而不是官方那个学习功能。这也可以看出Skill 这个词在生态里天然适合描述Github 操作套路。除了这两家还有一批像 ReasonIX 这样的新工具也在做 skills 机制。它们的实现思路大同小异无非是目录约定和加载路径略有差异。我个人的体会是这个阶段没必要绑定某个特定框架的格式把 SKILL.md 的写法掌握好迁移到哪个平台都不会太难。3.3 第三方工作台里的 SkillsHermes Agent、ReasonIX 等生态如果你关注 Obsidian 生态大概见过 Hermes Agent。它是在 Obsidian 里跑起来的 AI 第三方工作台主打在笔记环境里调用 Agent。对这种工具来说Skills 通常会以插件工作台的形式扩展安装方式一般是在工作台配置里选择从市场安装或将下载好的 skill 包导入进去。社区里有人会把常用的写作类技能、知识整理技能做成可下载的包这类内容就经常出现在skills 下载平台的搜索结果里。这类工作台的好处是上手门槛低你不用写代码就能把别人做好的 Skill 装进自己的笔记库里。坏处是跨平台复用性差。在 Claude Code 里写好的 Skill拿到 Hermes Agent 可能结构就不兼容反过来也一样。所以我建议如果你计划积累一套属于自己的技能资产优先按通用格式写放到 Git 仓库里管理然后根据目标平台做一层适配而不是绑定某一家平台的私有格式。第三方工作台生态还带火了一个需求找技能、装技能。目前不少工具都内置了社区市场可以直接搜索并安装。这类市场里的技能质量参差不齐后面我会专门写怎么选。4. 我从零开发一个分镜 Skill的完整过程4.1 为什么拿分镜脚本练手我见过很多入门教程拿写邮件总结文档当例子说实话太简单了体现不出 Skill 的价值。分镜脚本不一样它有几个特性非常适合用来理解技能的开发逻辑首先分镜有明确的行业套路和术语比如景别、运镜、镜头编号模型不一定天然懂其次分镜的输出格式要求高适合测试 Agent 的格式稳定性最后分镜脚本生成过程中需要结构化拆解能体现出 Skill 里决策路径的价值。所以下面我就用短视频分镜脚本生成作为完整案例从目录结构到 SKILL.md 写法一步步过一遍。这个流程你学会了之后可以迁移到任何其他类型技能上比如文案类、数据整理类、自动化测试类。4.2 设计目录结构与 SKILL.md这一步决定 Agent 会不会搭理你先看整体目录结构。一个标准的 Agent Skill 目录大概长这样storyboard-skill/ ├── SKILL.md ├── scripts/ │ └── generate_storyboard.py └── templates/ └── storyboard_template.mdSKILL.md是灵魂scripts里放辅助脚本templates里放输出模板。如果你后续需要放参考素材可以再加reference文件夹。然后是SKILL.md本身。frontmatter 里的 name 和 description 是重中之重。我一直强调description 是写给模型看的触发开关要写出什么情况下用户可能想要这个东西。比如可以这样写--- name: storyboard description: 用户需要为短视频生成分镜脚本、拍摄脚本、镜头表或者需要把一段文案/口播稿拆分成具体镜头包括分析景别、运镜、时长、画面内容、台词和备注时使用。 ---注意里面要写触发场景而不是写功能概述。storyboard这个名字对模型判断没有帮助触发描述里那些分镜脚本、镜头表、拍摄脚本才是模型真正用来匹配的关键词。写不好这一段Agent 永远想不起来还有这个技能可用。正文部分要写出工作流和方法论。我实际用的分类目写法如下理解需求先识别用户提供的素材类型是文案、口播稿还是创意方向确定视频总时长。规划结构按 3-7 秒一个镜头划分信息点一个镜头只表达一个核心信息。填充镜头要素每个镜头包含镜头号、景别、运镜、时长、画面描述、台词、背景音乐/音效建议、备注。检查完整性确认脚本覆盖了所有核心信息点、没有跳景别、口播与画面不冲突。输出格式调用templates/storyboard_template.md渲染最终结果。我在正文里还会写常见错误比如景别跳跃过大会让观众感觉突兀一句台词超过两行字短视频字幕放不下这些是模型从公网数据里很难学到的高质量经验。Skill 的价值就在这里。4.3 配套脚本和模板让输出可直接落地SKILL.md负责方法论脚本负责处理需要计算和格式化的内容。我写的一个简单示例脚本会读取输入文案按句号拆分并预估每条文案的朗读时长然后输出一个分镜数据表import sys import re def parse_copy(text: str): sentences re.split(r[。\n], text) sentences [s.strip() for s in sentences if s.strip()] segments [] for s in sentences: # 按每秒钟 4-5 个字的语速估算朗读时长 duration max(3, min(7, round(len(s) / 4.5))) segments.append({copy: s, duration: duration}) return segments if __name__ __main__: text sys.argv[1] if len(sys.argv) 1 else for i, seg in enumerate(parse_copy(text), 1): print(f镜头{i:02d} | 时长{seg[duration]}s | 台词:{seg[copy]})模板文件也很重要它负责约束输出格式让 Agent 不用每次重新发明表格格式。我会在模板里预设一个镜头表包含景别、运镜、画面内容等列让 Agent 在 markdown 表格里快速填充。这样既能提升输出稳定性也方便后续直接复制到拍摄团队手里使用。4.4 安装、触发测试与迭代写完 Skill 之后把它放到执行环境里。以 Claude Code 为例在项目根目录创建.claude/skills/storyboard/把整个目录放进去重启会话让工具加载新技能。如果你用的是 Codex通常是通过项目配置文件声明 skills 路径。这些都是基本操作更重要的是后面的测试环节。我最常用的测试方式是一组差异化输入第一给出完整的口播稿看它能不能正确拆分第二只给出一个主题词看它能不能在信息不足时主动询问时长和风格偏好第三故意给很长的文案看它输出会不会超出模板限制。测试时不要只看最终结果要观察模型的推理过程看它有没有真正读取 SKILL.md还是假装在执行、完全忽略了你写的方法。第一次迭代往往会发现两个问题description 写得不够宽导致特定输入下不触发或者正文步骤太理想化模型执行到一半发现信息缺失。这两个都很正常。改一下描述补上当用户没有提供完整信息时先提问这类兜底逻辑再跑一轮测试效果会立刻不一样。5. Skills 怎么找、怎么装、怎么挑从官方市场到社区仓库5.1 常见的 Skills 来源与下载平台现在 Agent 生态里找技能渠道已经不少了。GitHub 是最大的去处很多公司和开发者会把自己的 skill 仓库开源Anthropic 官方就有专门的 skills 仓库。社区里像 Superpowers Skills 这样的合集项目也很火把写作、编程、知识管理等领域的一大批技能打包成可安装套件。除此之外各种框架和第三方工作台基本都有自己的市场Hugging Face 这类模型社区也开始出现专门的 skills 区。我自己找技能的顺序一般是官方仓库、高星开源合集、市场搜索最后才是个人博客分享。来源特点适合场景官方开源仓库格式规范、示例质量高学习写法、直接使用基础技能社区合集覆盖面广、安装方便快速搭一套技能库工作台内置市场即搜即用、更新及时日常轻量使用个人仓库领域垂直、可能缺少维护参考思路、按需改造5.2 安装与更新的通用操作虽然不同平台细节不一样但安装 skill 的底层操作是大同小异的。Git 类安装最通用把仓库 clone 下来或者单独拿某个目录放进对应框架的 skills 路径下面然后重启 Agent 会话让它重新加载。下载 zip 包的方式也一样解压后放到位即可。我自己常用一条检查链先确认目录结构是不是标准的 SKILL.md 加资源文件再确认文件名和内部引用的脚本路径是否匹配然后打开 SKILL.md 看 frontmatter 的 description 是否清晰。这三步做完再放进去能少踩很多坑。很多安装后不生效的问题不是框架兼容问题而是目录多包了一层比如把storyboard-skill外层文件夹直接复制进去导致框架找不到子目录里的 SKILL.md。更新起来也麻烦一些。社区技能的迭代不像软件那样有版本号体系大部分人直接重新 clone 覆盖。如果你在某个技能上做了本地修改覆盖之前记得先备份或 fork不然下次更新会把你的定制冲掉。5.3 选型避坑我见过太多烂 Skill 了Skills 生态火起来之后明显开始出现低质量内容。最常见的几个坑我逐一说给你听。第一个坑是 description 写得一塌糊涂。要么太宽帮助用户完成各种任务模型基本上每次都会误触发要么太窄只有特定的几个词能触发实用性大打折扣。拿到一个 Skill先看 description 能不能精确描述它负责的场景就基本能判断其质量。第二个坑是金玉其外败絮其中。目录结构和文档都做得像模像样实际脚本却到处是硬编码路径换一台机器根本跑不通。遇到这种情况优先选择只依赖标准库、外部 API 有明确鉴权配置的技能。第三个坑是懒人包陷阱。有的合集把几十个技能打包在一起装起来确实省事但每次使用时都会把所有技能描述塞进上下文白白吃掉大量 token。安装的时候挑自己需要的装不要整个合集全塞进去。最后提醒一句来源不可靠的技能包不要直接运行里面可能混着恶意指令。这个话题我下面细说。6. 多 Agent 场景下的 Skills 编排与安全边界6.1 多 Agent 架构下 Skills 的共享与隔离项目一旦进入多 Agent 阶段Skills 的编排问题就会浮出水面。最常见的做法是主 Agent 加子 Agent架构一个编排 Agent 负责理解总任务拆分后派发给不同子 Agent。Skills 在这种情况下有两种放置策略一种是全局共享技能库所有子 Agent 都能加载另一种是每个子 Agent 挂自己的私有技能。全局共享的好处是复用率高写一个分镜 Skill策划 Agent 和市场 Agent 都能用。坏处是上下文开销变大而且可能造成职责混乱比如客服 Agent 莫名其妙加载了一个代码审查技能。我现在比较推荐混合策略把通用的、跨角色技能放全局共享比如总结归纳文档格式化把领域专属技能放对应 Agent 的私有目录比如安全测试 Agent 专属的漏洞扫描技能就不应该让内容生成 Agent 看到。编排层面的问题更实际。多 Agent 运行时谁来决定某个子 Agent 用哪个技能我建议让编排层只负责分配任务把选择技能这件事完全交给子 Agent 自己去判断通过技能描述决定。子 Agent 的上下文里只注入它可能用到的技能而不是全部技能的描述这样既能省 token也能降低误用概率。6.2 不要忽视 Skill 的安全问题Skills 看起来只是一堆文档和脚本但它的执行主体是 Agent一个能调用各种外部工具的智能体。这意味着 Skill 本身可能成为攻击入口。主要风险有两类一类是提示注入恶意构造的描述文字诱导 Agent 执行非预期操作另一类是脚本层面的风险比如下载下来的 python 脚本里藏了危险的系统指令。我有几条习惯性的安全策略不算复杂但非常有效。第一技能包里出现内联 base64 编码或者大量十六进制字符串的直接放弃。第二运行任何从第三方获取的脚本之前先打开看一遍重点关注涉及网络请求、文件删除、系统命令执行的部分。第三给 Agent 的运行环境做权限隔离尽量在容器里跑Skill 里的脚本默认没有访问主系统关键目录的权限。这不是小题大做Agent 领域安全事故里相当一部分就是恶意技能或提示注入引起的安全会越来越成为这块的核心竞争力。6.3 我的实操心得三次踩坑换来的三个原则最后分享几条我在真实项目里踩坑踩出来的经验。第一个原则一个 Skill 只解决一个问题。我最早写过一个大而全的内容创作技能又是写文案又是做图又配口播结果模型加载后经常搞不清当前该执行哪部分触发率和执行效果都很差。拆开成独立的文案生成配图建议口播稿拆分之后一切立刻正常。第二个原则测试 Skill 时你是在测试文档不是测试代码。我调试了很久脚本结果最后才发现是 SKILL.md 里漏写了一条步骤模型压根没有按我想的流程走。脚本只是辅助真正驱动模型的是文档。第三个原则迭代时多读模型的推理轨迹别只看输出结果。只有看到模型是被哪段描述触发的、执行到哪一步开始偏离你才知道该怎么改。如果你第一次写 Skill 就能体会到这三个原则这篇文章就没白看。
阅读完成 · 觉得有帮助？
