引子
你大概常听到一个词,Skill。很多人开始”做Skill”,做得跟建一个代码仓库似的,一个文件夹、一堆文件,搞得挺正式。
如果你是零基础,第一反应多半是一连串问号。这玩意儿到底是啥?跟我平时直接跟AI说话,也就是写prompt,有啥不一样?SKILL.md里到底该填什么?做好之后怎么装进Claude?我为Claude写的,能不能搬到OpenAI或者别的工具上用?还有那个最让人犯嘀咕的:我吭哧吭哧写一个Skill,AI真的会”用”它吗,还是跟prompt一样,扔进去不是石沉大海,就是量子力学?
这篇文章就当一份手把手的教程,把上面每一个问题都写到你能照着做。不需要任何编程基础,每一步该建什么文件、填什么字段、点哪个按钮,我都写清楚。读完你能亲手做出一个能跑的Skill,并且知道它在Claude、在OpenAI、在别处分别怎么用。
先交代一个背景,免得你以为这是什么小众玩意儿。Skill是Anthropic(做Claude的公司)2025年10月16日推出的,两个月后的12月18日,又把它的规格作为开放标准公开,明确写着目标是”跨平台通用”。到2026年,Claude、Codex、Gemini CLI等主流Agent工具已经开始支持这套格式。它早已超出某一家公司的范围,正在变成行业的通用零件。
一、三个概念先分清:prompt、Skill、Claude Skill
很多人一上来就被几个词绕晕,prompt、Skill、Claude Skill、MCP、插件,听着像一回事。这一章先把它们一刀一刀切开,后面才不会糊涂。

1.1 prompt:你对 AI 说的话
prompt(提示词)就是你对AI说的话,这是最朴素的起点。
你打开AI,敲一句”帮我把这段话翻译成英文”,这句话就是一个prompt。你交代得越清楚,它干得越好。你说”翻译成英文”,它给你一版。你说”翻译成英文,语气正式一点,给客户看的”,它给你的就稳当得多。过去两年大家挂在嘴边的”提示词工程”,剥开就是一件事:研究怎么把话说好。
prompt有个躲不掉的毛病:它是一次性的、口头的。就像你叫了个临时帮手,每次都得从头交代一遍。公司周报有固定格式,你今天让AI按格式整理一份,得把要求全打一遍。AI干完,对话窗口一关,这套要求它就忘得干干净净,下周再要还得从头说。说漏一条,它就漏做一条。这种重复全压在你身上,靠你的记性。
1.2 Skill:写成文件夹、能被反复调用的说明书
Skill就是把”这件事该怎么做”写成一份说明书,存成一个文件夹放好,需要时让AI自己去翻。
还拿周报那个例子。用prompt的活法,是每周把那一长串格式要求重新打一遍。用Skill的活法,是你把这套要求写成一份说明书存好,以后只要说一句”整理本周周报”,AI自己就想起”这事我有本手册”,翻开照着做。
它跟prompt最硬的三条区别,记住就够用。第一,prompt是临时的,Skill是常驻的,一个说完就没,一个存着反复用。第二,prompt靠你每次记得说全,Skill把要求固化下来,由AI自己去取。第三,prompt只能是一段文字,Skill是一个文件夹,里面除了说明书,还能放参考资料、放素材,甚至放一段能直接运行的小程序。最后这点是Skill真正的杀手锏,第二章细讲。
1.3 “Claude Skill”和”Agent Skills 开放标准”是什么关系
你会看到两种叫法,Claude Skill和Agent Skills,它们说的是同一套东西,只是角度不同。
Agent Skills是这套格式的正式名字,也是那份开放标准的名字,由Anthropic制定。Claude Skill通常指的是你在Claude这个产品里用的Skill。打个比方,Agent Skills是”USB接口标准”这份规格书,Claude Skill是”插在Claude这台电脑上的U盘”。规格是开放的,所以同一个U盘也能插到别的认这套标准的电脑上,这就是第五章要讲的跨平台。
时间线理清楚:2025年10月16日,Anthropic在Claude里上线了Skills功能。2025年12月18日,它把这套格式作为开放标准公开发布。注意一件容易混的事,开放标准跟”捐给基金会”是两码事。Anthropic确实在2025年12月把另一套东西MCP捐给了Linux基金会,但Agent Skills到目前为止并没有交给任何基金会,它是Anthropic主导、对社区开放贡献的模式。
1.4 Skill 不是 MCP,也不是插件:一句话划清边界
这几个词经常一起出现,容易混,这里各给一句话。
Skill是”写给AI看的操作手册”,告诉它某类任务该怎么一步步做。MCP(模型上下文协议)是”AI连接外部工具和数据的标准接口”,管的是AI怎么够到你的数据库、你的日历。一个偏”怎么做事的知识”,一个偏”怎么连外部系统”,两者还能配合,比如官方就有一个专门帮你搭MCP服务的Skill。
插件(plugin)则是更大的打包单位,一个插件里可以同时装着若干个Skill、若干条命令、若干个MCP连接。你可以把插件理解成”一个工具箱”,Skill是工具箱里的一把把工具。分清这三者,后面就不会犯迷糊。
二、解剖一个 Skill:内部有哪几块
概念讲清楚了,这一章把一个Skill彻底拆开,看它由哪几块拼成,每块装什么。看完你脑子里要有一张清晰的结构图。

