你有没有过这种经历一个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. 从第一性原理看SkillsAgent能力供给方式的范式转换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从“玩具”变“工具”的关键一跃。
你有没有过这种经历一个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. 从第一性原理看SkillsAgent能力供给方式的范式转换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从“玩具”变“工具”的关键一跃。
