这两年做AI编程和Agent相关的工作，我最大的感受是：真正的生产力瓶颈往往不在模型本身，而在于你怎么把重复性的"专家经验"沉淀下来。以前我新开一个Claude Code会话，总是要重新念叨一遍"你是资深前端工程师""遵循项目的Tailwind规范""别用class组件""组件注释要写中文"，烦不胜烦。直到我把这套流程做成一个Skill文件，事情才彻底改观——Agent遇到相关任务会自动加载它，不用我每个新会话里手动粘贴一堆要求。这篇就围绕Skills这套机制，把我从概念理解、实际安装、踩坑到亲手造轮子的完整经历拆开聊，希望能给你一个可以照做的参考路径。
1. 为什么2025年大家都在谈Skills：从prompt到技能包的范式转移
1.1 传统prompt的三个致命痛点
先说痛点。如果你用Claude Code、Codex或者类似工具写代码超过一两个月，大概率会撞上这几个问题。
第一，一次性。每次新开对话，之前精心设计的prompt全白费了。要么你手动重新粘贴，要么干脆凭感觉现场发挥。时间一长，你积累的不是经验，而是几百条改了又改、来了又走的"一次性咒语"。
第二，上下文污染。很多人写prompt喜欢"以防万一"式地塞背景信息，比如一口气写800字项目背景、技术栈、注意事项。但这些信息在Agent真正执行任务时，很多都用不上。既增加了token消耗，还干扰了模型对核心任务的理解。我见过一个同事的系统提示词长达3000字，结果Agent每次都把无关规则当成高优先级指令，反而把真正要写的逻辑搞砸了。
第三，不可复用。团队里A有一套前端规范咒语，B有一套自己的前端规范咒语，俩人互相看不到，更别提统一。项目一多，维护成本直接起飞。
1.2 Skills的本质：把"入职培训手册"交给Agent
那Skills是怎么解决这三个痛点的？我后来琢磨出一个比较贴切的类比：它相当于给Agent配了一份"入职培训手册"或"操作SOP"。
传统prompt是你每天在Agent耳边反复叮嘱"一定要注意xxx"。而Skills是你在Agent的工位上放了一本手册，上面写着："遇到前端组件任务时，先翻到第3页看规范；输出代码前，对照第8页的检查清单自查一遍。"Agent自己会根据任务类型，决定要不要翻开这本手册，以及翻开哪一部分。
从技术形态上说，一个Skill就是一个SKILL.md文件（Markdown格式），放在约定的目录里就生效。文件分两部分：头部是YAML格式的元信息，包含技能名称和描述；正文是具体的操作指令、模板、示例、禁忌事项，Anything goes。
这种设计的好处非常直接：
- 按需加载。Agent平时不会把Skills内容塞进上下文，只有判断任务相关时才加载。相比"把所有prompt都堆在系统提示词里"，上下文干净得多。
- 可复用。一个Skill改好了，放团队仓库里，大家都能用。
- 可版本管理。Markdown文件丢进git仓库，每次改动diff一目了然。
我自己使用后最明显的变化是：新开会话不用再重复"教育"Agent。只要说"帮我用现有技术栈生成一个用户列表组件"，它会自己去找对应的Skill，然后按里面的规范输出。
1.3 为什么Anthropic、OpenAI和吴恩达都在推同一件事
说实话，一个概念被这么多大厂同时盯上，在我的经验里不多见。Claude Code把Skills设成了核心能力模块，OpenAI的Codex也在做类似机制，连Google那边的Agent开发方向也在往"行为树+技能库"的路子上靠。社区里有人还在讨论"GPT-6 Astra时代，需要重新思考Skills和Prompt的关系"。
吴恩达在2025年的Agent Skills教程里讲了一个我很认同的观点：要让Agent稳定完成复杂任务，与其依赖一条写满所有规则的巨型prompt，不如拆成一个个内聚的、可独立调用的技能模块。这样说可能有点抽象，但用到实际场景里就很好懂：
- 一个"React组件生成"Skill，里面就只管React组件规范。
- 一个"数据库表结构设计"Skill，里面就只管表结构怎么设计。
- 一个"PR描述生成"Skill，里面只管怎么写PR描述。
每个技能边界清晰，互不干扰，Agent在具体任务里按需调用。Skill做得好不好，直接决定Agent干活靠不靠谱，这也解释了为什么"skills harness"这个概念会流行起来——一个会正确装配技能库的工程师，能同时指挥多个Agent完成比单个Agent复杂十倍的工作流。
2. 拆开看SKILL.md：一个技能文件的设计逻辑与技术细节
2.1 一个最小的SKILL.md长什么样
先看一个最简例子。假设我们要给Agent配一个"前端React组件生成"技能，SKILL.md大概长这样：
--- name: react-component-generator description: 当用户需要在React + TypeScript项目中创建或修改UI组件时使用。包含组件代码规范、样式约定、测试要求和导入导出规则。 --- # React组件生成规范 ## 技术栈约束 - React 18 + TypeScript - Tailwind CSS - 函数式组件，禁止使用class组件 ## 组件代码结构 1. 导入依赖 2. 定义Props接口 3. 组件函数实现 4. 默认导出 ## 示例 ```tsx import React from 'react'; interface UserListProps { users: User[]; } const UserList: React.FC<UserListProps> = ({ users }) => { return <ul>{users.map(...)}</ul>; }; export default UserList;自查清单
- [ ] 所有Props都定义了接口
- [ ] 样式类名遵循Tailwind规范
- [ ] 导出方式为默认导出
- [ ] 关键逻辑有中文注释
这个文件的核心信息全在frontmatter里：`name`是技能的唯一标识，`description`决定了Agent什么时候加载这个技能。 ### 2.2 三种存放位置：项目级、用户级和团队级 Skills按作用域分三种存放位置，我自己在实战中的推荐是这样的： | 存放位置 | 路径示例 | 适用场景 | |---------|---------|---------| | 项目级 | `.claude/skills/react-component-generator/SKILL.md` | 绑定当前项目，团队成员共享，随代码仓库走 | | 用户级 | `~/.claude/skills/react-component-generator/SKILL.md` | 个人常用技能，不随仓库分发 | | 团队级（通过Plugin管理） | Plugin仓库中的`skills/`目录 | 企业内部统一技能库，集中管控版本 | 我最常用的是项目级——跟项目绑定，团队拉下代码就有同一套技能，谁也不用手工复制配置。 ### 2.3 为什么description一栏直接决定技能的"智商" 遇到过很多朋友问：我Skill写了一大堆，Agent就是不主动用，为啥？十有八九是description写得不够"能匹配任务"。 Agent判断是否加载一个技能，靠的是把你当前的用户请求和每个技能的description做语义匹配。如果description写得含糊，比如"处理前端任务"，那当用户说"帮我改一下那个按钮的样式"时，Agent可能认为这个技能跟当前任务无关（因为"按钮样式"看起来不完全是"前端任务"），于是不加载。 我的经验是description要包含三要素： - 触发边界：什么样的任务需要这个技能？ - 任务类型：是生成代码、排查问题、还是写文档？ - 关键术语：任务里可能出现哪些词会命中这个技能？ 对比一下： ```markdown # 差描述 description: 前端开发相关技能 # 好描述 description: 当用户需要创建、修改或调试React+TypeScript项目中的UI组件、页面布局、样式逻辑时使用。涉及jsx/tsx文件编辑、Tailwind CSS类名设计、组件拆分与重构等任务时调用。好描述几乎把"什么时候该用它"写在了明面上，Agent一匹配一个准。用户级Skills还要特别注意：Skills的description会被Agent扫描，但正文内容只有在触发后才会被完整加载。
2.4 为什么Anthropic选Markdown而非其他格式
很多人第一次看到SKILL.md都会问：为什么不是JSON、YAML或者专用DSL？
我的理解是：Markdown恰好是"人类可读、AI可解析、工程师可版本管理"三者的最优解。
- 对普通用户来说，写Markdown没有学习成本。
- 对模型来说，Markdown的结构化信息（标题、列表、代码块）容易解析，frontmatter又提供了机器可读的元信息。
- 对工程团队来说，Markdown文件的diff非常清晰，谁改了什么一目了然，不像JSON文件稍微动一下整坨都乱了。
Anthropic官方的那套规范我强烈建议读一读，特别是关于目录命名（小写字母、数字、短横线）和SKILL.md文件名的要求。新版本的Claude Code已经支持/skill命令手动触发，编辑Skills后的热加载体验也比早期流畅不少。
3. 实操避坑：Skills安装的依赖环境、npx add与源码安装的完整步骤
3.1 环境前置：先确认Agent客户端和Node环境
装Skills之前，先检查环境。以Claude Code为例，确认客户端版本不能太老，老版本不支持Skills自动加载。我实际环境是：Node.js 18+，Claude Code版本通过npm保持最新。
安装社区Skills前，建议先执行一下：
claude --version node -v版本没问题，再继续后面的操作。如果Claude Code版本过旧，先升级：
npm update -g @anthropic-ai/claude-code3.2 用npx直接安装社区Skill
社区Skills通常通过skills命令行工具（npm包，发布在@wsh-ai/skills等名字下）来安装，整个过程很像装npm包。以热词里那条vidmuse-skills为例：
npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y拆开看每个参数的意思：
sandai-org/vidmuse-skills：GitHub仓库地址，格式是用户名/仓库名。--agent claude-code：指定目标Agent，目前很多工具链支持claude-code、codex、opencode等。-g：全局安装。不加-g则默认安装到当前项目目录。-y：跳过交互确认，脚本执行时省事。
安装成功后会打印类似"Skill installed to ~/.claude/skills/"的日志。这时新开一个Claude Code会话，Skills就自动可用了。
3.3 手动的源码安装方式
npx skills add就行，但有些场景必须手工源码安装。比如：Skill仓库没有发布到skills工具索引里，或者你想修改Skill内容再本地安装。
我一般用这个流程：
git clone https://github.com/sandai-org/vidmuse-skills.git cd vidmuse-skills # 注意看仓库结构，有些根目录下一堆子目录就是skills ls -la如果仓库根目录下就是多个Skill子目录，比如skill-a/、skill-b/，而每个子目录里都有SKILL.md，那就把它们复制到Claude Code的用户级Skills目录：
mkdir -p ~/.claude/skills cp -r skill-a skill-b ~/.claude/skills/如果是项目级安装，就放到当前项目的.claude/skills/目录下：
mkdir -p .claude/skills cp -r skill-a .claude/skills/源码安装常见的一个坑是：仓库里不止一层目录，比如skills/skill-a/SKILL.md和skills/helper/skill-b/SKILL.md。这种情况直接复制整个skills目录往往没用，因为Claude Code不递归查找深层Skills目录（新版本有所改进，但旧版本不支持）。正确做法是把每个包含SKILL.md的目录单独提取到目标Skills根目录下。
源码安装后，启动Claude Code时会自动扫描Skills目录。如果没生效，先检查目录结构是否严格符合xxx/SKILL.md的模式，确保文件名为大写SKILL.md，不要写成skill.md。
3.4 安装后不生效？排查链路分享
说到安装后不生效，这个坑我踩过不止一次，把排查经验整理成流程：
确认安装路径。控制台直接执行
ls ~/.claude/skills/或ls .claude/skills/，看技能目录在不在。如果不在，多半是npx安装时选择了其他位置，或者-g参数没生效。验证SKILL.md文件名是否准确。文件名必须严格是
SKILL.md（全大写），系统不认skill.md或Skill.md。检查frontmatter格式。
name和description这两个字段必须存在，且description不能为空。YAML的冒号后面要有空格，这个最容易出错。重启客户端。有些版本的老客户端需要完全退出重进才能重新扫描Skills目录，遇到不生效时先试这个。
查看仓库原始结构。如果是源码安装，回到仓库确认到底哪几个目录是真正的Skill根目录，别把外层包装目录也复制过去了。
上面的步骤我都踩过。特别是第3条，有次一个Skill写好后怎么都不生效，排查半天发现是YAML把description: 当用户需要...写成了description:当用户需要...——冒号后面没空格。这种细节离谱但真实。
3.5 常用Skill管理命令
再补充几个我日常用的命令，当熟悉了以后效率会提升不少：
npx skills list # 查看已安装技能列表 npx skills add owner/repo --agent claude-code -g # 全局安装 npx skills add owner/repo --agent codex -g # 装到codex npx skills remove skill-name # 移除技能不同命令的安装位置和写法可能略有差异，建议npx skills --help先看一眼。习惯后你会觉得整个流程和npm install一样自然。
4. 亲手做一个自己的Skill：一个前端组件生成技能的完整设计过程
4.1 先定边界：一个技能只干一件事
我发现很多朋友第一次写Skill就想着"做一个全能的"。这是个坑。Skill的核心价值在"内聚"——一个小技能专攻一类任务，而不是试图解决所有问题。
拿我自己的项目举例。当时我负责一个React + TypeScript + Tailwind的后台管理系统，频繁要写列表页、表单页、弹窗组件。团队里每个开发写出来的组件风格都不太一样。于是我做了一个admin-component-generator的Skill，目标很单纯：让Agent在创建组件时自动遵循团队规范。
4.2 写SKILL.md的具体过程
我的目录结构长这样：
.claude/skills/admin-component-generator/ ├── SKILL.md └── examples/ ├── list-page.tsx └── modal-form.tsxSKILL.md的正文按照"规则先行、模板兜底、示例对照、自查收尾"四段式组织：
--- name: admin-component-generator description: 在React+TypeScript+Tailwind后台管理项目中创建或重构页面组件时使用。适合列表页、表单弹窗、详情页等CRUD场景。涉及table、modal、form、button等元素时调用。 --- # 后台组件生成规范 ## 技术约束 - React 18 + TypeScript - 样式一律使用Tailwind类名，禁止内联style - 组件均使用函数式写法，禁止class组件 - 中英文文案统一走i18n key ## 输出模板 列表页必须包含以下区块： 1. 搜索栏 2. 操作按钮区 3. Table表格 4. 分页器 ## 代码检查 - Props接口必须显式定义，禁止用any - 表格列必须带数据索引和宽度 - Modal标题必须有具体语义写完主体，我在examples/目录放了一个列表页和表单弹窗的参考实现。这样Agent加载Skill后不仅有一堆抽象规范，还能直接参照具体代码实例。效果立竿见影——同一个需求，改造前生成的代码风格还很随机，接入这个Skill之后，输出的组件几乎和团队里老成员手写的一模一样。
4.3 设计触发描述：反复测试出来的"匹配咒语"
写description时我反复打磨了很多遍。初版写的是"用于后台管理系统页面组件开发"，但测试发现命中率一般，后来改成"创建或重构后台管理系统的列表页、表单弹窗、详情页等CRUD组件时使用，涉及table、form、modal、search、pagination元素时调用"。同时我把描述中的"触发条件"尽量贴近业务词汇——用户说"加一个用户管理列表页"时，Agent就能自动匹配到它。
这一版描述实测效果很好。关键是：不要在description里堆砌抽象的"高级词汇"，直接写任务里会出现的名词和场景，机器匹配的准确率才最高。
4.4 内测与迭代：怎么验证Skill真的提升效率
Skill写完别急着直接投产，我建议开一个测试项目专门验证。流程是：
- 拿它生成一个真实业务组件，跟无Skill时的输出对比。
- 故意提一个边界需求，测试Agent是否错误加载了Skill（比如让它生成一个非React组件，看它会不会还套用这套规则）。
- 让同事提几个他们日常的高频需求，看Skill能否稳定命中。
经过这三轮测试，我把Skill里"自查清单"部分的排序调整过几次，也补了几个Tailwind使用规范。Skill的迭代不能靠拍脑袋，要看真实对话里的表现。
其实到这里，我已经把一套适合团队的"组件生成SOP"沉淀成了文件，放进了项目仓库。新同事入职只需要拉一次代码，Claude Code就会自动拥有这套技能，不用任何人给他讲"我们团队代码规范是这样的"。
5. 值得关注的Skills项目与扩展方向：从Superpower到数学建模、专利写作
5.1 Superpower Skills：社区功能最全的百宝箱
热词里反复出现的superpower skills，是目前社区热度最高的Skills合集项目。它内部集成了大量预设技能，覆盖写作、编码、数据分析、日常效率等多种场景。我最初接触这个概念时，就是先把它整套装进Claude Code里，通过翻它的Skill清单，才真正理解"把一个复杂工作流拆成技能模块"的实践方式。
装好之后最明显的变化是：你在对话里让它写Slug、生成周报、总结会议纪要，Agent都不用你一步步教，它自己会去调对应技能。虽然有些技能我不常用，但当作"高质量Skill设计范本"来读，价值也很大。如果你想快速理解"一个好Skill应该长什么样"，看它的代码结构是捷径。
5.2 垂直领域的技能包：视频生成、数学建模、专利写作
热词里还有几个方向，代表了Skills正在快速渗透进垂直领域。
vidmuse-skills就是视频生成方向的，安装命令和前面的npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y一条搞定，它把"从文案脚本到镜头拆解再到剪辑方向"整套视频生产流程固化成技能。
数学建模方向的Skills，我是在校学生朋友推荐的。这类技能主要把竞赛中常见的建模流程——问题分析、假设设定、模型选择、检验改进——固化成标准步骤，Agent拿到题目后按SOP走，不容易漏掉关键环节。
专利写作方向的Skills是热词给我的新启发。发明专利写作有很强的格式规范，包括技术领域、背景技术、发明内容、具体实施方式等，新手很容易写漏。这类Skill的价值就是"把专业文档的结构规范封装起来"，让Agent输出时自动带格式。公众号文章、结构图、报告生成等场景的Skills也是同一个逻辑。
其实你仔细观察会发现：凡是"有固定流程、有明确边界、需要专业知识沉淀"的任务，几乎都适合做成Skill。反过来，一个模糊的"帮我写点东西"就不太适合，因为缺乏任务边界。
5.3 安全评估类技能的边界提醒
热词里有"渗透测试skills"。这块我得专门说一句：安全评估类技能本身是合规的防御视角工具，但使用边界必须是授权测试。任何安全类技能的应用都应当在合法合规的前提下进行，强调授权、防御、漏洞修复视角。这里不对具体攻击方法做展开。把Skill的"安全红线"写进description里，也能让Agent在触碰敏感操作时保持克制。
5.4 UI/UX设计等其他热门项目
热词里还有uiuxpromax和opencode skills、codex skills等。uiuxpromax我初步了解是聚焦UI/UX设计规范的技能包，适合设计师或全栈工程师做界面时参考。opencode和codex则说明技能机制不绑定单一产品，OpenCode、Codex等Agent工具也有各自的Skills机制。你之前基于claude-code写的Skill，稍微调整下描述和目录，很可能也能迁移到Codex上。这种生态间的相互借鉴正在成为一种趋势。
6. Skills库的工程化管理与我的维护心得
6.1 版本管理与命名规约
Skill文件一多，管理就要跟上。我的做法是把项目级Skills直接放git仓库，改版记录天然留在commit历史里。命名上严格遵循"动词-名词"风格，比如react-component-generator、analysis-project-structure、write-pr-description，一眼能看出用途。不要出现test123这种无意义名字，Agent匹配时也会混乱。
6.2 测试与回归
每次修改Skill，我都会在测试项目里跑一遍"典型任务-边界任务"的组合，确保没有破坏已有功能。以前改过某个组件生成规范的描述，结果练测试任务时不那么准了，后来靠回归测试及时发现并回退。Skills的测试成本比普通代码低很多，因为不用写自动化测试用例，手动让Agent跑几个代表性任务就够了。重点是"每次改完必测"这个习惯。
6.3 边界思维：哪些事不该做成Skill
我见过一些人把一次性临时任务也封装成Skill，结果用一次就再也不碰，还给Agent造成大量description匹配干扰。我的经验是：一个Skill至少要在真实任务中被使用3次以上，才值得固化成文件；如果只是临时跑一次，直接在对话里给指令就好。判断标准很简单——你是不是每两周都会做同类事情。如果是，那就值得做成Skill；如果不是，别做。
6.4 我的几点维护体会
第一，Skill语言"宁白话勿华丽"，用团队成员都懂的话来写，不要写成法律条文。第二，定期清理没用的旧Skill。第三，Skill和普通文档不一样，它本身也是"可执行"的知识。修改完Skill最好在对话里实际跑一下，确认Agent真的读到了最新内容。
如今我自己的技能库已经覆盖了前端组件生成、代码分析、后端接口文档维护、PR描述撰写等高频场景。新项目初始化时，我会先复用之前Skill库里的通用部分，再根据项目特点补充专属内容。可以说，Skills把大量隐性的、靠经验才能传递的工程规范，变成了Agent可以随时调用的显性资产。这也是我在这轮AI编程浪潮里，感受到的最实际、最确定的一点增量。