2.1 本体就是一个文件夹
一个Skill,本体就是电脑上的一个普通文件夹。文件夹的名字就是这个Skill的名字,里面至少装一个叫SKILL.md的文件。一个完整些的Skill,目录大致长这样:
weekly-report/ # 文件夹名 = Skill名
├── SKILL.md # 必需:说明书主文件
├── scripts/ # 可选:能直接运行的小程序
│ └── make_table.py
├── references/ # 可选:按需才读的详细文档
│ └── format-rules.md
└── assets/ # 可选:模板、素材文件
└── template.xlsx
记住这个结构:一个跟Skill同名的文件夹,里面一个必需的SKILL.md,外加scripts、references、assets三个可选子目录。最小的Skill就一个SKILL.md,三个子目录一个都不要也能跑。
2.2 SKILL.md 第一部分:开头的字段(frontmatter)
SKILL.md这个文件分成上下两部分。上半部分是一段用三道横线框起来的设置区,行话叫frontmatter,专门写这个Skill的基本信息。它长这样:
---
name: weekly-report
description: 按公司格式整理每周工作周报。当用户说"写周报""周总结""整理本周工作"时使用。
---
这里逐个字段说清楚,哪些必填、有什么硬规矩。
name(必填)是Skill的名字。规矩很死:最多64个字符,只能用小写字母、数字和连字符,开头结尾不能是连字符,不能有连续两个连字符,而且必须跟文件夹名字一模一样。还有两个保留词不能用,名字里不能含anthropic或claude。
description(必填)是一句简介,也是整个Skill最该花心思的一行。它要同时说清两件事:这个Skill干什么,以及什么时候该用它,最好带上能触发它的关键词。长度上,claude.ai网页端要求大约200字以内,通过API上传可以放宽到1024字符,但别贪长,写清楚就好。为什么这行这么重要,第三章会专门讲,因为它是AI决定用不用这个Skill的主要依据。
剩下几个是选填的,零基础阶段用不上,知道有就行。license写许可证。compatibility写运行环境要求,比如需要联网、需要某个Python版本,最多500字符。metadata是个自由的键值表,可以塞作者、版本号这类附加信息。allowed-tools预先批准这个Skill能用哪些工具,写法像 Bash(git:*) Read,不过它还是实验性的,各家支持不一,先别依赖。
2.3 SKILL.md 第二部分:正文
三道横线下面的全部内容,是这个Skill的正文,用普通Markdown文字写,就是带点格式的记事本。这部分是真正的”操作手册”,告诉AI这类任务该怎么一步步做。
正文怎么写没有死规定,但好的写法是:先一句话说这个Skill解决什么,再用编号列出步骤,能给例子就给例子,能附模板就附模板。比如周报Skill的正文,可以写”第一步列本周完成、每条带负责人,第二步列下周计划,第三步语气正式,第四步结尾附一个三列表格”,再贴一份填好的样板周报让AI照葫芦画瓢。
有一条硬建议要记住:正文别超过500行。太长了AI读着费劲、也占地方,正确的做法是把不常用的细节拆到references子目录里,正文只留主干,用到了再让AI去翻。这背后的道理就是下面2.5节要讲的渐进式披露。
2.4 三个可选子目录:scripts、references、assets
这三个子目录是Skill比prompt强的地方,各有分工。
scripts放能直接运行的小程序,Python、Bash脚本都行。凡是确定性的脏活,排序、求和、格式转换、批量改名,都适合写成脚本扔这儿。关键好处后面会反复讲:AI是去运行它,不是去读它,脚本的代码本身根本不进AI的脑子,只有运行结果回来。
references放更详细的参考文档,都是Markdown。把正文里塞不下、又不是每次都用的细节放这儿,比如一份完整的格式规范、一张容易出错的对照表。AI只在真用到那一刻才去读对应文件,平时不碰。
assets放静态素材,模板、图片、数据文件,比如一个现成的Excel模板、一张查找表。脚本和正文需要时直接引用它们。
引用这些文件时有两条小规矩:用相对路径(从Skill文件夹算起),目录别套太深,一层就好,别搞嵌套分类。
2.5 Skill 是怎么被加载的:渐进式披露
这是整篇文章最该搞懂的机制。AI不会把你所有Skill一股脑全读进脑子,那样既慢又乱。它用的办法官方叫渐进式披露(progressive disclosure),翻成人话就是:用到哪本才翻哪本,用到哪页才翻哪页。分三层。
第一层,元数据。AI一开机,只把每个Skill的name和description读进来,正文一概不读。这一层每个Skill只占大约100个token,就是一句话简介的量级。所以你哪怕装了几十个Skill,平时也几乎不占地方、不拖慢它。
第二层,正文。当你说的任务跟某个Skill的description对上了,AI才把那一个Skill的SKILL.md正文完整读进来,照着做。这一层官方建议控制在5000个token、500行以内,就是为了读得快。
第三层,资源。只有真用到时,AI才去读scripts、references、assets里的具体文件。脚本更特殊,它是被运行,源码不进上下文。
三层下来,效果是任何一刻进AI脑子的内容都尽量少。记住这个”少喂”的特点,第六章回答”黑箱”问题时全靠它。
2.6 看一个官方真 Skill:PDF 技能长什么样
光说不练没体感,来看Anthropic官方那个处理PDF的真Skill,它就在GitHub的anthropics/skills仓库里。它的文件夹是这样:
pdf/
├── SKILL.md
├── LICENSE.txt
├── reference.md # 进阶用法、排错
├── forms.md # 填PDF表单的专门流程
└── scripts/
├── extract_form_field_info.py
├── fill_fillable_fields.py
├── convert_pdf_to_images.py
└── ...(共八个脚本)
它的description写得很见功力,几乎把所有可能的触发场景都列了:读取或抽取PDF文字表格、合并拆分、旋转页面、加水印、新建、填表单、加解密、抽图片、对扫描件做OCR,只要用户提到 .pdf文件或要生成PDF,就用这个Skill。这就是好description的样板,把”什么时候该用”写得密不透风。
正文则是一份PDF处理指南,讲该用哪个Python库、哪个命令行工具,并且明确说”填表单看forms.md,进阶看reference.md”,把细节甩给了references文件。八个脚本则是确定性的活,比如抽取表单字段那个,AI直接运行就拿到结果,不用把整个PDF读进脑子。一个标准的渐进式披露布局,正文管主干,references管细节,scripts管脏活。
顺带说一句官方都提供了哪些现成Skill。claude.ai和API上自带四个文档类预建技能:pptx做PowerPoint、xlsx做Excel、docx做Word、pdf处理PDF。GitHub仓库里还开源了一批Skill,比如帮你做Skill的skill-creator、帮你搭MCP服务的mcp-builder、查Claude API文档的claude-api、做网页测试的webapp-testing、写内部沟通文档的internal-comms等等,照着改是最快的入门法。
2.7 哪些事不适合做成 Skill
知道什么该做成Skill,也得知道什么不该,免得白费劲。有几类事做成Skill并不划算。
一次性的事不必做。你这辈子可能就用一次的需求,直接写句prompt就完了,专门建个文件夹反而麻烦。Skill的价值全在”反复用”,用一次就摊不平做它的成本。
要求每次都变的事做不了。Skill装的是固定流程,如果你每次的要求都不一样、没有可沉淀的套路,那它就没东西可写。它适合”格式固定、内容变”,不适合”格式也天天变”。
纯粹查实时信息的事它管不着,那是MCP的活。比如”查一下今天的汇率”“看看我邮箱里最新一封信”,这些要的是连接外部数据,得靠MCP那套接口,Skill帮不上忙。一句话,Skill管”怎么做事的固定知识”,不管”实时去哪取数据”。
三、手把手做你的第一个 Skill
理论够了,这一章带你从零做一个能跑的Skill。就拿”整理周报”这个最常见的需求开刀,每一步给你能直接抄的内容。

