你有没有过这种经历：一个Agent吹得天花乱坠，接进来之后日常聊天确实像模像样，可只要一让它干点具体的活——画一张分镜、生成一份带样式的落地页、批量整理一批文件——就开始拉胯。要么给一堆正确的废话，要么做出来的东西根本不能用。我折腾了大半年Agent开发，一直被这个问题卡着。直到我把一套叫Skills的技能机制接到自己的工作流里，情况才真正发生变化。
这篇内容我就围绕“agent-skills”展开，从第一性原理解释Skills为什么能解决Agent“只会聊不会做”的难题，讲清楚它的目录结构、SKILL.md的编写方式、安装与测试链路，再对比当前主流平台对Skills的支持程度。不管你是自己折腾Claude、Codex这类编码Agent，还是在LangGraph之类框架里做Agent开发，这篇文章都值得花十分钟看完。
1. 一个越用越上头的现象：给Agent配“手艺活”
先说我最近的实测感受。之前我用一个Agent处理前端开发任务，它的表现在及格线上下徘徊：简单的组件能写，稍微复杂点的页面就崩，永远不知道在什么场景下该调用什么函数。后来我给同一个Agent配了几个Skill——一个负责落地页生成、一个负责可访问性检查、一个负责数据可视化——效果完全不一样。
最明显的变化是：Agent拿到需求之后会先“判断自己该用哪个技能”，而不是每次从零开始猜。比如让它“做一个产品和功能对比的展示页”，它瞬间就把落地页Skill调出来了，按照Skill里的规则输出一套可以直接打开的HTML；再让它检查一遍页面的对比度和标签语义，它就自动切到可访问性Skill，按SKILL.md里定义的检查清单逐项过，最后给出修改列表。整个过程像是一个新员工入职的时候拿到了几本岗位手册，而不是每次干活都靠临场发挥。
这不是Claude一家的事。OpenAI的Codex、各家的Agent框架，都在往“技能化”方向收敛。热搜词里反复出现的“agent skill教程”“skills开发”“agent skill测试”也都指向同一个趋势：大家已经厌倦了用Prompt堆功能的老办法，开始寻找一种能让Agent稳定复用手艺的结构化方案。
所以别再把Skills当成一个花哨的新名词。它本质上是Agent能力供给方式的一次升级——从“每次都要现场说的动态指令”变成“提前封装好、按需调用的标准操作包”。这篇文章后面讲的机制、实战和避坑，全都围绕这条主线展开。
2. 从第一性原理看Skills：Agent能力供给方式的范式转换
2.1 传统Prompt堆叠式Agent为什么撑不住复杂任务
很多人刚开始做Agent应用，第一反应是把所有要求写进系统提示词里。比如“你是一个前端专家，写代码时要注意响应式布局，要使用Tailwind，要保证在Chrome和Safari下表现一致，还要注意可访问性……”这段描述写得再详细，Agent在执行复杂任务的时候还是会出问题。
原因有三个。
第一，上下文窗口有限。系统提示词占掉的token越多，留给实际内容和中间推理的token就越少。一份写满了行业术语和规范的系统提示词，可能光初始化就吃掉四五千token。对短对话影响不大，一旦任务复杂、跨多轮，上下文就开始拥挤，Agent会渐渐“忘记”那些写在提示词里的规则。
第二，规则之间互相打架。真实业务场景里的规则不是线性的。你让Agent“输出简洁风格的界面”，它可能和“保证信息密度”冲突；让“尽力满足需求”和“不能擅自增加依赖包”冲突。写在单一大段提示词里的规则，Agent很难实时做冲突仲裁。
第三，没有可执行性。纯文字规则是“解释性知识”，Agent即使理解，也不知道要调用什么工具、执行什么脚本。让它“对页面做可访问性检查”，它只能凭印象给几条通用建议，而不是真正跑Lighthouse跑axe-core。
这些问题我在做一个批量生成品牌落地页的自动化流程时全踩过。那时候我把十条设计规范全部塞进Prompt，最终生成的页面风格五花八门，没有一个严格达标。后来我意识到：问题不在于模型不够聪明，而在于我喂给它的“能力载体”错了——文字规则不是能力，只有可执行的结构化逻辑才是能力。
2.2 Skills的底层机制：描述性元数据 + 可执行载体
Skills的设计思路，简单说就是：把一组完成特定任务所需的知识、流程、脚本和文件组织成独立模块，让Agent在需要时“按说明调用”。
这里有两个关键部件。
第一个是描述性元数据，通常是一个SKILL.md文件。这个文件用自然语言描述这个Skill是做什么的、适合什么场景、不适合什么场景、怎么使用、有哪些注意事项。它不是给人类看的手册，而是给Agent看的“工具说明书”。Agent读完之后，就知道“我现在该不该用这个技能”。
第二个是可执行载体。一个Skill可以只包含说明文档，也可以带Python脚本、Node脚本、模板文件、静态资源。比如一个“生成分镜图”的Skill里可以附带一套分镜结构的JSON模板；一个“自动修图”的Skill里可以封装一个调用图像处理API的Python脚本。Agent根据任务需要，决定是直接按说明写代码，还是去执行配套脚本。
这两个部件组合起来，就形成了一个“技能单元”。Agent遇到任务时，先做一次匹配——根据用户的请求判断应该激活哪个SKILL.md；激活之后，再按照里面的指引去读脚本、跑工具、生成结果。
我常用一个类比来解释：之前的Agent像是一个什么都会一点、但每次都空手上门的实习生；Skills就是给这个实习生配好的一套工具箱，每个箱子里有操作手册、有专用工具，还贴了适用场景标签。工具箱不会让实习生变聪明，但能让他在正确的时间拿出正确的工具。
2.3 Skills与Function Calling、Tool Use的关系
很多人分不清Skills和Function Calling的区别。我一开始也混淆，后来想清楚了：Function Calling/Tool Use是“让大模型调用你定义好的函数”，Skills是“让大模型按照一份包含知识和流程的说明书，去完成一整类任务”。两者差了一个维度。
Function Calling适合原子操作：查天气、发短信、写一条记录。它的粒度很小，模型只需要决定“调不调、参数怎么填”。
Skills适合复合任务：生成一个项目脚手架、完成一轮代码审查、整理一份会议纪要并导出结构化数据。这类任务里可能要用到多个函数、多条决策规则、多轮输出。
换个角度说：Function Calling是棋子，Skills是棋谱。棋子一次性只能走一步，棋谱教你整局怎么布局。真正的Agent系统里两者也不冲突，SKILL.md内部完全可以引用一组函数，用Function Calling去执行底层步骤，Skills负责上层的流程编排和决策逻辑。
搞清楚了这一层，后面开发Skill的时候思路就会很清晰：不要什么东西都扔进Skill里，也不要指望靠一个函数完成复杂的技能逻辑，Skills承担的是“把范围收窄、把标准立住、把流程固化”的角色。
3. 从零开发一个Skill：完整的可复现链路
3.1 Skill的目录结构与SKILL.md怎么写
先给一个最常规的目录结构，我建议所有初学者从这个骨架开始：
my-skill/ ├── SKILL.md ├── scripts/ │ ├── run.py │ └── requirements.txt ├── assets/ │ ├── template.html │ └── example.json └── README.mdSKILL.md是入口，Agent优先读这个文件；scripts/放可执行脚本，适合有确定算法逻辑的部分；assets/放模板、示例文件、数据文件。README.md给人类维护者看，Agent一般不读它。
SKILL.md是核心，建议用Markdown格式，前端用YAML frontmatter写元信息。我常用的一套字段是这个样子：
--- name: landing-page-builder description: 适合生成营销落地页、产品介绍页、活动页。输入需求说明，输出完整的单文件HTML。不适合用于电商交易页面和需要复杂后端的系统。 ---关键在于description这一段。模型判断是否启用这个Skill，主要就看这一段。要写清楚三个信息：这个技能是干什么的；在什么条件下触发；在什么条件下不能触发。
正文部分要按“给另一个Agent看的说明书”的标准来写。建议包含这些章节：
- 使用场景：什么时候用、什么时候别用，给出正例和反例。
- 执行步骤：从收到请求到输出结果，需要经过哪些具体步骤。
- 输出格式规范：如果产物是HTML，就规定必须有哪些结构；如果是JSON，定义字段列表。
- 注意事项：频率踩的坑，比如“不要使用外部CDN，因为环境可能离线”。
- 自检清单：输出前要逐项检查的内容。
不要把SKILL.md写成人类培训教材。别开篇讲概念科普，直接给Agent可执行的规则；也别用模糊的形容词，尽量用可判断的标准。比如“风格简洁”不如“字体使用系统默认字体栈，不引入非必要的Google Fonts”。
3.2 实战：做一个“前端落地页生成”Skill
我拿自己做过的落地页Skill当例子，完整走一遍开发流程。这个Skill的目标：给定产品描述，输出一个可直接打开的单文件HTML页面。
SKILL.md的关键部分，我这样设计：
## 执行步骤 1. 从用户输入中提取产品名称、目标用户、核心卖点、行动召唤（CTA）。 2. 使用assets/product-page-template.html作为基础模板。 3. 按照模板中的注释替换各个区块内容。 4. 检查页面是否包含完整的头部导航、主视觉区、三个卖点区块、CTA区、页脚联系方式。 5. 确保所有样式内联在<style>中，不依赖外部文件。 ## 输出格式规范 - 输出一个完整HTML文档，DOCTYPE为html。 - 页面字体使用系统字体栈。 - 主按钮颜色使用#2563EB，圆角8px。 - CTA文本优先从用户输入中提取，缺失时默认为“申请试用”。 ## 自检清单 - [ ] 所有图片均使用占位图数据或描述性alt文本 - [ ] 页面在移动端375px宽度下无横向滚动 - [ ] 响应式断点包含768px和1024px模板文件里我把结构提前搭好，留下带注释的插槽。这样Agent做出来的页面不会天马行空，至少骨架稳定、风格统一。很多人的Skill之所以效果不稳，缺的就是这一步——给Agent一个明确的模板，而不是让它自由发挥。
然后还要写脚本。这个Skill里我在scripts/下放了一个validate.py，用于检查生成的HTML是否满足自检清单里的关键项。原理很简单：用正则和html解析库检查是否存在<nav>、CTA按钮文本、响应式断点、alt属性。Agent执行完后自己跑一遍脚本，比自己肉眼“检查”靠谱得多。
这整套Skill做下来，我强烈建议你理解一个核心原则：Skill的价值在于固化决策和执行标准，不在于炫技。模板、脚本、检查清单都是在替Agent兜底，把容错空间缩小到可控范围。
3.3 三种层级的测试方法
Skill写完不算完，测试才是重头。我踩过不少坑之后，形成了三层测试习惯。
第一层：文档测试。把SKILL.md单独丢给对方模型读一遍，然后让它不看任何额外说明，就按照SKILL.md回答任务。这一步能暴露元数据写得好不好的问题。如果模型读完description之后，在明显不该触发的时候触发了，或该触发的时候没触发，说明描述有歧义。要反复调整description里的正例和反例。
第二层：组件测试。单独测试scripts目录里的脚本。别觉得脚本简单就不测，我就遇到过因为脚本依赖的包没有写进requirements.txt，整个Skill在别的环境跑不起来的情况。把所有脚本在干净环境里跑一遍，确保依赖完整、路径都是相对路径。
第三层：集成测试。用真实的Agent环境，输入若干条目标场景的请求和若干条“干扰请求”，观察Agent能不能正确选择Sk、按步骤执行、输出符合自检清单的结果。干扰请求特别重要。比如落地页Skill，你给它发“写一篇技术博客”这种请求，正确行为是拒绝调用，直接在对话里回复做不到或转给其他流程。
集成测试的调试视角：如果输出偏离预期，优先回去改SKILL.md正文，而不是改模型配置。大多数情况下，问题出在说明书写得不够清楚，不在模型本身。
4. 主流平台与框架的Skills支持对照
4.1 Claude生态：从Claude Code到API层的Skills机制
当前对Skills支持最完整、外界讨论最多的还是Claude产品线。在Claude Code里已经支持通过/skill这样的命令方式装载技能，面向开发者的官方市场也开放了一批成熟Skill，覆盖前端开发、代码审查、测试生成等场景。热搜词里“claude agent skills: a first principles deep dive”这类内容非常多，说明大家对这个机制的兴趣已经从小众技术圈扩散到了大众开发者。
在API层面，Claude的Skills机制和它的Agent开发框架深度融合。你可以把SKILL.md作为知识资产注册进去，让Agent在规划任务时自动检索匹配。如果要自己搭应用层，大致模式是：先维护一个Skills清单，任务来的时候先做一次相关性检索，再决定把哪些SKILL.md内容注入上下文。这个流程看起来简单，但实际效果很好——相当于给Agent装了一个“按需加载”的能力层。
4.2 Codex与命令行编码Agent的Skills形态
OpenAI的Codex热度一直很高，热搜词里“welcome to codex”这类也很扎眼。Codex在Skills方向上给出了另一套设计思路。它的核心不在一个统一的SKILL.md标准，而更强调在命令行Agent的上下文中固化“提示词包”和“脚本组合”，通过配置文件来声明可用技能。
我试下来的感受是：Codex的Skills形态更偏向“给编码Agent定义规则和外部命令”，适合代码库内的重复性任务，比如按团队规范生成commit信息、跑格式化工具、执行特定lint规则。它的优势在于和CLI工作流贴合紧密，劣势在于跨平台、跨Agent的可移植性目前不如SKILL.md这种标准文件来得通用。
4.3 通用Agent框架中的技能编排位置
如果你用的是LangGraph、OpenAI Agents SDK、或自己写的一套Agent跑循环，Skills的表现形式会更自由。这时候“技能”不一定是文件，也可能是一组Tool Node、一个SubAgent、一段包含状态机的Workflow。
我在自研框架里用的方案是：把每个Skill做成一个独立的处理节点，节点内部包含“调该调的工具、按什么顺序调、出什么格式的结果”。流程图里看就是Agent有一个路由节点，负责根据用户输入选择走哪个Skill节点。这和开源社区里“多Agent”热搜词关注的方向一致——技能编排是多Agent协作的基础单元，一个Agent的核心能力就是知道自己接下来该把任务转给哪个技能节点。
做跨平台方案时的建议：尽量让Skill内容保持“文件化”和“与平台无关”。SKILL.md加scripts的结构在Claude里能用，搬到自研框架里也能解析。别把 Skill 写死成某家平台的私有格式。
5. 安装、测试和安全边界：容易被忽略的事
5.1 Skill安装的几个常见错误来源
热搜词里“skills安装包下载”“skills下载平台有哪些”是高频搜索，说明安Step没那么顺。我自己安装第三方Skill也遇到过一堆问题，列几个最常见的。
- 版本兼容：有些Skill是针对特定模型版本设计的，换了版本之后SKILL.md里的某些新语法字段可能无法被解析，表现为Agent完全忽略这个Skill。解决办法是看Skill仓库的更新记录，明确标注支持的版本范围，不要盲装。
- 路径问题：多数Skill框架在加载时按相对路径找scripts和assets。如果整个目录从压缩包解压时多了层级，比如多了一层子目录，Agent就找不到脚本，表现为“Skill被触发但执行时报错”。装上之后先跑一遍内置测试，有tests目录就跑tests，没有就手动触发一次。
- 依赖污染：Skill的scripts如果声明依赖不严格，容易和系统里已装的包冲突。尽量用虚拟环境或要求Skill自带依赖声明文件。我见过一个Skill要求
requests版本必须小于某版本，结果把另一个项目环境搞挂了。
5.2 权限设计与沙箱思路
Skill的本质是让Agent获得执行能力。能力越强，越要谈权限。很多人的思路是“反正本地跑，应该没事”，等出了事才后悔。
我的权限设计三条原则：
第一条，最小权限。Skill脚本默认只能访问自己目录内的文件和用户明确授权的位置。比如一个文件整理类的Skill，如果没有授权就不要让它碰系统目录。
第二条，可审计。所有Skill产生的文件变更、网络请求、命令执行都要有日志。我用的方案是要求Skill的脚本把操作记录写到一个统一的log目录。这样出了问题能回溯。
第三条，命令白名单。避免让Agent直接执行任意Shell命令，能封装的尽量封装成Skill内提供的脚本。尤其不要让Skill内部轻易调用eval、exec、subprocess去执行用户输入的内容，除非加了一层防护校验。
5.3 合规使用：安全类Skill的授权边界
热搜词里有“自动挖洞skills”，这让我想说清楚一件事：安全类Skill本身是中性的，但必须限定在授权范围内使用。我在自己的安全测试流程里也会用Skill，但前提是目标资产拥有合法测试授权，扫的是自己维护的系统或者SRC平台允许的范围。
如果你准备做安全方向的Skill，建议在SKILL.md的description里明确写“仅在获得授权后使用”，并且在执行步骤里加入授权确认环节。比如先让使用者声明授权范围，脚本内部再对目标路径做前置校验。这些设计不是限制你，而是保护你。我就见过有人拿一个扫描Skill去打别人的系统，结果产生的日志直接成了风险证据。能力本身不背锅，用的人要负责。
5.4 Skills与记忆、多Agent协作的组合玩法
热搜词里还有“agent记忆”“多agent”“hermes agent obsidian”这些方向。Skills、记忆、多Agent不是三件事，本质是Agent能力的三层结构。
Skills决定“会做什么”，记忆决定“记得偏好和历史”，多Agent协调决定“谁来做什么”。把三层打通之后，玩法会完全不一样。
我设置了一个个人知识管理Agent，用Obsidian作为外部记忆库，Skills负责具体动作：一个是网页剪藏Skill，把网页转成符合笔记规范并归档；另一个是周报生成Skill，读取这周的笔记条目，按模板生成周报。然后整个流程由一个协调Agent来调度，用户只需要说一句“这周汇报材料整理一下”，链路自己跑。
这种组合带来一个方法论上的转变：别再把Agent当作一个函数，而是当成一支按技能分工的团队。Skill是在给团队里每个人发岗位职责书，记忆是多Agent共享的工作日志，编排是在分配活。三者结合之后，Agent系统的能力边界很明显往上抬了一大截。
6. 踩坑之后，我的几条真实体会
写到最后，说几句比较掏心窝的话。
我见过太多人开发Agent，模型换了一个又一个、Prompt调得越来越长，效果还是不理想。而我自己的体会是：模型本身的能力已经够用的情况下，真正的性能瓶颈常常在最朴素的地方——有没有稳定的流程、有没有结构化的技能封装、有没有反复可验证的测试。Skills这个地方，恰好把这些看似不起眼的点串起来了。
给新入门的朋友几个建议。第一，先从复制别人写好的SKILL.md开始，不要一上来就自己设计结构。多读几个热门Skill的写法，注意它description用了什么语气，执行步骤是怎么拆到模型能跟上的程度；第二，把测试当成开发的一部分，而不是等到“感觉差不多了”再试；第三，每次升级Skill之后留一个旧版本，随时能回滚，这比什么花哨功能都实在。
我目前最想尝试的方向，是把Skills和更复杂的多步骤工作流结合起来：比如让一个Skill负责数据分析，另一个Skill负责把结果转成面向管理层的叙事，再由第三个Skill生成渲染用的图表。这套链路如果跑顺，能替代很多“人肉搬运数据、人肉排版”的工作。不要小看这些单个看不大的改进，把它们串起来，恰恰是Agent从“玩具”变“工具”的关键一跃。
