我不知道你是不是也注意到了这个现象最近技术圈里只要聊AI编程和AI智能体绕不开一个词——skills。从Claude Code、Codex、OpenCode到Cursor各个Agent都在推自己的技能生态GitHub上superpower skills、baoyu的skills合集动辄几千星连吴恩达都专门讲过agent skills的落地思路。有人说这是prompt的升级版有人说是把工作流打包成了插件我的看法更直接这是把原来存在你脑子和聊天记录里的那套做事方法终于变成了可以提交、可以审查、可以复用的工程资产。先说清楚skills是什么。你以前用AI干活得在对话框里把要求从头到尾说一遍你是前端专家先看设计稿再分析组件库最后输出带样式变量的代码。这套说辞每次都要复制、修改、补充AI的理解还经常跑偏。skills要做的事情就是把这一类特定任务的完整执行方案固化下来包括任务拆解、判断标准、参考规范、甚至能直接跑的脚本统一放进一个约定的目录结构里。Agent在遇到相关任务时会按这个方案去执行。这篇文章我结合自己在Claude Code、Codex、OpenCode上的实际使用经验把skills的安装、编写、排障以及不同场景下的精选技能包全部摊开讲一遍。1. 从Prompt到Skills一次工作流升级1.1 为什么提示词拼不动了我先说说自己的真实感受。早先我用GPT和Claude写代码最头疼的不是模型能力不够而是每次都要重新组织提示词。比如让AI做代码评审你得交代语言、项目背景、关注点、输出格式换成让AI写测试用例又得重新交代业务上下文和覆盖标准。这些交代一次两次还好一旦项目复杂起来提示词占了整个对话的大半篇幅真正留给模型思考的上下文反而不够了。后来我还尝试攒一个巨大的超级提示词把各种规则、示例、小技巧全部塞进去。很多人在网上分享过这种模板但我用下来效果并不理想。原因很简单上下文窗口是有限的几十条规则混在一起模型根本分不清当前任务该重点看哪条同时提示词越长模型注意力被稀释得越厉害容易既丢了细节又拖慢速度。skills这套机制解决的就是这个痛点。它把完整的任务规范拆成一个个独立、可加载的单元每个单元都有自己的清单、脚本和参考材料。Agent平时不会把它们全部塞进上下文只在任务匹配时才按需加载。这个设计和人脑的工作方式很像你不用随时记住公司所有规章制度的全文真到了报销、请假、审批这些具体场景再去查对应的流程手册就行了。1.2 Skills的目录结构长什么样一个标准的skill本质上是一个带规范格式的目录。我先拿一个典型的前端代码审查技能包举例frontend-review/ ├── SKILL.md ├── scripts/ │ └── analyze-diff.sh ├── assets/ │ ├── checklist.md │ └── senior-review-principles.md └── references/ └── team-coding-standards.md最核心的文件是SKILL.md它用Markdown编写头部带一段YAML格式的元信息类似下面这样--- name: frontend-review description: 用于前端代码评审。当用户给出PR或代码diff希望得到关于组件设计、样式方案、性能隐患的审查意见时使用。 ---description这段是整个技能包的灵魂后面我还会反复强调。除了SKILL.md其余目录都不是硬性要求但实际使用中非常有帮助。scripts/放的是可执行脚本比如分析diff、抓取页面信息assets/放辅助材料比如评审清单、设计原则references/放深度参考文档供Agent在需要时引用。如果做一个类比SKILL.md是菜谱脚本是已经处理好的半成品食材references是食材产地介绍。菜谱负责告诉AI这菜怎么做脚本替AI把麻烦的体力活干完参考资料则在AI拿不准时给它补背景知识。三者配合才能让一个技能包既稳定又好用。1.3 Skills与MCP、系统提示词的边界很多刚接触的人会把skills、MCP、系统提示词混在一起其实它们是三层不同东西。MCPModel Context Protocol解决的是AI能连到哪些外部工具和数据比如读数据库、操作浏览器、调设计稿解析服务skills解决的是AI拿到这些工具后该怎么按一套标准的流程干活系统提示词则是Agent启动时就常驻的、面向全局的底层规则。我打个比方MCP是给AI配了厨房里的烤箱、料理机、温度计skills是写着做这道蛋糕要先预热再打发再烘烤的流程手册系统提示词是贴在厨房门口的安全第一、随手关火这类底线要求。烤箱很重要但没有菜谱你只会干瞪眼有菜谱没有烤箱流程写得再漂亮也做不出成品。这几者的边界在实际中很微妙。一个好的skill通常会在SKILL.md里写清楚自己依赖哪些MCP工具、在哪个环节调用、期望拿到什么数据。比如一个网页设计稿还原的技能包就可以说明它需要调用浏览器截图MCP先循环截取设计稿的关键区块再执行还原流程。这样各司其职才能把问题拆解干净。2. 快速上手安装官方与第三方Skills2.1 一行命令装上热门技能包现在安装skills已经很成熟了社区生态基本都围绕skills add这个命令在转。我自己最常用的安装命令长这样npx skills add obra/superpowers --agent claude-code -g -y npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y第一行装的是GitHub上非常火的obra/superpowers里面包含了一批提升Claude Code工作流的能力擅长把复杂任务拆解成子任务再逐层执行第二行是视频生成方向的skill能帮助Agent将分镜思路与视频生成工具衔接出片效率比我手动描述高很多。这里面的参数值得解释一下。--agent claude-code是告诉安装器当前目标Agent是Claude Code不同Agent的skills目录位置不一样-g表示全局安装以后新建任何项目都能用-y相当于自动确认跳过交互式提问。如果你用Codex或OpenCode把--agent后面的值替换成codex或opencode即可。安装完成后我建议先验证一下位置。以Claude Code为例全局skills通常放在~/.claude/skills/下项目级skills则放在当前项目的.claude/skills/下。打开这个目录看到对应技能包的文件夹就说明装成功了。2.2 源码安装Skill的方法并不是所有skill都能用一行命令装好有些作者还没发布到统一的索引只把代码丢在GitHub仓库里有些企业内部skill放在私有GitLab上。这时候就需要手动源码安装方法并不复杂本质就是三步下载、放到正确目录、验证。先克隆仓库git clone https://github.com/yourname/your-skill-repo.git然后看仓库结构。如果仓库本身就是单个技能包直接把它复制到Agent的skills目录如果是一个集合仓库里面有多个子目录每个子目录都带独立的SKILL.md就从中挑出需要的单独复制。命令示例cp -r your-skill-repo ~/.claude/skills/my-skill我更喜欢用软链接而不是直接复制这样源码仓库更新后执行git pull就能同步不用再手动覆盖ln -s /path/to/your-skill-repo ~/.claude/skills/my-skill最后在Agent里新建会话输入类似/skills的命令查看已加载列表确认新技能出现。如果没有出现就重启一次Agent会话。2.3 让Skills对当前会话生效安装完成后不生效是新手踩得最多的坑。这里有个容易忽略的细节Agent加载skills的时机通常是在会话开始时也就是说你装完技能那一刻当前对话窗口里它其实还没被读进来。所以安装完第一件事是重启会话或新建会话让Agent重新扫描技能目录。另外不是所有skill都会被自动唤起。以Claude Code为例它的设计思路是按需加载Agent会根据当前用户请求去匹配各技能包SKILL.md头部的description匹配度足够高时才加载具体内容。这样做是为了节省上下文窗口但副作用是如果description写得太模糊Agent可能根本想不到调用。所以遇到技能不生效先别急着怪安装先看看自己的需求描述和技能描述是否对得上。想确认一个技能到底有没有被加载最直接的办法就是对话中明确带上技能包能处理的场景词。比如装了一个测试用例生成技能就明确说给这个函数生成边界测试用例而不是稀里糊涂地只丢一句帮我测测。3. 手写第一个自己的Skill3.1 SKILL.md的元信息怎么写安装别人做的技能包只是开始真正的价值在于把你自己团队那套沉淀了几年的经验变成一个Agent也能遵循的标准流程。我第一次手写skill时参考了社区里十几个热门仓库最后总结出的核心就是description决定能不能被唤起正文决定干得好不好。SKILL.md的头部字段我常用的就这几个--- name: react-component-generator description: 根据设计稿描述生成React组件。当用户提供组件需求、Figma链接或截图希望得到可运行的TSX和样式代码时使用。生成时优先复用项目中已有的设计令牌与组件库若不确定默认风格则先询问。 ---name要短description要长而具体至少说清三件事技能擅长的输入是什么能产出的结果是什么处理的优先级和边界是什么。很多人模仿开源仓库时只写一句用于React组件生成这远远不够因为Agent在匹配时只能看到这句话缺少触发信号它就不会加载你那套几千字的规范。有两点我踩过坑这里特别说一下。一是description不要写当用户需要帮助时使用这种万金油话术说了等于没说二是不要在description里依赖缩写和黑话Agent训练时见到的通用表达更容易命中。总之让AI一眼看出这个请求归我管是description的核心使命。3.2 把日常重复任务封装成技能讲一个具体案例。我团队前端每次做设计稿还原AI产出的代码风格都飘忽不定一会儿用px一会儿用rem一会儿组件颗粒度特别粗。后来我写了一个设计稿还原技能包把团队规范全部装进去效果立刻不一样。这个技能包的SKILL.md正文是这样组织的先说明流程顺序读取设计稿资源提取颜色、字号、间距、圆角等设计令牌对照团队已有组件库优先用现有组件拼装遇到缺失组件才手写结构样式变量统一用主题文件中的命名。写清输出格式要求组件要拆成TSX、样式、类型三段接口命名要遵循团队前缀规范图片资源要给出替换占位符。给出质量自检清单检查是否硬编码了设计稿里的临时色值、是否漏掉hover和loading态、边距是否和设计稿的8像素网格对齐。scripts/里我放了一个Node脚本用来解析设计稿导出的JSON token文件自动生成SCSS变量assets/里放了团队规范摘要和几个经典组件示例。这样AI执行时既有流程指令又有工具辅助输出质量稳定了很多。3.3 设计Skills的三种思路用了一段时间后我发现不同场景下的技能包设计思路其实可以归纳成三类。第一类是任务型技能关键词是拆解流程。比如代码评审、生成PR描述、整理Changelog这类任务有明确起点和终点技能的核心是把执行路径固定下来让AI每次都能按相同顺序、相同标准完成。代码评审技能里就会强制AI先看diff规模再按安全、性能、可读性逐层审查而不是想到哪看到哪。第二类是领域型技能关键词是沉淀知识。比如数学建模、专利文书写作、渗透测试安全审计这类技能的难点在于工作流复杂、领域知识多。以数学建模为例一个合格的技能包不是让AI帮你随便写个模型而是把选题分析、数据清洗、模型选型、敏感性分析、论文排版一整套流程串起来并在每个阶段给出检查清单。第三类是检查型技能关键词是质量门禁。比如测试用例生成、代码规范校验、图片还原对比这类技能通常和CI/CD结合在交付前最后卡一道关。测试用例技能会要求AI覆盖正常路径、异常路径、边界条件并根据函数复杂度决定用例数量避免每次产量忽高忽低。你在设计自己的技能包时先问自己一句这个问题属于哪一类是要把过程标准化还是要把知识显性化还是要把质量门槛焊死答案决定了你下一步的精力应该花在流程设计上还是知识整理上。4. 主流Agent的Skills兼容性速查4.1 Claude Code、Codex、OpenCode、Cursor的行为差异现在主流Agent基本都支持skills但各自的加载机制和目录位置并不完全一致不了解这些差异照搬别人的经验很容易踩坑。我整理了最近实测下来最关键的几个差异点可以对照查看Agent全局skills目录项目级目录加载方式Claude Code~/.claude/skills.claude/skills按需匹配优先级较低描述匹配才加载Codex~/.codex/skills.codex/skills结合CLI配置按需加载对长流程任务更友好OpenCode~/.config/opencode/skills.opencode/skills类似Claude Code强调渐进式加载Cursor通过专门的管理面板配置项目目录下统一管理更偏知识库导入行为更像检索增强我用下来最大的体感差异在是否需要显式调用。Claude Code和OpenCode倾向于让模型自己根据对话内容判断是否加载技能Codex在这基础上更看重用户命令的明确性如果你的请求太模糊它可能不会主动去翻技能包。Cursor则更接近一个整合型IDE里的知识库你甚至可以在配置里把技能包直接关联到特定项目。这对我们普通用户意味着同一套技能包换到不同Agent上不能假设效果完全一样。至少要留出半天时间做迁移测试尤其是技能包里带了自定义脚本的要重新确认脚本运行环境和输出解析方式。4.2 Skills如何调用MCP工具很多技能包的实际威力来自和MCP工具的联动这也是我最初最感兴趣的部分skills到底怎么调用MCP工具以我写的一个网页测试用例生成技能为例。它的SKILL.md里有一段明确说明执行测试用例分析前先调用浏览器自动化MCP用例生成阶段需要调用测试框架相关的MCP通过接口读取项目已有的测试配置。核心思路是在技能流程的特定步骤中写清楚这个环节应该通过MCP拿什么数据、调用什么工具、出错时怎么降级。写这个说明有个技巧不要把MCP当作隐藏能力而是把它当作文档里明确约定的依赖。大家在阅读你的SKILL.md时必须能看到这个任务需要哪些MCP服务的清晰列表。更好的做法是在SKILL.md的元信息区增加一个自定义字段列出所有依赖的MCP服务比如required_mcp: browser-tools, jest-runner这样Agent在执行前就能确认环境是否就绪。还要注意MCP服务本身是需要在Agent全局配置里先启用的。skills和MCP的关系更像是程序与运行环境环境没配好程序写得再漂亮也跑不起来。4.3 不同场景下的精华Skills清单热词里出现了大量具体场景的skills推荐这些我都实际筛过一轮分享一下我保留下来真正常用的清单。前端开发方向我离不开的是设计稿还原和前端代码评审两类技能包。好用的技能包会用设计令牌统一风格同时提供一份代码评审checklist从性能隐患到可访问性全覆盖。社区里Matt Pocock这类前端大佬维护的skills也值得关注尤其适合TypeScript项目。测试方向现在最热门的技能包是测试用例生成与回归类。这类技能会引导AI从需求描述中拆出业务规则再按正常、异常、边界三个维度生成用例矩阵。和普通让AI写用例相比技能包最大的进步是引入了覆盖率检查脚本用脚本反测用例有没有漏场景。数学建模和学术方向有不少集成了从数据清洗到论文写作全流程的技能包。数学建模比赛党好评的是模型选型引导能力AI会先问清楚数据量、变量类型、业务目标再推荐预测、评价或优化模型而不是一上来就甩一个线性回归。专利和论文方向的技能包则强在把权利要求拆解、背景技术撰写这些逻辑性很强的环节模板化。安全审计方向也有相当多技能包但我的态度很明确只在明确授权和测试环境里使用重点做风险排查、权限校验这类防御性工作。把技能包当成合法的加固工具而不是绕过控制的手段。更完整的冷门技能包列表可以经常去GitHub热榜和社区搜一搜现在每天都有新仓库冒出来核心筛选标准就两条有完整的SKILL.md而不是只有一句简介配套scripts和references而不是空壳结构。5. 常见问题与排障实录5.1 装上之后不生效这个问题几乎每个用skills的人都遇到过。我经历的排查顺序是这样的先看目录位置对不对Claude Code只认~/.claude/skills/下的目录Codex认~/.codex/skills/放错目录读到高效低下再看是否有同名技能冲突两个技能名字一样时Agent可能只加载了其中一个最后重启会话很多Agent在会话启动时才扫描技能目录。如果还不行就在对话里直接尝试触发它。比如你装了一个测试用例生成技能就明确说用测试用例生成技能针对这些业务规则输出用例矩阵。一旦技能被成功加载Agent通常会在思考过程里引用技能里的流程清单这时候你就能确认加载成功与否了。5.2 权限与路径坑用了一阵子后我发现真正容易出问题的不是SKILL.md本身而是技能包携带的脚本。不少脚本是Bash写的在Windows环境下会遇到路径分隔符和权限问题如果换了macOS又可能因为zsh和bash的语法差异报错。我的建议是尽量避免直接写系统级依赖统一用Node脚本是最稳的方案跨平台兼容性好而且Node在现代开发环境里几乎必装。如果一定要用Bash就在SKILL.md里写清楚脚本运行前提比如需要bash 4.0及以上macOS用户请先确认bash --version。另一个常见问题是软链接失效。有些同学图方便把整个仓库软链到skills目录仓库或分支切换后软链会指向不存在的路径Agent扫描时直接静默跳过。排查时如果发现技能彻底失踪先检查软链是否已经变成红色断链。5.3 自己维护Skills的深坑清单很多仓库停留在一次性创建永不更新的状态三个月后大家发现它不准了。原因不难猜MCP工具版本升级了、团队规范改了、知识库里的链接失效了。所以我会把技能包当作代码一样维护定期让一个独立Agent审一遍所有SKILL.md检查描述是否仍然准确、脚本是否还能跑、参考资料是否已经过时。另外一个技能包里不要贪多求全。我最早写过一个全能代码助手技能试图涵盖前端、后端、测试、部署所有场景结果因为description写得太大而无法精确匹配最终变成了一个偶尔被想起、多数时候没用的摆设。拆成多个小技能每个解决一个具体问题触发率和成功率反而大幅提升。最后建议每个技能包都配一个简单的README.md写清楚意图、适用场景和更新记录。这些东西AI自己不会补只有你写下来团队其他人才能接手维护而不是半年后看着一堆没有人能看懂的技能目录发呆。结尾踩过这么多坑之后我现在的态度是skills不是一个需要追的潮流而是一种能把隐性经验显性化的工作方法。真正让它产生价值的不是装了多少热门技能包而是你把团队和自己那套反复验证过的做事逻辑用结构化的方式沉淀下来。我个人觉得哪怕先从一个十几行SKILL.md的小技能开始也比攒几千行永不更新的万能提示词更有意义。如果你也想试建议从手边重复度最高的那个任务下手拆流程、补脚本、写描述跑通一次之后你大概率会回头把第二十个任务也装进技能包里。