3.1 选题:找一件你反复做的事
第一个Skill别贪复杂,挑一件你确实在反复做、而且每次规矩都差不多的事。判断标准很简单:如果你发现自己在不同对话里一遍遍打同一段prompt,那就对了。
适合开刀的典型有这些。按固定格式写周报月报,按公司口径回客户邮件,把杂乱的客户名单清洗成统一格式,按一份清单审查合同条款,把会议录音整理成”结论加待办加负责人”的纪要,按品牌调性写一批文案。这些事的共同点是要求固定、只有内容每次不同,最适合做成Skill。下面我们用周报。
3.2 第一步:建文件夹和 SKILL.md
先建一个文件夹,名字就叫weekly-report,记住文件夹名以后要和SKILL.md里的name一致。在文件夹里新建一个文本文件,命名为SKILL.md(建议大写,最稳)。
把下面这些内容原样抄进去,这就是一个最小可用的Skill:
---
name: weekly-report
description: 按公司格式整理每周工作周报。当用户说"写周报""周总结""整理本周工作"时使用。
---
# 周报整理
把用户给的零散工作内容,整理成公司标准格式的周报。
## 步骤
1. 先写"本周完成",每条一句话,句末用括号标注负责人。
2. 再写"下周计划",格式同上。
3. 全文语气正式,不用感叹号和表情。
4. 结尾附一个三列表格:项目、进度、风险。
## 示例
本周完成:
- 完成X模块联调,进入测试(张三)
下周计划:
- 上线X模块,跟进线上数据(张三)
到这一步,一个能用的Skill已经做完了。全是大白话,没有一行代码,你写的就是一份你早就会的操作说明,跟编程不沾边。
3.3 第二步:把 description 写对,这是触发的唯一钥匙
第二章说过,description是AI决定用不用这个Skill的主要依据。这句话写得好不好,直接决定你的Skill会不会被想起来,所以单独拎出来讲。
道理在于AI平时只看得见每个Skill的name和description(第一层加载)。你说”帮我整理一下这周干的活”,AI扫一遍所有description,看哪个对得上。如果你的description写得含含糊糊,它就认不出来,这个Skill就被晾在一边,永远不被调用。
对比一下好坏。差的写法:”周报工具。”这句话既没说清干什么,也没说什么时候用,更没有能对上”这周干的活”的关键词。好的写法:”按公司格式整理每周工作周报。当用户说写周报、周总结、整理本周工作、汇报这周进展时使用。”它把功能和触发场景都说全了,还铺了好几个用户可能用的说法当关键词。写description的诀窍就一条:把用户可能怎么开口,尽量都塞进去。
3.4 第三步:写正文步骤,附上样板
正文就是上面那段三道横线下面的内容。写法很直白,先一句话说清这个Skill干什么,再用编号把步骤列清楚,最后给一个填好的样板。
样板这一步别省。AI看一个具体的好例子,比读三行抽象描述学得快得多。周报Skill里那段”本周完成:完成X模块联调(张三)”,就是给AI看的标准答案,它会照着这个样子输出。能给例子的地方都给例子,这是让Skill稳定的最便宜的办法。
3.5 第四步:长了就拆,加一个 references 文件
如果你的格式规矩很多,正文眼看要超过500行,就该拆了。做法是在文件夹里建一个references子目录,把详细规矩挪进去,比如建一个references/format-rules.md,里面写满各种边角情况:节假日那周怎么写、跨部门项目负责人怎么标、数字精确到几位。
然后在正文里留一句话指路:”详细的格式规范见references/format-rules.md。”这样AI平时只读精简的正文,真碰到复杂情况才去翻那份细则。正文保持清爽,细节又不丢,这就是渐进式披露在你自己Skill里的用法。
3.6 第五步:确定的活写成 script
到这里Skill还只是”会自动翻出来的prompt”。要用上它真正的杀手锏,就把确定性的活儿写成脚本。
举个周报里就有的例子。结尾那个三列表格,如果数据来自一个Excel,让AI一格一格读、一格一格算总和,又慢又可能错。正确做法是在scripts里放一个小程序,比如scripts/make_table.py,让它读Excel、自动算好每列的合计、生成表格。AI只负责运行这个脚本,确定的答案直接出来。
再看官方那个更典型的。Anthropic的PDF技能里有段Python程序专门抽PDF表单字段,AI直接运行就拿到结果,不用把整个PDF读进脑子。凡是排序、求和、格式转换、批量改名这类有标准答案的活,都交给脚本,比让AI一个字一个字生成又快又准。这一步需要一点点编程,但零基础阶段可以先跳过,等周报Skill跑顺了再回来加。
3.7 第六步:自检
做完跑之前,对着几条硬规矩自检一遍。文件夹名和SKILL.md里的name是否一致。name是否只用了小写字母、数字、连字符,有没有不小心写成大写或带空格。description有没有把”什么时候用”说清楚。正文是否在500行以内。引用的文件路径是不是相对路径、是不是只放了一层。
如果你想更省心,开放标准官方提供了一个校验小工具,在github的agentskills/agentskills仓库里,跑一句 skills-ref validate ./weekly-report 就能帮你检查格式对不对。零基础阶段不用它也行,肉眼对着上面几条过一遍就够。
3.8 第七步:实际跑通,认识几个常见坑
做完先让AI实际用一次,别急着收工。你说一句该触发它的话,看它有没有照着你的步骤来。多数人第一次都会卡在几个固定的坑上,提前认识一下能省很多排查时间。
最常见的是它压根没被触发,你说了该用的话它却自顾自地答。十有八九是description没写好,回3.3节,把用户可能的说法多塞几个进去。在Claude Code里可以直接问”有哪些skill可用”,确认它到底有没有被加载进来。
第二个坑是name和文件夹名对不上,或者name里混进了大写字母、空格、下划线。规矩很死,只能小写字母、数字、连字符,且必须跟文件夹同名,错一个字符就可能加载失败。
第三个坑只在claude.ai出现,上传后死活用不了,往往是代码执行没开。回4.1节先确认那个开关。还有一个高频小错是打包,zip解开后不能多套一层,里面第一层必须直接是你那个Skill文件夹。
第四个坑跟脚本有关,脚本跑不起来。先看运行环境,Claude Code能联网、能用本机的包,但API的容器不能联网、不能临时装包,你的脚本如果依赖某个没预装的库,在API那边就会失败。
最后一个偏经验:description写得太泛会”误触发”。比如你写”整理文档”,结果用户一提到任何文档它都跳出来抢活。触发场景写得具体一点、贴着真实用法,比写得宽泛安全。
3.9 再做一个:代码审查 Skill
举一反三,照同样的套路再做一个,你就彻底会了。这次做代码审查,针对前面1.1节那个”每次都要叮嘱检查空指针、没关的文件、硬编码密码”的痛点。文件夹叫code-review,SKILL.md这么写:
---
name: code-review
description: 按团队清单审查一段代码,检查常见隐患。当用户说"审一下代码""code review""检查这段代码"时使用。
---
# 代码审查
按下面的清单逐项检查用户给的代码,列出问题和改法。
## 检查清单
1. 空指针:有没有可能为空的变量直接被使用。
2. 资源:打开的文件、连接有没有确保关闭。
3. 密钥:有没有把密码、token硬编码在代码里。
4. 错误处理:异常有没有被吞掉而不报。
## 输出格式
每发现一处,写成"位置 + 问题 + 建议改法"三段,没问题就明确说通过。
跟周报Skill一模一样的骨架:两个必填字段,一段带触发词的description,一份编号清单当正文,再加一句输出格式的约定。以后你说”审一下这段代码”,这四条规矩它自己就调出来逐项过,你再不用每次背一遍。换任何一件你反复做的事,套路都是这个。
四、把 Skill 装进 Claude 用
Skill做好了,怎么让Claude真的用上?Claude有三个入口,网页和桌面端、命令行工具Claude Code、面向开发者的API。每个的装法不一样,下面一个一个写清楚。

