最近AI编程圈里“skills”这个词的出镜率高得离谱。你打开Claude Code的更新日志能看到skills翻GitHub趋势也能看到skills连我平时用Codex处理项目时官方文档都在强调要把任务拆成skills。说实话我第一次听到这个词的时候是懵的以为又是一套全新的概念体系。但真正用它跑完一个项目之后我发现所谓skills说到底就是把“人怎么教AI干活”这件事标准化了。这篇东西不聊虚的只讲实操把什么是skills、怎么装、怎么写、以及我踩过的坑一次讲清楚。如果你也跟我一样平时依赖Claude Code、Codex或者OpenCode这类命令行Agent工作那么这个概念迟早会撞到你脸上。它不是什么高深算法而是一个朴素却极其实用的工程做法把一个常见任务从触发条件、执行步骤到注意事项写成一份Agent能读懂的说明书再配上必要的脚本和模板打包成独立目录。这样模型遇到对应任务时就可以直接按这份说明书行动而不是每次从零思考。下面我按从原理到实战的顺序把整套玩法拆开讲。1. Skills到底是什么从“技能包”到Agent的能力封装1.1 一个类比Skills是Agent的“操作手册”人们常说Agent编程像是带新员工这个比喻其实比想象的更贴切。新员工入职你不能要求他凭聪明才智直接上手所有业务通常会甩给他一份SOP里面写清楚什么情况怎么处理、流程分几步、遇到问题找谁。Skills本质上就是这么一份给AI读的SOP只不过它的载体是一个目录里面有一个叫做SKILL.md的说明文件以及可能附带的示例、脚本和模板。举个例子假设你经常需要AI帮你生成一套符合团队规范的React页面。没有Skills时你得每次在提示词里反复粘贴架构约定、组件书写方式、样式方案一次两次还行项目一多就极其痛苦。有Skills的话这些全套约定会被装进一个名叫“前端开发技能包”的目录里。AI一旦判定当前任务适合使用这个技能包就会自动读取SKILL.md按照里面写的步骤生成代码连你团队依赖的UI组件库版本号、命名规范都照顾到。这个设计之所以好是因为它让“知识”与“执行”分离了。“知识”沉淀在技能包中可以被复用、维护、迭代Agent只是在执行时把对应知识加载进上下文而已。而且这个隔离很有价值你可以像管理代码一样管理教AI做事的经验可以版本化可以做Code Review团队里谁都能看明白这个技能包要解决什么问题。1.2 与传统提示词、插件、MCP的区别很多人第一次接触Skills时会觉得这不就是升级版Prompt吗这么想有道理但不准确。Prompt是一段一次性施法吟唱你写进系统提示词里的内容会在整个会话里持续占用上下文窗口所有模型都要背着这堆内容不管用不用得上。Skills则是有选择地注入只有当模型判断任务匹配description时才会把SKILL.md的内容读进来。这就像工具箱里的分隔层平常不占桌面空间要用的时候才抽出来。至于Plugin和MCP又是另外的属性。Plugin更偏向IDE或编辑器层面的扩展它能够监听编辑器事件、操作UI界面、与代码编辑器深度集成MCP则是一个“工具协议”解决的是Agent调用外部系统的问题比如查询数据库、操作浏览器、读写文件。Skills解决的是“这个任务应该怎么做”的方法论三者解决的问题并不重叠实际项目里经常组合使用完全不是非要二选一的关系。我自己的理解是MCP回答“你能做什么”Skills回答“这件事该怎么做”。一个Agent可以同时挂载几十个MCP工具也可以同时装几十个SkillsMCP提供外部能力入口Skills负责工作流编排。如果有团队在纠结“我们到底是该做MCP Server还是该做Skills”不妨先想清楚你需要的是稳定的外部数据通路还是一套可复述的做事流程需要前者就做MCP需要后者就做Skills。1.3 为什么各家Agent都开始推Skills这个问题如果只看表面会觉得是厂商在造新概念。实际上Skills能流行有一个很扎实的技术原因上下文窗口再大也是有限的。本地模型上下文小云端模型上下文虽然能达到几十万Token但塞进来的内容越大推理延迟和成本就越高。如果每次对话都把几十个细分领域的规则写进系统提示词Agent还没干活就被规则压垮了。Skills按需加载让模型只处理与当前任务相关的内容这是性价比非常高的设计。第二点原因在于生态传播。技能包是纯文本加脚本的目录结构天然适合丢到GitHub上分享。一个人写好了“代码审查Skills”全世界都能直接npx安装这比复制粘贴一大段Prompt可靠太多因为有目录、有版本、有文档甚至可以直接写自动化测试。所谓skills harness其实就是支撑这套机制运行的基础设施负责扫描skills目录、解析说明文件、注入到模型上下文、管理脚本执行结果。另外从工程师的使用体验看Skills降低了Agent定制的门槛。以前想让AI固守某套工作流往往得写复杂的提示词工程或写代码做Agent编排现在只要往skills目录里丢一个文件夹再写清楚description就完成了定制。这也是为什么推广速度特别快。吴恩达在讲Agent Skills时反复强调的一句话我印象很深不要试图让大模型自己猜出复杂任务的全过程而是把任务拆成小块每一块配一个清晰的技能说明。2. 生态速览Claude Code、Codex、OpenCode与社区热门2.1 Claude Code与npx skills add使用体验在Claude Code里Skills的默认安装路径是全局目录~/.claude/skills/项目级目录则是.claude/skills/。无论哪种方式每个技能包都是一个独立文件夹最外层必须有SKILL.md其metadata要包含name和description。description尤为关键模型就是靠读它来决定要不要触发这个技能。官方提供了skills命令行工具最常用的安装姿势是这样npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y我拿这个命令实测过几次拆开来看npx是Node.js自带的包执行器skills add表示调用skills工具执行添加操作sandai-org/vidmuse-skills是GitHub仓库地址指明技能包来源--agent claude-code告诉工具当前要配置的Agent是Claude Code-g代表全局安装-y则是跳过所有确认提示适合在自动化脚本里使用。执行完成后技能会被下载到~/.claude/skills下。这个工具最令我满意的一点是它同时支持从仓库名安装和从本地路径安装。比如你想先试用某个项目内私有技能可以直接把仓库clone下来再用--local或者直接复制到项目skills目录不走网络发布流程。不过官方对目录校验比较严格如果SKILL.md不在仓库最外层或者缺少必要的name字段命令会直接报错这在社区仓库里很常见建议优先看README确认目录结构。2.2 Codex、OpenCode、Superpower Skills与Skills HarnessClaude Code并不是唯一拥抱Skills的Agent。ChatGPT Codex的Agent Skills功能与Claude的技能包思路一致也会从~/.codex/skills/之类的目录中读取技能OpenCode则把它作为一种高阶敏捷开发能力来宣传社区里已经有不少工程师把日常编码流程封装成了opencode skills。有趣的是这些实现虽然目录细节不同但核心规范出奇地一致一个说明书文件加上若干附属资源靠description触发按需加载。社区里知名度最高的Skill合集很多人第一个想到的是Superpower Skills。这是一套由slash command和skill集合组成的生态覆盖了从代码重构、调试到技术方案设计的常见场景。你不需要自己从头写每个技能安装后就能获得一批相当好用的“默认配置”尤其适合刚开始接触Skills、想直接上手体验的人。还有一些知名开发者会开源自己常用的skills仓库比如搜索mattpocook skills时能看到不少基于Claude Code的技能示例虽然这些个人维护的仓库质量参差不齐但胜在看得见摸得着很适合作为学习模板。这里我想专门提一下skills harness这个词。它经常和Skills一起出现翻译成“技能运行框架”可能更容易理解。一套harness要解决的事情包括扫描技能目录、解析SKILL.md元数据、判断何时注入技能内容、管理脚本执行权限、把执行结果回传给模型。你如果把Skills想象成手机Appharness就是操作系统。这也是为什么同一个技能包在Claude Code里能用不代表在别的Agent里也一定能用因为不同harness对metadata和脚本的支持程度不完全一样。2.3 社区里最常见的几类Skills我在GitHub上刷了段时间后发现社区流行的技能包其实高度集中在几类场景。第一类是前端开发和编码相关这应该是数量最多的比如自动生成React组件、按团队规范跑ESLint并修错、根据接口文档生成TypeScript类型定义。第二类是分析类技能例如“分析项目结构并生成文档结构图”通常融合了脚本和结构图描述语言AI输出Mermaid或Graphviz文本后渲染成图对应热搜里很多人搜的结构图skills。第三类是数学建模和科研写作类。数学建模skills在大学生群体里呼声很高本质上就是把线性规划、回归分析、模型调参、结果可视化这些常用流程固化下来模型一看到题目关键词就按部就班地跑建模流程。第四类是文档和专利写作类比如发明专利写作skills会提示模型按照“技术领域、背景技术、发明内容、实施例”的结构输出。每个技能包不一定复杂但都紧扣一个高频重复的使用场景。3. 十分钟上手安装并调用一个Skills包3.1 环境准备Node.js与Agent命令行工具安装Skills前先把基础环境确认好。目前绝大多数skills分发工具都是基于Node.js生态的所以机器上需要装好Node.js建议不低于18版本。装完可以打开终端执行node -v如果能正常打印版本号说明环境没问题如果提示找不到node那就去官网下载LTS版本装好再继续。接下来你至少需要有一款支持Skills的Agent命令行工具本文以Claude Code为例其他工具大同小异。第二点是目录权限。安装命令会访问GitHub拉取代码如果遇到超时可以多试几次或者先确认当前网络环境稳定。安装时如果用了-g参数可能涉及写入用户主目录下的.claude文件夹通常不需要sudo但如果之前修改过HOME路径需要确认权限没问题。很多新手在自定义目录结构时容易把SKILL.md放错层级导致工具报了“找不到SKILL.md”又说不清原因这个后面会专门讲。3.2 安装vidmuse-skills逐段拆解安装命令这里我拿热搜里的vidmuse-skills做一个完整演示。这个技能包主要是用来做视频相关的多模态分析与生成辅助具体能力你可以看它的README我们更关注安装过程。打开终端输入npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y我第一次跑完这条命令终端会打印类似“Installing skill from sandai-org/vidmuse-skills”的日志几秒钟后提示安装完成。这时检查一下全局目录里是否多了对应的文件夹ls ~/.claude/skills如果正常你会看到一个以vidmuse-skills命名的目录里面至少有SKILL.md这个文件。这个文件就是整个技能包的核心AI后续主要靠它理解怎么使用该技能。你可以用cat直接打开看过内容理解一下技能包到底写了什么。安装不限于这个包任何GitHub上的技能包都可以换成owner/repo的格式安装。很多仓库还支持指定tag或分支比如owner/repo#main这样你可以固定版本避免上游更新后行为不稳。用-y跳过确认虽然方便但在不确定脚本来源时我建议第一次去掉-y先让它打印出具体要下载什么、安装到哪里心里有个底再确认。3.3 让Agent真正把Skill用起来的三个技巧装好技能包只是第一步真正让模型调用它是另一回事。第一个技巧是任务描述要尽量具体。比如你刚装好一个“项目结构分析”类技能如果只说“帮我看下项目”模型很可能不触发技能而是给你一段笼统的回复。换成“请使用项目结构分析技能扫描src目录生成模块依赖关系图”命中率会大幅提高。第二个技巧是可以直接点名技能。在Claude Code之类支持自然语言指令的Agent里你可以明确说出技能名比如“请使用vidmuse-skills处理这个视频任务”。通过显式引用能绕过模型对description的模糊判断属于最稳的方式。第三个技巧是关注Skill的执行日志。很多Agent在加载技能时会在日志里打印“using skill xxx”类似信息如果你发现预期触发的技能没出现先从日志查起而不是怀疑技能写错了。4. 从零开发自己的Skills目录、说明与脚本4.1 最小目录结构SKILL.md是入场券开发自己的Skills并不复杂核心就是搭一个标准目录。最小的技能包只要两样东西一个叫SKILL.md的说明书文件以及这个说明书所在的目录。在Claude Code的规范里目录名通常可以自定义但SKILL.md文件名必须严格一致否则harness不会识别。可以简单理解成目录名是给人看的SKILL.md才是给机器找的。如果技能需要在本地执行脚本或引用模板那就把额外资源放进子目录。比如下面这个最小结构my-skill/ ├── SKILL.md ├── scripts/ │ └── analyze.sh └── templates/ └── report.mdscripts和templates目录不是强制的但它们能让技能包从“纯文字建议”变成“可以真正干活”的工具。比如技能要读取项目里的文件并汇总就可以写一个Python或Shell脚本放在scripts下SKILL.md里写明运行方式Agent会调用脚本并把输出带回上下文。4.2 写一份能触发模型行为的SKILL.mdSKILL.md最前面必须有一段YAML frontmatter至少包含name和description。name是该技能的唯一IDdescription是模型判断是否触发的关键。很多人第一次写都会把description写得太宽比如“用于处理所有项目相关问题”这会导致模型在完全不相关的任务上也尝试调用反倒让技能形同虚设。一个相对靠谱的SKILL.md大概长这样--- name: repo-structure-analyzer description: 当用户需要分析Git仓库目录结构、统计模块依赖或生成结构图时使用。输入可以是任意本地项目路径。 --- 输入项目路径。 步骤 1. 用find命令列出目录树忽略node_modules等目录。 2. 识别核心模块标记模块间依赖。 3. 用mermaid格式输出结构图。 约束 - 不修改任何源码文件。 - 如果项目大于100MB只分析第一层目录。对比一下就能看出差异它把触发条件、输入格式、步骤和边界约束都写清楚了。AI的行为受step-by-step影响非常大越是清晰的操作步骤它的输出越稳定。另外别忘了在文档里写明失败处理比如“如果找不到package.json提示用户这不是Node项目”。4.3 给Skills装上“手脚”辅助脚本怎么设计一味让SKILL.md写“你该怎么做”还不够很多任务需要脚本去真正执行因为模型的文本能力再强也算不了大文件、读不了二进制。设计辅助脚本时我建议遵循三个原则。第一是短小精悍一个脚本最好只做一件事然后输出结构化结果第二是输出要能被模型读懂尽量用文本格式如果涉及多个字段就给出行号或JSON让AI容易引用第三是错误信息要友好在脚本里面捕获异常不要默认模型能读懂乱码堆栈。举个简单例子如果你的技能是“扫描项目并提取TODO清单”可以在scripts下放一个Python脚本遍历源文件匹配TODO字样把文件路径和注释原文输出成表格文本。SKILL.md中只需写明“运行scripts/scan_todo.py”模型就会拿着脚本执行结果再结合上下文给你一份整理过的清单。脚本的安全问题也要注意harness通常不会限制脚本权限你自己写技能时务必检查脚本不会删除用户文件或执行未知命令。4.4 本地调试与发布源码安装与npx分发开发完技能包后先在本地验证。最简单的方法是把my-skill目录直接复制到当前项目的.claude/skills/目录下然后打开Claude Code自然描述一个任务观察技能是否被触发。如果不触发优先检查description里的关键词是否和任务描述匹配如果触发了但行为不对多调试SKILL.md里的步骤顺序和约束条件。本地跑通了再放到全局目录里供所有项目使用。发布到社区同样不难。把目录推到GitHub仓库即可其他人就能通过npx skills add owner/repo安装。如果你希望别人能按tag固定版本可以在仓库打tag仓库名后面加#tag引用。所谓“源码安装”其实就是在npx安装失败时直接把仓库clone到skills目录git clone https://github.com/yourname/your-skill.git ~/.claude/skills/your-skill注意clone后的目录名可以不和仓库名一致但目录里必须直接包含SKILL.md不能多套一层文件夹这是新手最容易踩的坑。5. 场景化拓展Skills不止能写代码5.1 前端开发与编码效率类Skills虽然Skills最先火起来是沾了编码Agent的光但它的能力范围早就超出了纯编码。前端开发领域尤其明显团队可以把设计规范、组件库文档、状态管理约定、提交信息规范全部装进一个前端开发skills包里AI生成的代码风格会非常统一。我见过有团队把自己的CI脚本和代码审查流程也做成技能Agent每次提交前自动先跑一遍“审查技能”节省了人工Review不少时间。除此之外编码相关的结构图技能也很推荐。很多流程性任务比如梳理调用链、画系统架构图、生成数据库ER图以往需要人手工整理现在可以做成一个技能让AI读取代码结构后直接输出mermaid或graphviz格式的图。这样既能沉淀到文档里又不会因为代码迭代而过期维护成本比人工画图低很多。5.2 数学建模、结构图与文档写作类Skills数学建模Skills成为热搜词是有原因的。数模比赛时间紧任务重真正耗时的反而是一遍遍重复的标准化流程读题、假设梳理、模型选择、参数估计、灵敏性分析、论文排版。一个结构良好的数模Skills包可以把这些步骤按比赛节奏组织起来模型在拿到题目后自动按流程推进极大减少“每到新题都要从头引导”的时间。当然它代替不了人的建模思考但作为流程助手非常有效。文档写作领域也类似尤其是发明专利写作这类格式要求严格的内容。专利写作Skills可以内置权利要求书的结构模板并提示模型按“技术问题-技术方案-有益效果”的逻辑组织内容输出初稿后再由人来润色。对于公众号运营、方案策划这类场景以及各平台热词常提到的“微信公众号文章相关的技能包”核心思路也是一样的把爆款结构、标题风格、排版规范沉淀成技能让AI在创作时自动遵循。5.3 安全测试类Skills的合规边界安全测试类Skills在社区里同样有存在感但我必须在这里说清楚任何安全测试相关内容都只允许在获得明确授权的环境中使用。一个合规的渗透测试Skills包正确的姿势应该是集成测试清单、报告模板、漏洞分级规范以及符合行业标准的流程指引而不是提供越权绕过或攻击载荷生成。我见过有些团队把安全测试流程做成技能每次被授权测试时自动生成测试范围和发现报告这就很好用。我希望看到这篇内容的人都能记得Skills本身是工具它放大的是使用者的专业判断。放进技能包的代码与指令都应该经过合规审核。尤其是当你打算把安全类Skills发布到GitHub时更要注意不要包含可能被滥用的内容遵守平台法律法规是底线。6. 常见问题与避坑指南6.1 npx找不到模块或权限不足怎么办最基础的错误就是npx: command not found说明Node.js没有安装或没有进PATH去装一个LTS版本然后重开终端即可。如果你确认npx存在但执行npx skills add时报权限错误先确认你是不是在用户目录下有写入权限正常不需要sudo。极少数情况下网络不稳定会下载失败多试一次或者调整网络环境后重试。还有些人遇到“Could not find SKILL.md”报错这通常不是网络问题而是仓库结构不符合规范。你可以先把仓库clone到本地看一眼如果SKILL.md在下一层目录要么改用owner/repo的安装方式让工具自动识别要么手动把整个子目录复制到skills目录。这类问题排查起来都不难关键是养成看README和目录结构的习惯。6.2 Skills装上后模型不调用怎么办模型不调用Skills是最高频的困惑。第一步先检查路径确认你装的是全局还是项目级当前项目是否有.claude/skills覆盖了全局目录。第二步检查description和任务描述是否语义匹配。模型基本是靠description做“语义触发”如果你的技能包说“用于视频生成”而你问“帮我把这个视频转成gif”即便能力相关也可能因为措辞不同而触发失败。第三步就是手动点名直接说“使用xx技能处理”可以立竿见影。从设计来说我建议每个技能的description里都加上触发关键词和适用输入示例。不要寄希望于模型能从你的模糊指令里理解到“这个场景应该用这个技能”最可靠的触发路径还得靠清晰的任务描述加上语义匹配的技能说明。6.3 触发不精准全是description的锅很多技能过度触发问题也出在description。比如你写“处理所有数据分析相关工作”模型可能会把它当成万能技能在画饼状图、算均值、做预测时都去加载结果不符合预期。更优的写法是“仅在用户提供CSV文件并请求生成描述性统计报告时使用”这样既给了明确边界又给了触发条件。另外SKILL.md里的步骤里最好别写“根据情况而定”这类开放性描述因为大模型拿到开放性指令后每次执行结果都会不一样。宁可多写几个分支“如果……则……否则……”让它像程序一样执行。我在写自己的技能包时会尽量把“输入”和“期望输出”写成一个可验证的形式甚至在SKILL.md里放一个最简单的输入输出样例模型照着样例输出就不会跑偏。6.4 Skills与MCP、Plugin如何选型这是一个很容易纠结的问题。我的判断标准很简单如果任务是“如何做”选Skills如果任务是“做什么数据操作”选MCP如果任务要操纵编辑器UI和事件选Plugin。它们不是互相排斥而是在不同层级发挥价值。实际项目里最舒服的组合是用MCP接入代码库、数据库和浏览器等外部系统用Skills提前定义好工作流再让Agent按技能步骤去调用MCP工具。还有一个现实建议开始不要贪多。一次往环境里塞几十个技能不仅模型会因为description冲突而误触发你排查起来也很累。先用两三个高频技能跑通流程观察哪些写得好哪些经常误导再逐步删改和扩充。技能的维护是一个持续过程不是做完一个包就一劳永逸。我个人在这段时间的实验里最大的体感是真正好用的Skills通常都不是追求大而全而是把一件小事描述得极端清楚。我后期写技能包时宁可让description只有一两句话也要把边界条件和失败处理写到位。如果你也想从零开始做第一个skills建议从你每天最常让AI重复做的那个任务入手比如“生成项目周报”或者“分析仓库结构”把它拆成说明书可能比你先研究三天框架更有效。这个思路才是skills这个概念的真正价值所在。