最近一两年，"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-style"skill，SKILL.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两边能互通，只要注意个别特殊标记就行。具体对比如下：

"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系为例：

1. 先找到全局技能目录。正常情况下是~/.claude/skills（Windows下是C:\Users\你的用户名.claude\skills）。如果目录不存在就自己建。
2. 把整个skill文件夹复制进去，注意保持目录结构完整，千万不要只拷SKILL.md而丢了scripts。
3. 重启或reload当前工具会话。Claude Code里可以输入/skill看到当前已安装的skill列表，Codex工具也有类似命令。
4. 验证：在对话里描述一个能触发你目标的场景，看它是否真的调用到了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}号, 期望第{prev+1}号" 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 加载失败排查速查表

这里特别说一下编码问题。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。