4.1 在 Claude.ai 网页或桌面端
普通用户最常用这个,套餐从免费到企业版都支持,但有个前提开关得先打开。
先开代码执行。免费、Pro、Max用户进设置里的Capabilities,确认”Code execution and file creation”(代码执行与文件创建)是打开的。团队和企业版要由管理员在组织设置里先开。为什么要先开这个,因为Skill跑起来依赖代码执行的能力。
再打开Skills。代码执行开了之后,在左边栏找到Customize下的Skills(有些较旧的文档里这个入口叫Settings下的Features,指的是同一处,以你登录后实际看到的为准)。进去能看到四个内置技能,PowerPoint、Excel、Word、PDF,逐个打开就能用。
上传你自己的Skill。在Skills界面点加号,再点”Create skill”,上传一个zip压缩包。注意压缩包的结构,zip解开后第一层必须就是你那个Skill文件夹,别多套一层。也就是把weekly-report这个文件夹直接压成weekly-report.zip。个人用户上传的自定义Skill默认归个人使用。Team和Enterprise还可以由管理员在组织层面统一配置或下发Skill。
怎么触发。代码执行开着的时候,Claude会在合适的时候自动调用,不用你专门下命令。你说”做一个Q3业绩的PPT”,它自动用上pptx技能。你说”整理本周周报”,它自动翻出你那个weekly-report。
还有一条不用自己写、直接拿来用的路子。Skills界面里点加号有个”Browse skills”,那是一个把技能、连接器、插件合在一起的目录,里面有官方和合作伙伴做好的现成技能,看中哪个点”Install”就装上,装完默认就启用。自己懒得写、或者想找个好样板照着改,先来这儿逛一圈。
4.2 在 Claude Code(命令行)
Claude Code是装在终端里的命令行工具,程序员用得多。它只支持你自己的Skill,没有那四个预建文档技能。好处是它纯靠文件系统,不用上传,把文件夹放到对的位置就行。
放哪里决定谁能用。放进 ~/.claude/skills/weekly-report/SKILL.md,就是个人级,你所有项目都能用。放进某个项目里的 .claude/skills/weekly-report/SKILL.md,就只在那个项目里管用。企业还能通过统一配置给全组织下发。
怎么调。Claude Code一启动,就把所有Skill的name和description载进来(还是每个约100个token),完整正文留到被调用时才读。触发有两种,一种是让Claude看着description自动调,一种是你手动敲斜杠命令,文件夹叫weekly-report,命令就是 /weekly-report。一个贴心细节,你在会话里改了Skill内容,当场就生效,不用重启。
同名冲突有个优先级,企业下发的盖过你个人的,个人的盖过项目的,都盖过同名的内置技能,记住这个顺序就不会撞车。Claude Code的Skill还能玩一个进阶花样,在正文里用一行命令注入实时上下文,比如写一行让它先跑 git diff 再把改动喂给自己,这样代码审查Skill每次都对着最新的改动审,不用你手动贴。
排查和生成。想知道现在有哪些Skill可用,直接问Claude “有哪些skill可用”。格式有没有问题,跑 /doctor 或者带 --debug 启动能看到。还有那个官方的skill-creator,它是个插件,用 /plugin install skill-creator@claude-plugins-official 装上,能帮你把”写测试、跑评测、对比效果”这套迭代自动化。
4.3 通过 Claude API(开发者向)
如果你是要把Skill接进自己的程序,那走API。这部分给开发者看,零基础读者了解个大概即可。
三个beta开关要带上。在请求头里加三个beta标记:code-execution-2025-08-25、skills-2025-10-02、files-api-2025-04-14,分别对应代码执行、技能功能、文件读写。
Skill必须配合代码执行工具,并在container里点名要哪些Skill。一个完整的Python调用大致这样:
import anthropic
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
betas=["code-execution-2025-08-25", "skills-2025-10-02"],
container={"skills": [
{"type": "anthropic", "skill_id": "pptx", "version": "latest"}
]},
tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
messages=[{"role": "user", "content": "做一个关于可再生能源的演示文稿"}],
)
上传自定义Skill走另一个接口,把整个文件夹打包发到 /v1/skills,整包要小于30MB,name、description的约束跟前面一样。单次请求最多挂8个Skill。要留意API的运行环境有限制,容器里不能联网、不能临时装新的依赖包,只能用预装好的,跟Claude Code那种能联网的环境不一样。
4.4 怎么确认 Skill 真被调用了
写了Skill,最怕的是它压根没被触发,自己还不知道。三个平台各有看得见的信号。
在claude.ai,Claude思考过程里会冒出一行”Reading某某技能”,比如”Reading weekly-report”,看到这行就说明它真去翻你那本手册了。在Claude Code,你会看到对应的Skill工具被调用,或者你手动敲的斜杠命令生效。通过API,响应里会出现code_execution工具的调用块,那是Claude在容器里读SKILL.md、跑脚本。
如果你说了该触发的话它却没动静,十有八九是description没写好,回到3.3节重新打磨那一行。
4.5 三个入口对照
把上面三个地方并排一下,方便你选。
| Claude.ai网页/桌面 | Claude Code | API | |
|---|---|---|---|
| 适合谁 | 普通用户 | 开发者、命令行党 | 接进自己程序 |
| 怎么装 | 上传zip | 放进skills目录 | 打包上传或引用 |
| 预建文档技能 | 有(4个) | 没有 | 有(4个) |
| 前提 | 先开代码执行 | 直接放文件 | 带beta头 |
| 共享范围 | 个人上传默认个人使用;Team/Enterprise可组织级下发 | 看放哪个目录 | 同workspace |
五、同一个 Skill 能搬到 OpenAI、Gemini 吗
这是很多人最关心的问题:我费劲为Claude写的Skill,换个工具还能用吗?答案是很大程度上能,因为它是开放标准。但完全一字不改地搬通常做不到,差异在哪,这一章讲透。
5.1 开放标准是什么意思
2025年12月18日,Anthropic把Agent Skills的规格作为开放标准公开,规范挂在http://agentskills.io这个网站上,谁都能看、能照着实现。标准化的就是前面讲的那几样:文件夹布局、SKILL.md的格式、那几个frontmatter字段、渐进式披露的三层加载。
开放的意思是,别的AI工具只要照着这份规范实现,就能读懂同一个SKILL.md。这也是为什么短短时间里,Claude、Codex、Gemini CLI等工具都开始支持这套格式。再强调一遍前面那个容易混的点:开放标准不等于交给基金会,Agent Skills目前还是Anthropic主导加社区贡献,规范的GitHub仓库是agentskills/agentskills,里面还带一个校验工具。
5.2 OpenAI Codex 怎么用
OpenAI这边承载Skill的是Codex,包括CLI、IDE扩展和Codex app,用法跟Claude Code很像,差别在文件放哪。
Codex找Skill的地方是 .agents/skills(仓库级)和 ~/.agents/skills(用户级),注意这个目录名跟Claude的 .claude/skills 不一样。SKILL.md本身的格式照旧,name和description照样必填。Codex还有自己的一点扩展,可以另配一个 agents/openai.yaml 写显示名、图标这些,但那是Codex专属的,不影响SKILL.md通用。
5.3 Gemini CLI、Cursor 怎么用
其他几个主流工具大同小异,都读同一个SKILL.md,只是目录位置和触发方式各有讲究。
Google的Gemini CLI,Skill放在 ~/.gemini/skills/ 或者通用的 ~/.agents/skills/,匹配上之后它会弹一个确认框问你要不要启用,也有 /skills 命令管理。Cursor也开始支持Agent Skills,但目录、触发方式和扩展字段还在快速变化,写跨平台Skill时不要把Cursor专属字段当成通用标准。
一个贴心的设计是,Codex和Gemini CLI都认一个公共目录 ~/.agents/skills/,你把Skill放这儿,多个工具能一起读到,省得每家复制一份。Cursor等工具也在向这套路径靠拢,但具体支持以各自文档为准。
把各家的目录放一张表里,你要往哪搬一目了然。同一个weekly-report文件夹,放进对应位置即可,SKILL.md内容不用动。
| 工具 | 个人级目录 | 项目级目录 | 触发方式 |
|---|---|---|---|
| Claude Code | ~/.claude/skills/ | .claude/skills/ | 自动,或 /技能名 |
| OpenAI Codex | ~/.agents/skills/ | .agents/skills/ | 自动,或斜杠 |
| Gemini CLI | ~/.gemini/skills/ | .gemini/skills/ | 自动,弹窗确认 |
| Cursor | 以官方文档为准 | 以官方文档为准 | 自动或手动触发,依版本而定 |
具体到OpenAI这边走一遍,三步就用上。把你的Skill文件夹放进项目里的 .agents/skills/(或用户级的 ~/.agents/skills/),SKILL.md保持原样,name和description照旧。然后在Codex里正常提需求,它会自动匹配,也可以打斜杠手动选。要给Codex加点专属设置(显示名、图标),可以另放一个 agents/openai.yaml,但那是Codex的扩展,不影响这个Skill在别处通用。Gemini CLI也类似,只是多了启用确认和 /skills 管理流程。
5.4 可移植的真相:哪些原样通用,哪些会绊倒你
诚实地说,”一份Skill到处跑”在最小范围内成立,但别指望连放置路径和高级功能都零改动。
真正通用的有这些。SKILL.md这个格式本身是跟工具无关的。最稳的最小公分母是name和description两个字段,几乎所有工具都认。脚本用Bash和Python最保险,这两种各家都可靠支持。
会绊倒你的也有这些。一是目录位置各不相同,Claude是 .claude/skills,Codex是 .agents/skills,Gemini是 .gemini/skills。二是那些高级字段和附加配置各认各的,比如allowed-tools支持情况会因客户端而异,openai.yaml是Codex扩展,换个平台就不一定认。三是脚本能不能跑、跑得一样不一样,取决于每个工具的执行环境,Bash和Python之外不保证。
5.5 写”一份多用”Skill 的实操建议
把上面的真相落成可操作的几条。
保持核心干净:共享的Skill里,frontmatter只留name和description这两个通用字段,平台专属的那些别往主文件里塞。脚本只用Bash和Python,别用冷门语言。目录结构保持扁平,就是 skills/某技能/SKILL.md,别搞嵌套分类,因为有的工具只可靠支持扁平结构。想多个工具共用,优先放进公共的 ~/.agents/skills/。做到这几条,你就能”写一份,多处用”,平台之间顶多挪挪文件夹位置,核心内容不用动。
六、核心追问:写了 Skill,是不是照样进黑箱
把怎么做、怎么装、怎么跨平台都讲完了,回到那个最让人犯嘀咕的问题。你写prompt时一直有个隐忧,话说进去了,AI到底怎么用、会不会漏听、会不会理解偏,你看不见。那Skill破解了这个黑箱吗?

