Agent Skills 完全指南：原理、写法、安装与实战避坑

最近一两年skills这个词在AI工具链里的地位简直像坐上了火箭。尤其是Claude Code、Codex这类编程智能体普及以后大家对skills的讨论从这是什么直接跳到了我今天又学会了几个skill打开新世界。GitHub上的skill仓库如雨后春笋官方使劲推社区跟着疯狂造轮子。我自己用agent做前端、写论文、做自动化测试也有一段时间了最近专门花了两周把skills相关的机制、写法、分发、坑点全部过了一遍这篇就把我看到的东西、踩过的坑和能直接抄的作业都摊开来聊聊。这里先把skills定义清楚免得后面跑了题我们聊的不是招聘网站上的技能那个skills也不是GitHub教育项目GitHub Skills而是Agent Skills——也就是给Claude、Codex这类AI编程助手/智能体用的技能包。一个skill本质上是一个文件夹里面有说明文档、脚本、模板和校验规则告诉agent你在面对某类任务时按这个流程、用这些工具、产出这种格式的东西。它解决的核心问题是不靠每次临时写prompt去碰运气而是把已经验证过的方法论沉淀下来让agent一遇到对应任务就直接调用。适合谁看呢如果你在写prompt时总觉得这次告诉它怎么做下次还得再讲一遍如果你想让Claude帮你稳定产出某个固定格式的东西分镜、论文、周报、代码脚手架如果你想把某个细分领域的工作流打包发给同事用——这篇都适合你。1. 先搞清楚一件事Agent Skills 到底是什么1.1 一个 Skill 的实际形态我先拿一个最典型的例子来说明。你从官方或者社区下载一个好的skill后解压开通常能看到这样的目录storyboard-skill/ ├── SKILL.md ├── scripts/ │ ├── format_storyboard.py │ └── generate_shot_list.py ├── templates/ │ ├── storyboard_table.md │ └── shot_description.md └── assets/ └── examples/真正核心的文件只有一个SKILL.md。这个文件就是整个skill的说明书里面用Markdown写清楚了这个skill是干什么的、它会在什么场景下被触发、agent拿到任务后应该按什么步骤走、输出要达到什么标准、必要时可以调用哪些脚本。其余scripts和templates都是辅助工具脚本可以帮你做格式转换、数据抽取、文件合并等工作模板可以固定输出样式。也就是说一个skill本质上是把提示词 流程 工具 模板打包成了一个可复用单元。这个设计思路跟传统的系统提示词最大的区别在于加载方式。系统提示词是大模型每次对话都背着的一整段背景知识你塞的东西越多agent的注意力越容易被稀释。而skill是按需加载的agent先读到SKILL.md里那段描述判断当前任务是否匹配匹配了再读取完整内容不匹配就完全不占用上下文。这样既保证了专精度又不会污染通用对话能力。很多人第一次看到这个结构会问这不就是一个README加几个脚本吗对就是把简单的东西组合出了不简单的效果。关键在于这个结构被各个agent工具认可了成了约定俗成的标准所以你可以把一个skill文件夹从一个工具迁移到另一个工具拷贝、压缩、上传、下载都极其轻便。这种标准化文件夹的设计是它能在生态里流通起来的根本原因。1.2 为什么它是超能力级别的抽象社区里有人把好的skills叫做超能力是有原因的。你想一下传统玩法是什么我让Claude写一个分镜脚本我得在prompt里写清楚分镜表有几列、镜头号怎么编、景别术语有哪些、人物情绪怎么标注……这些规则完整写出来可能光prompt就上千字。而且同一套规则换个任务场景就得改一遍。有了skill之后这一步就变成把分镜方法论写进SKILL.md——写一次之后每次只要说帮我把这个剧本拆成分镜它就知道要去翻storyboard-skill按你的脚本去跑产出整齐的分镜表。你不需要重复教学agent就像忽然长出了一个分镜肌肉记忆。我自己的感受是装了一个好skill等于给agent装了一根领域专用的拐杖它从什么都能聊两句的实习生变成某个环节闭着眼睛都能搞定的熟练工。这里需要提醒一句别指望一个skill能管所有事。技能越聚焦效果越炸。要么你直接使用一个skill只解决一个大任务把步骤写细把边界写清楚别贪多。你要做一个全栈工程师skill那大概率还不如不装因为agent读完了也不知道眼下这个具体任务到底该按哪条路走。1.3 前端开发相关的 Skills 到底能帮你省下什么热搜词里前端开发skills排得很靠前我猜不少人是被这个吸引进来的。我实际用下来前端方向的skill是最容易见效的因为它天然有标准答案式的产出物——组件、页面、样式规范。举个例子。你可以做一个react-project-styleskillSKILL.md里写清楚这个项目用的技术栈React TypeScript Tailwind、组件命名规范、目录结构、状态管理方案、接口封装风格。然后你对agent说帮我实现一个用户列表页它就会自动按项目约定生成文件而不是每次都用那种千篇一律的通用代码。项目里新来一个同事也不需要花半小时给他讲代码规范直接把skill丢给他就完事了。前端开发场景里比较常见的skill类型有组件生成、代码评审、样式系统搭建、脚手架初始化、Tailwind类名规范检查。这类skill写起来也不难核心就是把你平时会口头强调的注意这个项目不用CSS Modules用Tailwind这类话变成结构化的说明。我建议每个前端team都维护一到两个项目专属skill收益是立竿见影的。2. Skills 的工作原理与第一性原理2.1 从上下文注入到能力加载关于Claude Agent Skills: A First Principles Deep Dive这个讨论方向我很喜欢因为它逼着你去想一个问题为什么非要有skills这个东西把底层的机制拆开看其实是三个词提示词工程、结构化输出、工具调用。Skills把这三种玩法揉成了一个统一接口。传统提示词工程是对输入下功夫每次都在prompt里做加法把规则越写越长最后甚至出现prompt里加一句你是专家就比不加效果好这种玄学。而skill机制是先在开发期把规则沉淀下来运行期只做加载几乎不往prompt里堆废话。Claude Agent Skills的具体实现简单说就是在对话过程中让agent主动检查当前可用的skills列表根据描述匹配之后再读取对应SKILL.md和脚本。也就是说从用户注入上下文变成了agent自己按需加载能力。这个区别带来一个很有意思的连锁反应写prompt的人开始像写代码一样管理自己的知识资产。你不再关心这句指令该怎么说而开始关心这个能力该怎么抽象、怎么测试、怎么迭代。这也解释了为什么skills生态会在这么短时间内膨胀起来——它让每个人都成了知识工程师。你可以把SKILL.md理解成一段带版本、带测试、可复用的高质量提示词工程产物只不过它多了脚本和模板这两个可靠的执行层。2.2 一个好的 Skill 应该有三层描述、流程、校验我自己写多了之后总结了一个判断标准一个skill能不能打看的不是它文案多漂亮而是这三层齐不齐。第一层是描述层。SKILL.md开头那段这个skill什么时候用、什么时候别用必须写得非常具体。你写用于生成报告就是垃圾因为agent分不清什么报告属于这个skill你写用于将产品需求文档翻译为PRD格式报告输入需包含原始需求文档路径不适用于已格式化的PRD就是好的。描述决定了agent是否正确触发它也决定了上下文会不会被无关skill白占。第二层是流程层。这里面要写清楚步骤顺序、每步的输入输出、关键判断点。如果一个SKILL.md全部是你要负责、你要确保、你要擅长这类套话它约等于一张废纸。好的流程是一串可以照着执行的动作比如第一步列出所有镜头第二步按三镜头法分组第三步生成分镜表第四步用script校验编号。agent不是靠悟性工作而是靠步骤。第三层是校验层。这也是最容易被人忽略的。我见过太多skill只能产出差不多的结果。要拿到稳定的结果你必须在SKILL.md里明确输出必须满足的硬性标准最好再配一个脚本自动检查。比如分镜skill可以写镜头号必须以S001格式编码不能跳过编号再让脚本跑一遍检查不合格就反馈给agent重新改。这一层让skill从演示品变成生产工具。2.3 Claude Skills 与 Codex Skills 的差异这里简单对比一下我实际用下来的感受。Claude Code把skills做成了官方一级公民目录规范、加载方式、文档都很完整上手快。Codex的skills体系稍晚一点整体思路接近同样有SKILL.md这样的描述文件但权限模型、命令解析这些细节上有差别。我建议把它俩都装上多数通用skill两边能互通只要注意个别特殊标记就行。具体对比如下对比维度Claude SkillsCodex Skills文件结构SKILL.md 辅助目录类似支持 AGENTS.md 约定加载方式对话中按需匹配并加载任务开头扫描并加载适用范围Claude Code及部分兼容工具Codex CLI、IDE 插件等生态成熟度官方开源仓库社区聚合量大增长快偏研发场景的多通用性SKILL.md 通用脚本接口可移植同理别用太专有的命令就行reasonix如何安装新skills这类问题我也在社区里看到过其实ReasonIX这类基于Claude Code能力封装的产品安装方式基本都是走同一套目录规范把skill放进指定的~/.claude/skills路径再在工具里reload一下就行。如果你的工具文档没写就去它设置里找skills目录就好大概率逃不出这个套路。3. 安装与下载找到好 Skills 的完整路径3.1 从哪找官方市场与开源仓库很多人第一问是skills下载平台有哪些。答案是目前并没有一个特别集中统一的应用市场各家AI工具正在补课但实战中大家主要从这几个地方找。第一个是官方仓库。Anthropic官方维护的claude-skills仓库GitHub上搜anthropics/claude-skills里面有几个由官方团队打磨的示例质量高适合拿来学习写法。OpenAI那边也可以搜codex-skills。第二个是GitHub上的聚合列表比如awesome-claude-skills、awesome-codex-skills这类大全仓库里面按场景分好类了从前端开发、文档撰写到写作辅助一应俱全是我最常用的一站式入口。第三个是社区分享包括一些独立开发者官网、技术博客里附带的下载链接。很多人在社交平台上发今天学会了skills打开新世界的时候下面往往就挂着一个仓库地址。找的时候有两点建议第一优先看README里有没有写明适用的工具版本和Skill测试结果没写清楚的多半是投机作品第二优先找有实例输出示例的skill光有描述没有结果的下载前先打个问号。网络环境这块我不多展开大家按自己实际可访问的资源来GitHub上也有不少镜像仓库和打包下载资源同样可用。3.2 手动安装方法与目录规范拿到一个skill之后安装流程其实很简单以Claude Code系为例先找到全局技能目录。正常情况下是~/.claude/skillsWindows下是C:\Users\你的用户名.claude\skills。如果目录不存在就自己建。把整个skill文件夹复制进去注意保持目录结构完整千万不要只拷SKILL.md而丢了scripts。重启或reload当前工具会话。Claude Code里可以输入/skill看到当前已安装的skill列表Codex工具也有类似命令。验证在对话里描述一个能触发你目标的场景看它是否真的调用到了skill里的步骤。这里有个小细节很多人把skill装到项目目录而不是全局目录。全局目录的意思是任何项目都能用项目目录比如项目根目录下的.skills的意思是只有这个项目能用。我建议通用能力写作、读PDF、格式转换放全局和某项目强绑定的比如这个项目的代码规范校验放项目目录这样不会串味。还有一种离线安装包的说法其实本质就是把上面说的文件夹打好压缩包解压后放到位即可。所以你在网上看到skill的.zip下载很常见别担心宁可多放一层文件夹也不要少放文件。有些打包的人习惯在外层再包一个同名目录解压后可能是skills/storyboard-skill/SKILL.md这层嵌套本身没影响agent能找到。3.3 装完不生效的第一次排查新装skill最容易踩的坑就是明明装了但对话里提任务它完全不理你。我遇到过太多次基本排查按这个顺序来先看路径是不是放错了目录层级比如多套了一层skills/skill-name目录再看文件名SKILL.md这个文件名不能改大小写也最好原样然后看描述如果你的SKILL.md里描述本身写得过于宽泛agent根本判断不出该不该触发最后看版本很老的工具客户端可能不支持skills功能该升级就升级。还有一个特别容易被忽略的如果你同时装了多个skill触发了竞争。agent会优先匹配描述最像当前任务的skill这时候别的skill会静默失效。别一个劲怀疑脚本有问题先看看是不是能力打架。3.4 实测下来真正好用的几类 Skills聊几个我装了以后真的在反复用的skill类型给你一个skills推荐方向的参考。第一类是文档格式化类。比如把会议纪要转成规范的周报、把零散的研究笔记变成结构化文档。这类skill效果最好因为大模型本来就擅长文本整理skill只需把格式标准和术语表固定下来输出就能稳定达标。第二类是代码脚手架生成类。给它一个需求描述它直接按项目规范生成多文件代码骨架省掉新建文件夹、写样板代码的重复动作。第三类是数据清洗与格式转换类比如把CSV转JSON、把时间戳统一格式、把日志按规则过滤这类任务用脚本做最可靠skill正好让agent知道什么时候该用这些脚本。我踩过的反向例子也有比如全知全能型的超级skill什么都想管最后agent每次都要读一大段说明反而把简单任务复杂化。所以一个skill能帮你省时间的前提是它知道边界在哪里。4. 动手写一个 Skill从分镜到论文的完整拆解4.1 具体场景写一个分镜 Skill很多人找分镜skills下载但网上现成的不一定顺手自己写反而十分钟搞定。我先以分镜为例走一遍完整设计流程。第一步明确技能范围。我要做的分镜skill只服务于将小说/剧本片段转换为分镜表不管拍摄、剪辑这些后期的事。第二步写描述和流程。SKILL.md我一般这样起头# Storyboard Skill 将剧本或小说片段转换为专业分镜表。 适用需要分镜表的视频项目。 不适用本身已经是分镜表的内容。 ## 工作流程 1. 通读原文提取场景、角色和行为。 2. 按叙事节奏切分镜头每镜头表达一个核心动作。 3. 对每个镜头标注镜头号(S001)、景别、拍摄方式、台词、角色情绪。 4. 生成完整分镜表。 5. 调用 scripts/validate_storyboard.py 校验编号格式失败则修正。 ## 输出格式 | 镜头号 | 景别 | 拍摄方式 | 画面内容 | 台词 | 情绪 |第三步写一个简单的校验脚本比如用Python正则检查镜头号是否按S001、S002顺序排列import re, sys def validate(lines): nums [re.match(r^S(\d{3}), line.strip()) for line in lines if line.strip().startswith(S)] prev 0 for m in nums: if not m: continue cur int(m.group(1)) if cur ! prev 1: return f镜头编号不连续: 第{cur}号, 期望第{prev1}号 prev cur if prev 0: return 没有找到任何镜头编号 return OK if __name__ __main__: print(validate(sys.stdin.readlines()))第四步测试。我给几个不同风格的输入试过古典小说片段、现代电视剧对话、甚至一段很意识流的散文。发现问题就改流程描述和脚本规则。这步就是agent skills测试非常必要别省。有时候你会发现SDK的输出格式跟你产品里的样式有冲突那就直接改输出格式这一段把列名调成你最终需要的让agent按这个来。4.2 具体场景写一个论文辅助 Skill再讲一个codex写论文的skills的实际案例。论文辅助类skill跟分镜不同它其实是一个工作流包里面应该有多个阶段文献检索、大纲生成、段落撰写、引用格式化、重复率自查。你可以把它做成一个skill但里面用阶段标志区分更优雅的做法是拆成多个skill比如topic-research、paper-draft、citation-format每个负责一段。我见过一个很靠谱的写法SKILL.md 里不做写论文这种巨型任务描述而是把它拆成如果输入是题目走A流程如果输入是草稿走B流程用一个关键词判断来控制分支。这时脚本的作用就大了一个脚本可以抽取当前草稿中的引用列表另一个脚本可以检查摘要的行数、关键词数量是否符合目标期刊格式。写这类辅助skill有个通用技巧多放禁项。比如明确写不要让模型编造引用文献找不到的标注[未验证]概述部分不要超过150字不要使用第一人称。大模型对要做什么听得懂对不能做什么容易忽略所以你必须在SKILL.md里用专门的硬性约束小节把雷区一条一条列出来。这是我从一堆失败skill里总结出来的关键区别。4.3 开发过程中的注意事项然后是一些实操心得。第一命名用英文小写加中划线像storyboard-skill这样。中文名虽然看着亲切但有些CLI工具对非ASCII路径支持不友好容易出幺蛾子。第二脚本能跑通是底线。我遇到过SKILL.md写得天花乱坠结果依赖脚本缺库、路径写死一执行就报错。开发时脚本不要依赖特殊环境尽量只用Python标准库或者提前在skill说明里写清楚依赖安装命令。第三测试一定要覆盖负例——也就是不该触发这个skill的场景。如果它错误地触发了说明描述还不够圆润要加不适用的排除条件。另外写完skill最好做一个最小验证起一个干净的对话不要夹带任何额外提示直接说一句用XX skill处理一下这份内容。如果这样都能稳定触发并输出合格结果说明这个skill已经站得住了。凡是需要你手动补充一堆上下文才能工作的skill本质上还是半成品。5. 常见问题与排查技巧实录5.1 加载失败排查速查表症状可能原因建议处理skill在列表里看不到安装目录不对检查skills目录层数避免嵌套看得到但任务不触发描述写得太泛/与已有skill冲突改描述加限定条件删掉重复skill触发了但输出跑偏流程不具体把步骤改成可执行的清单与判断准则脚本报错缺依赖/路径写死用标准库重写或补充依赖安装说明中文乱码编码问题SKILL.md和脚本统一用UTF-8保存权限不足没有执行权限Linux/macOS给脚本加可执行权限chmod x新版不兼容工具版本太老升级CLI到支持skills的版本这里特别说一下编码问题。Windows记事本默认是ANSI编码你辛辛苦苦用记事本编辑SKILL.md一放进去agent读取的时候出现乱码整个文档直接失效。解决办法很简单用VS Code等现代编辑器写保存时选UTF-8不要用系统默认编码。5.2 我踩过的坑与独家技巧第一个坑是skill之间的覆盖和冲突。我试过同时装了一个写营销文案skill和一个短视频脚本skill给Claude下达任务写一个介绍产品的朗读文案时它随机触发其中一个效果很割裂。后面我学会了在描述里写互斥条件比如营销文案skill里写一句不要处理短视频口播类文案请转交脚本skill效果立刻好了很多。第二个坑是过度自动化。刚开始我会在skill里塞很多脚本觉得脚本越多越专业结果整个流程变得很重加载慢、报错多、维护成本高。后来我明确了原则能用自然语言流程写清楚的就别脚本脚本只负责那些正则能查的校验和文件级批处理。记住skill的核心是给agent一套方法论工具永远是辅助。第三个技巧是版本管理。我在~/.claude/skills下面维护了一个git仓库所有skill变更都提交。出现之前还能用这版改坏了的情况随时回溯。另外把每个skill的README写清楚变更历史方便后面查。虽然听起来像在管理一个正经项目但时间长了你会发现这堆skill就是你沉淀下来的知识资产跟源码库没什么区别。5.3 安全红线自动化挖洞类 Skill 的正确姿势最后必须专门提一嘴自动挖洞skills这类东西。网络安全领域确实有人用skills做自动化漏洞挖掘——信息收集、端口扫描、常见漏洞PoC检测甚至AI辅助的Exploit编写。我自己也做过合规的CTF和授权渗透测试不得不承认一个设计良好的skill确实能把这类流程标准化减少大量重复劳动。但这里必须画一条清清楚楚的红线所有自动化安全类skill只能用于你有明确书面授权的目标或者CTF比赛、自建靶场。绝对不要拿它去扫别人的服务器、测没有授权的系统。把未授权扫描当作skill好用来玩是把自己往法律风险里送。我建议这类skill的SKILL.md里应该内置几句硬约束启动前要求用户确认授权、输出只包含技术指标不包含攻击细节、如果检测到敏感目标直接中止。做白帽工具和做黑产脚本一线之隔但这个一线碰都不要碰。我个人的体会是skills这个机制最大的价值并不是让AI多看一眼文档而是逼着你把脑袋里那些我以为我懂的流程落到纸面上变成一串可执行、可校验、可持续迭代的步骤。写完一个skill再回头看它的时候你自己对这件事的理解反而变深了。最后分享一个小技巧每当你发现自己对同一个任务、同样的问题连续跟AI重复说过两遍以上的指令那就说明这段方法论值得被封装成一个skill了。把它写下来下次你会感谢自己。如果你手头正好有某个反复折腾的固定流程建议现在就去把它变成你的第一个skill。