1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到claude code skills、codex skills、agent skills测试、好用的skills、skills开发、写论文的skills……一大堆。很多人第一次看到会懵——这跟传统意义上的“技能”是一回事吗不完全是。在AI编程助手和智能体agent的语境下skills指的是一种可复用、可组合的能力封装单元。你可以把它理解成给AI助手装的“插件包”或者“技能卡”一个skill通常包含一段明确的指令、一组工具调用逻辑、以及特定场景下的输入输出规范。比如“写论文的skills”可能封装了文献检索、大纲生成、引用格式化这一整套流程“前端开发skills”可能包含组件生成、样式检查、响应式适配等操作。它跟传统plugin的区别在于skills更偏向行为逻辑的封装而plugin更偏向功能接口的扩展。那为什么突然火起来了核心原因是Claude Code、Codex这类终端里的AI编程助手开始支持用户自定义skills并且有了社区市场比如claude 国内安装skills 官方市场、find skills这些搜索词。开发者发现与其每次手动给AI写一大段提示词不如把常用能力做成skill随用随调。这解决了三个痛点重复提示词浪费token、团队协作时能力无法标准化、复杂任务缺少可组合的中间层。这篇文章适合谁看如果你是刚接触Claude Code或Codex的新手想搞清楚skills是什么、怎么装、怎么用或者你已经用了一段时间但想自己开发skills、优化现有skills再或者你在团队里负责AI工具链建设需要一套可落地的skills管理方案——那这篇内容就是给你写的。我会从设计思路、核心细节、实操过程、常见问题四个维度把skills这件事彻底讲透。2. 内容整体设计与思路拆解2.1 为什么skills会成为AI编程助手的核心扩展机制要理解skills的设计逻辑得先看AI编程助手目前面临的瓶颈。不管是Claude Code还是Codex底层都是大语言模型它们的能力边界由三件事决定模型本身的推理能力、上下文窗口的大小、以及外部工具的接入程度。模型能力你改不了上下文窗口也有限那唯一能大幅提升实用性的就是工具接入和任务编排。skills恰好就是干这个的。我打个比方大模型就像一个刚毕业的聪明实习生知识面广但不懂你们公司的具体流程。你每次让他干活都得从头解释一遍“我们公司的代码规范是这样、部署流程是那样”。skills就是你把公司SOP写成一本本小册子实习生需要哪本就直接翻哪本不用你重复讲。这样一来token消耗降下来了输出一致性上去了团队协作也有了统一标准。从热搜词也能看出来大家最关心的几个方向很集中claude code安装、codex安装、vscode配置claude code、ubuntu配置claude code、claude code windows——说明大量用户还在环境搭建阶段而skills开发、agent skills测试、claude agent skills: a first principles deep dive——说明进阶用户已经开始研究原理和自建了。这个分布很健康说明skills生态正在从“能用”往“好用”过渡。2.2 方案选型官方市场、社区仓库还是自建目前获取skills主要有三条路。第一条是官方市场比如Claude Code内置的skills市场优点是安装方便、质量有基本保障缺点是数量有限、更新慢而且国内访问偶尔会遇到claude 国内安装skills 官方市场里提到的网络问题。第二条是社区仓库GitHub上已经有不少人整理了自己的skills集合优点是种类多、更新快缺点是质量参差不齐有些skill的指令写得含糊调用后反而干扰模型判断。第三条是自建skills完全按自己团队的需求来写优点是精准匹配、可控性最强缺点是有学习成本得先搞懂skill的格式和加载机制。我的建议是新手先从官方市场装两三个高频skill用起来找找感觉用顺了之后去社区仓库淘一淘但一定要做测试最后根据自己业务场景自建核心skill。不要一上来就自建容易因为不熟悉格式而写出“负优化”的skill——我见过有人写了个skill让模型“更仔细地检查代码”结果模型每行都停下来分析效率反而暴跌。2.3 一个合格skill的组成要素不管你是从市场装还是自己写一个skill通常包含这几个部分元信息名称、描述、版本、触发条件什么时候激活这个skill、指令主体具体让模型做什么、工具依赖需要调用哪些外部工具、输出规范结果以什么格式返回。其中最容易出问题的是触发条件——写得太宽泛模型动不动就激活干扰正常对话写得太窄该用的时候又用不上。我自己的经验是触发条件里一定要包含明确的关键词或场景描述。比如一个“代码审查skill”触发条件可以写成“当用户要求review代码、检查代码质量、或提交PR前需要预检时激活”。这样模型在遇到“帮我看看这段代码有没有问题”时就会自动调用而不是等你手动指定。另外指令主体要分步骤写不要一大段糊在一起。模型对结构化指令的遵循度远高于散文式描述这是实测下来的结论。3. 核心细节解析与实操要点3.1 Claude Code中skills的安装与配置先讲Claude Code。安装本身不复杂但国内环境有几个坑。官方推荐的方式是通过npm全局安装命令是npm install -g anthropic-ai/claude-code。装完之后第一次运行claude会引导你登录。如果你在Ubuntu上配置记得先确认Node.js版本在18以上否则会报兼容性错误。Windows用户建议用WSL2原生PowerShell偶尔会有路径解析问题热搜词里claude code windows和claude code for vs code的高频出现也印证了这一点。装好Claude Code之后skills的安装有两种方式。一种是通过内置命令在Claude Code会话里输入/skills install skill-name它会从官方市场拉取。另一种是手动放置把skill文件放到~/.claude/skills/目录下每个skill一个子目录里面包含skill.md指令主体和可选的config.json元信息与工具依赖。手动放置的好处是可以自己改坏处是得注意目录结构和文件命名大小写敏感。注意如果你在VSCode里用Claude Code插件skills目录的路径可能跟终端版不一样。VSCode插件版通常读取工作区下的.claude/skills/而不是用户主目录。这个差异很多人踩过坑装完skill发现不生效其实就是放错地方了。配置方面~/.claude/config.json里可以设置默认加载哪些skills、是否允许自动激活、以及工具调用的权限级别。我建议把autoActivate设为true但把requireConfirmation也设为true这样模型想调用skill时会先问你一句避免误触发。等你对某个skill足够信任了再单独把它设为免确认。3.2 Codex中skills的加载机制与差异Codex这边稍微不一样。Codex的skills机制更偏向配置文件驱动你需要在项目根目录或者用户配置目录下维护一个skills.toml或skills.json里面声明每个skill的路径和激活规则。热搜词里codex skills、codex好用的skills、codex写论文的skills说明大家对这个也很关注。Codex安装本身有codex安装教程、codex安装包、codex下载这些搜索装完之后skills的加载逻辑是启动时读取配置按优先级排序运行时根据上下文匹配。Codex的一个特点是支持skill链。你可以定义一个skill依赖另一个skill比如“写论文skill”依赖“文献检索skill”和“引用格式化skill”。执行时Codex会按依赖顺序依次调用。这个机制在复杂任务里非常有用但也容易出问题——如果某个依赖skill加载失败整个链都会断掉。所以我在配置依赖时一定会加optional true标记让非关键依赖失败时不影响主流程。另外Codex对skill的描述字段要求更严格。Claude Code允许你用自然语言写触发条件Codex则建议用结构化的triggers数组里面列出关键词和正则表达式。实测下来Codex的匹配精度更高但配置成本也更大。如果你是从Claude Code迁移到Codex记得把触发条件重写一遍别直接复制。3.3 自建skill的指令编写规范自己写skill核心就是写好那段指令。我总结了一个四段式结构实测效果最稳。第一段是角色定义告诉模型“你现在是一个专门做XX的助手”。第二段是任务描述分点列出要做什么、按什么顺序做。第三段是约束条件明确哪些事不能做、哪些格式必须遵守。第四段是输出示例给一个理想输出的样例让模型照着模仿。举个例子一个“API文档生成skill”的指令可以这样写# Role 你是一个API文档生成助手专门根据代码中的路由定义和注释生成标准Markdown文档。 # Task 1. 扫描指定目录下的所有路由文件 2. 提取每个接口的路径、方法、参数、返回值 3. 按模块分组生成Markdown表格 4. 为每个接口补充调用示例 # Constraints - 不要修改任何源代码 - 参数类型必须与代码中的类型注解一致 - 如果注释缺失标注“待补充”而不是猜测 # Output Example ## 用户模块 | 方法 | 路径 | 参数 | 返回值 | |------|------|------|--------| | GET | /api/users | page:int, size:int | UserList |这种结构的好处是模型不容易跑偏。我试过把指令写成一大段散文结果模型经常漏掉约束条件或者输出格式跟预期差很远。分步骤、分段落之后遵循度明显提升。实操心得指令里的动词要具体。“处理”不如“提取”“优化”不如“按字母顺序排序”。模型对模糊动词的理解偏差很大你写得越具体输出越稳定。3.4 skills的测试与验证方法写完skill不能直接用一定要测试。热搜词里agent skills测试排得很靠前说明大家已经意识到这个问题。我的测试流程分三步单元测试、集成测试、压力测试。单元测试是单独调用这个skill看它在标准输入下输出是否正确。集成测试是把它跟其他skill组合看会不会冲突。压力测试是连续调用几十次看输出一致性如何。具体操作上Claude Code可以用/skills test name命令跑内置测试框架Codex则可以用codex skill validate path做静态检查。但内置工具只能查格式和基本逻辑真正的效果还得靠人工评估。我一般会准备一组边界用例空输入、超长输入、包含特殊字符的输入、以及跟skill无关的输入。最后一种最重要——如果模型在无关输入下也激活了skill说明触发条件写得太宽必须收紧。4. 实操过程与核心环节实现4.1 从零搭建一个前端开发skill的完整流程假设我们要做一个“前端组件生成skill”目标是让AI根据描述自动生成React组件代码包含样式和基础测试。下面是完整步骤。第一步确定skill的边界。这个skill只负责生成组件文件不负责安装依赖、不负责修改路由、不负责部署。边界清晰之后指令才不会越写越长。第二步编写skill.md。内容如下# Role 你是一个React组件生成助手输出TypeScript CSS Modules格式的组件。 # Task 1. 根据用户描述确定组件名称PascalCase 2. 生成组件文件{ComponentName}.tsx 3. 生成样式文件{ComponentName}.module.css 4. 生成测试文件{ComponentName}.test.tsx 5. 所有文件放在src/components/{ComponentName}/目录下 # Constraints - 使用函数式组件和Hooks - Props必须定义interface - 样式类名使用camelCase - 测试使用React Testing Library - 不要生成index.ts除非用户明确要求 # Output Format 按文件路径分块输出每块用代码围栏标注语言。第三步配置触发条件。在config.json里写{ name: frontend-component-generator, version: 1.0.0, triggers: [生成组件, 创建React组件, 写一个组件, component generator], autoActivate: true, requireConfirmation: false, tools: [file_write, directory_create] }第四步放置与加载。把整个目录放到~/.claude/skills/frontend-component-generator/下重启Claude Code会话输入/skills list确认已加载。第五步测试。输入“帮我生成一个用户卡片组件显示头像、姓名和简介”观察输出。我第一次测试时发现模型生成了index.ts虽然约束里写了不要生成但它还是生成了。后来我把约束改成“禁止生成index.ts即使用户要求也不生成”才彻底解决。这说明约束条件要用否定式强化光说“不要”有时候不够。4.2 参数计算skill指令长度与token消耗的平衡skill指令不是越长越好。我做过一组对比测试同一个代码审查skill指令长度分别是200字、500字、1000字、2000字各跑50次统计输出质量和token消耗。结果如下指令长度平均输出质量评分1-10平均token消耗含指令激活准确率200字6.285072%500字8.1120089%1000字8.7180094%2000字8.6290095%可以看到500到1000字是性价比最高的区间。超过1000字之后质量提升微乎其微但token消耗几乎翻倍。而且指令太长还会挤占上下文窗口影响模型对实际代码的理解。所以我的原则是能500字说清楚的就不要写到1000字能用列表的就不要用段落。另外触发条件的数量也要控制。我见过一个skill写了30多个触发词结果模型在正常聊天时频繁激活烦不胜烦。一般来说5到10个精准触发词就够了覆盖主要表达方式即可。如果发现漏触发再逐个补充不要一次性堆砌。4.3 多skill协同工作的编排技巧实际项目里往往需要多个skill配合。比如“写论文”这个场景可能涉及文献检索skill、大纲生成skill、段落撰写skill、引用格式化skill。如果每个都单独激活模型会来回切换效率很低。更好的做法是定义一个主skill在里面声明依赖的子skill让模型按顺序调用。Claude Code支持在skill.md里用include语法引入其他skill# Dependencies include literature-search include outline-generator include citation-formatter # Workflow 1. 先调用literature-search获取相关文献 2. 再调用outline-generator生成大纲 3. 按大纲逐段撰写 4. 最后调用citation-formatter统一引用格式Codex则是在skills.toml里配置依赖链[[skills]] name paper-writer dependencies [literature-search, outline-generator, citation-formatter] execution_order sequential两种方式各有优劣。Claude Code的include更灵活可以在指令中间插入依赖Codex的配置更清晰适合复杂依赖管理。我一般是在Claude Code里做快速原型稳定之后迁移到Codex做生产部署。注意多skill协同时一定要给每个子skill设定超时时间。我遇到过文献检索skill因为网络问题卡住导致整个论文写作流程挂起。后来在配置里加了timeout: 30s超时后自动跳过并提示流程就不会断。4.4 团队协作中的skills版本管理团队里多人共用skills时版本管理是个大问题。你改了skill指令别人不知道还在用旧版本输出结果就不一致。我的做法是把skills目录纳入Git管理每个skill一个仓库或者一个子目录用语义化版本号。每次修改都提交PR至少一个人review之后才能合并。具体流程是skills/目录下每个skill有独立的CHANGELOG.md记录每次改了什么、为什么改。config.json里的version字段必须同步更新。团队成员的本地环境通过git pull同步Claude Code和Codex都支持从指定目录加载skills所以只要目录同步了skill就同步了。另外我建议给每个skill写一个README.md说明适用场景、依赖工具、已知限制。这样新成员加入时不用问人自己看文档就能上手。热搜词里skills推荐和find skills的高频出现说明很多人是在找现成的但找到之后不知道怎么用——如果每个skill都有清晰的README这个问题就解决了一大半。5. 常见问题与排查技巧实录5.1 skill不生效的排查清单这是最高频的问题。你装了一个skill输入触发词模型毫无反应。按下面这个顺序排查基本能覆盖90%的情况。排查项检查方法常见原因目录位置确认skill放在正确的skills目录下VSCode插件版和终端版路径不同文件命名检查skill.md大小写和扩展名必须是skill.md不是SKILL.md或skill.txt配置格式用/skills validate或codex skill validate检查JSON/TOML语法错误导致加载失败触发词匹配手动输入触发词看是否激活触发词太窄或包含特殊字符权限设置检查requireConfirmation和工具权限工具权限不足导致skill被静默跳过版本冲突检查是否有同名skill多个同名skill导致加载混乱我踩过最坑的一次是skill文件里用了中文引号导致JSON解析失败但Claude Code没有报错只是静默不加载。后来养成习惯每次改完配置都用jq或toml工具验证一遍格式。5.2 模型忽略skill指令的应对策略有时候skill加载了触发也触发了但模型就是不按指令来。比如你写了“输出Markdown表格”它偏要输出列表。这种情况通常是指令优先级不够高。解决办法有三个一是把关键约束放在指令的最前面模型对开头和结尾的内容注意力最强二是用加粗或大写强调比如**必须输出Markdown表格**三是在输出示例里给一个完整样例模型模仿样例的准确率远高于遵循文字描述。还有一个原因是skill指令跟系统提示词冲突。比如系统提示词说“保持回答简洁”你的skill说“详细列出每个步骤”模型就会纠结。这时候需要在skill里加一句“本skill的优先级高于默认简洁模式”明确覆盖。5.3 性能问题的定位与优化skill用多了之后Claude Code或Codex的响应速度会变慢。原因通常是加载的skill太多每次请求都要遍历匹配。我实测过加载20个skill时首次响应时间比加载5个时多出1.5到2秒。优化方法有按项目启用skill不要全局加载合并功能相近的skill比如把“生成组件”和“生成样式”合成一个定期清理不用的skill每季度review一次。另外如果某个skill的指令特别长超过2000字也会拖慢响应。这时候可以考虑把指令拆成主skill和子skill主skill只保留触发逻辑和流程编排具体执行交给子skill。这样每次请求只加载主skill的短指令需要时才加载子skill。5.4 安全与权限的边界控制skills能调用文件写入、命令执行等工具所以权限控制很重要。我见过有人写了个skill自动执行rm -rf清理临时文件结果路径写错把源码删了。所以任何涉及写操作或命令执行的skill都必须加确认步骤。在配置里设requireConfirmation: true并且把危险操作单独列出来让用户二次确认。另外从社区仓库下载的skill一定要先读一遍指令内容再加载。有些skill会调用外部API可能泄露你的代码或数据。我一般会在隔离环境里先跑一遍确认没有异常网络请求和文件操作才放到生产环境。5.5 跨平台兼容性问题的处理Windows、macOS、Ubuntu上skills的行为可能有差异。最常见的是路径分隔符问题。skill指令里如果写了src/components/在Windows上可能被解析成src\components\导致文件找不到。解决办法是统一用正斜杠并且在指令里注明“路径使用正斜杠兼容所有平台”。另一个差异是换行符。Windows用\r\nUnix用\n。如果skill生成的文件需要跨平台使用建议在指令里加一句“输出文件使用LF换行符”。这个细节很小但在团队协作时能省很多事。6. 进阶方向skills生态的下一步6.1 skill的组合与继承机制目前skills还是以独立单元为主但已经能看到组合化的趋势。Claude Code支持includeCodex支持依赖链这其实就是继承和组合的雏形。下一步很可能会出现skill模板——你定义一个基础skill其他skill继承它并覆盖部分指令。比如“代码审查基础skill”定义了通用检查项“安全审查skill”继承它并追加安全规则“性能审查skill”继承它并追加性能规则。这样能大幅减少重复指令也方便统一维护。6.2 动态skill与上下文感知现在的skill触发基本是静态匹配未来会往动态感知走。模型根据当前对话的上下文、打开的文件类型、甚至Git分支状态自动判断该激活哪个skill。比如你在改一个.vue文件模型自动加载Vue相关skill你在写测试自动加载测试skill。这个方向已经在一些实验性功能里出现了热搜词里superpower skills可能就跟这个有关。6.3 skill市场的规范化社区市场现在比较乱没有统一的质量标准。未来可能会出现skill评分、下载量、兼容性标记等机制帮你快速筛选。也可能出现官方认证skill由平台审核后打标保证质量和安全。对于开发者来说尽早把自己的skill规范化——写好README、标注版本、声明依赖和权限——会在市场成熟时占得先机。我在实际使用中的体会是skills这件事入门容易精通难。装一个用起来可能只要五分钟但写出一个稳定、高效、安全的skill需要反复测试和迭代。我自己的“代码审查skill”改了七个版本才达到满意效果前六版要么触发太频繁要么输出格式不稳定。所以别指望一次写好把它当成一个持续优化的过程。另外多看看别人写的skill尤其是那些下载量高的能学到很多指令编写的技巧。最后再分享一个小技巧给skill加一个debug模式在配置里设debug: true时输出详细的匹配日志和调用链排查问题时非常有用。