6.1 什么叫黑箱
先把黑箱说清楚。你给AI三条要求,它办了两条漏了一条,你事后才发现,却不知道它当时为啥漏。这种”话进去了,内部怎么处理你看不见”的状态,就是黑箱。写prompt的人都碰过。
6.2 对的一半:手册读进去那一刻,就成了 prompt
诚实的答案分两半,先说让你泄气的那一半。
当AI把那本SKILL.md的正文读进脑子之后,那段文字和你手打的prompt没有任何区别,它就是prompt。所以你对prompt的一切无奈照样适用,它会不会漏掉第三步、会不会把语气理解偏、内容一长注意力会不会飘,该不确定的还是不确定。Skill算不上一种新的”让AI更听话”的魔法,它只是一种新的”把话递过去”的方式。
更微妙的是,你的黑箱从一个变成了两个。原来的黑箱是”它怎么处理我给的文字”,现在前面又多了一个,”它到底会不会想到去翻我这本手册”。如果你那句description写得含糊,AI扫一圈认不出该用它,它压根不会被抽出来。这就是为什么第三章反复强调要打磨description,那是你唯一能影响它”想不想得到”的旋钮。
6.3 不对的一半:两个地方真的绕开了黑箱
这才是Skill存在的意义,它在两个地方实打实地绕开了黑箱。
第一个地方,它让你能控制喂多少、什么时候喂。写prompt你唯一的杠杆是措辞。Skill靠渐进式披露多给了你一个控制面,任何一刻进AI脑子的内容更少,能被读错的东西自然就更少。黑箱本身没变小,但你学会了少往里塞东西。一句话概括,prompt是”我说什么”,Skill是”我说什么,外加一套决定何时说、说多少的机制”。
第二个地方更硬,那个写成脚本的部分,根本不经过黑箱。当一个步骤被写成脚本、让AI去运行而不是去理解时,它就彻底跳出了黑箱,靠的是一段确定的程序跑出一个确定的结果。给一列数字求和,代码永远算对,AI心算却可能出错。凡是你能塞进代码的环节,就再也不用赌AI听不听话了。
所以最终答案是,Skill没把prompt的黑箱变透明,它干了件更聪明的事,让必须穿过黑箱的东西变少了。一方面每次只把相关的那一小本递进去,另一方面把可靠确定的活儿写成代码直接绕过AI。你担心的”写了也进黑箱”,对那本手册的文字正文来说确实如此,那部分你还得像打磨prompt一样打磨它。但Skill给了你两样prompt没有的武器,少喂,和用代码绕开。
6.4 安全:恶意 Skill 的风险
正因为Skill里能夹会运行的程序,它带来一个prompt没有的风险。一个怀有恶意的Skill,能指挥AI做出跟它声称用途完全不符的事,比如偷偷把你的数据传走、越权访问你的文件。
这不是危言耸听,Anthropic官方自己就明确警告了。2025年12月,有安全团队演示过一个伪装成”GIF生成器”的Skill,表面人畜无害,背地里却让AI跑起了勒索程序。所以”像随手下载别人代码仓库一样抓个Skill来用”,风险比抄一段prompt严肃得多。原则很简单,只用你自己写的,或者来源确实可信的。
七、零基础的学习路径
最后给一条从零到熟练的路。
7.1 心态:当成给实习生写 SOP
别把它当写代码,就当成给一个新来的实习生写一份岗位说明。你能把一件事教明白一个人,你就能写一个Skill。区别只在于,这回读说明的是AI,而AI比实习生更听话,也更需要你把话写清楚、把步骤写全、把例子给够。
7.2 进阶:拆分、脚本化、版本管理、打包分享
第一个Skill跑顺之后,往这几个方向加深。正文长了就往references拆,让主文件保持精简。把确定性的活逐步写成scripts,让结果更可靠。因为Skill就是文件夹,你可以用Git做版本管理,改坏了能回退,还能看到每一版改了什么。做好的Skill还能打包进一个插件分享给同事,把它放进团队共用的代码仓库,让一个人的习惯变成一个团队的资产,新人入职拉一下仓库,全套规矩就到手了。
这里有个心法值得记住:一个Skill别贪大求全。与其做一个”什么都管”的巨型Skill,不如拆成几个职责单一的小Skill,一个管周报、一个管代码审查、一个管邮件。小而专的好处是description好写、触发准、维护也简单,这跟程序员说的”一个函数只做一件事”是同一个道理。
7.3 偷懒捷径:用 skill-creator 生成器
不想从零写,有捷径。Anthropic提供了skill-creator,你用大白话描述需求,它就替你把Skill文件的架子搭好。Gemini CLI也有创建和管理Agent Skills的官方流程。先让工具出个初稿,你再改,比从零写省事得多。Anthropic那个skill-creator还能帮你跑评测、对比开不开这个Skill的效果差别,把打磨过程自动化。
7.4 系统学的去处
想系统学,去这几个地方。Anthropic官方有完整文档,还有一门免费课叫Introduction to Agent Skills。DeepLearning.AI上有一门专门的短课Agent Skills with Anthropic。开放标准的主页http://agentskills.io上能看到完整规范,GitHub上的anthropics/skills仓库里有一大堆现成的官方Skill,照着改是最快的入门方式。
结尾
把这篇压成一句话:prompt是你每次重新交代的一句话,Skill是你写好放在书架上、AI会自己取用的一本说明书,这本说明书有固定的格式(一个文件夹加一个SKILL.md),能装进Claude的三个入口,也能搬到OpenAI Codex、Gemini CLI等支持Agent Skills的工具里,而且里面能夹一段直接运行的代码,让最该靠谱的那部分活儿根本不经过AI的理解。
它没让AI变得更透明,它只是让你更聪明地决定,什么该交给AI去读,什么干脆别让它读、直接算出来给它。对一个零基础的人来说,这件事的门槛低得超出你的想象。它要你拿出的,不过是把一件早就会做的事,认认真真写下来的那点耐心。现在就挑一件你每周都在重复交代的活,建个文件夹,写下第一行name,你的第一个Skill就开始了。