1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到claude code、codex、agents、plugin、skills推荐、codex skills、claude agent skills……这些词几乎绑在一起出现。很多人第一次看到“skills”会以为是某种新编程语言或者框架其实不是。它更像是一套给AI编程助手用的“技能包”机制——把常见的开发任务、代码规范、项目结构、调试流程封装成可复用、可组合的模块让AI助手在特定场景下知道“该怎么做、按什么顺序做、注意什么”。我最早接触这个概念是在折腾claude code和codex的时候。当时想让AI帮我改一个前端项目的组件结果它给出的代码风格跟项目里现有的完全不一致变量命名、目录结构、甚至import顺序都乱套。后来才发现问题不在于模型能力不行而在于我没有给它提供“项目上下文”和“操作规范”。而skills就是干这个的把隐性的团队经验显性化把重复的指令模板化把AI的行为约束在可控范围内。这篇文章适合谁看如果你是刚接触claude code或codex的新手想搞清楚skills到底怎么装、怎么用、怎么自己写或者你已经用过一段时间但总觉得AI输出不稳定、每次都要重复交代背景再或者你是团队里的技术负责人想统一团队的AI辅助开发流程——那这篇内容应该能帮你省下不少试错时间。我会从设计思路、核心细节、实操流程、常见问题四个层面展开尽量把踩过的坑和验证过的方案都摊开讲。2. 内容整体设计与思路拆解2.1 为什么需要skills从“每次重新交代”到“一次封装反复用”在没有skills之前我用claude code的典型流程是这样的打开终端进入项目目录然后敲一大段提示词——“这是一个React项目用TypeScript组件放在src/components下样式用CSS Modules状态管理用Zustand命名用驼峰不要用default export……”每次新开一个会话这段话都要重新说一遍。更麻烦的是团队里每个人说的还不一样导致AI产出的代码风格飘忽不定。skills的核心思路就是把这段“交代背景”的过程产品化。你可以把它理解成给AI助手准备的一份“入职手册”项目用什么技术栈、代码放哪里、命名规范是什么、测试怎么写、提交信息格式怎么定。这份手册以结构化文件的形式存在AI在需要的时候会自动读取并遵循。这样一来你不需要每次重复AI也不会“失忆”。从热搜词里也能看出这个趋势claude agent skills: a first principles deep dive、codex skills、skills开发、idea使用skills——大家关注的焦点已经从“怎么让AI写代码”转移到“怎么让AI按我的规矩写代码”。这背后其实是AI辅助开发从“玩具阶段”进入“工程阶段”的必然结果。2.2 skills、plugin、agents三者的关系别搞混了很多人会把skills、plugin、agents混为一谈我一开始也绕了很久。用个生活化的类比agents是“员工”skills是“岗位操作手册”plugin是“工具箱”。agents负责决策和调度决定“现在该做什么”。比如一个代码审查agent它的职责是检查代码质量。skills定义“具体怎么做”。比如“审查React组件时先检查hooks依赖数组再检查props类型最后看是否有不必要的re-render”。plugin提供“用什么做”。比如调用ESLint、Prettier、TypeScript编译器这些外部工具。在实际配置中这三者经常一起出现。比如你在claude code里装了一个前端开发相关的skill它可能会依赖某个plugin来执行lint命令同时被某个agent在代码审查环节调用。热搜词里的dsh plugin --profile web add dshmarket、eclipse mybatisx plugin、idea设置plugin中插件仓库地址这些都是在不同IDE或工具链里管理plugin的典型操作。理解这个分层很重要因为后面配置的时候你会知道该改的是skill文件还是该装plugin还是该调整agent的调度逻辑。搞混了就会像热搜里那个cc switch local proxy failed while handling codex endpoint /responses一样明明是个配置问题却以为是模型问题折腾半天没结果。2.3 方案选型为什么我最终选了文件化的skills管理市面上管理AI助手行为的方式有好几种一种是在对话里直接写长提示词一种是存成prompt模板还有一种是做成结构化的skill文件。我三种都用过最后稳定在文件化方案上原因有三个。第一可版本控制。skill文件就是普通文本可以放进Git仓库跟着项目一起迭代。谁改了哪条规范什么时候改的一目了然。提示词存在聊天记录里过两周就找不到了。第二可组合。一个项目可能需要前端skill、测试skill、部署skill它们可以独立存在按需加载。而不是把所有规则塞进一个巨大的提示词里导致AI注意力分散。第三跨工具复用。claude code和codex虽然底层模型不同但skill文件的结构可以设计成通用的。我现在的做法是核心规范写成Markdown放在项目根目录的.skills/文件夹下不同工具通过各自的配置去引用。这样换工具的时候规范不用重写。当然文件化方案也有代价初期搭建麻烦需要想清楚目录结构和加载逻辑。但一旦跑通后面就是复制粘贴的事。热搜里claude 国内安装skills 官方市场、codex好用的skills这些搜索说明很多人已经在找现成的skill包了但我建议至少自己写一遍核心规范因为每个项目的技术栈和团队习惯都不一样直接抄别人的往往水土不服。3. 核心细节解析与实操要点3.1 skill文件的基本结构一个最小可用示例一个skill文件本质上就是一份带元信息的Markdown。我拿一个前端项目的代码规范skill举例结构大概是这样--- name: frontend-code-style description: React TypeScript项目的代码风格规范 version: 1.0.0 triggers: - 修改组件 - 新增页面 - 重构前端代码 --- # 前端代码风格规范 ## 组件结构 - 使用函数组件禁止class组件 - 组件文件放在 src/components/ 下每个组件一个文件夹 - 文件夹内包含 index.tsx、styles.module.css、types.ts ## 命名规范 - 组件名用PascalCase - 变量和函数用camelCase - 常量用UPPER_SNAKE_CASE - CSS类名用kebab-case ## 状态管理 - 全局状态用Zustandstore放在 src/stores/ - 局部状态优先用useState避免不必要的全局状态 ## 注意事项 - 禁止使用any类型 - 所有props必须定义TypeScript接口 - 事件处理函数必须以handle开头这个文件里---包裹的部分是元信息告诉AI这个skill叫什么、什么时候触发。下面的正文就是具体规范。triggers字段很关键它决定了AI在什么场景下会自动加载这个skill。如果你写得太宽泛比如只写“写代码”那AI可能在任何时候都加载它反而干扰其他任务。提示triggers不要写太多3到5个足够。写多了会导致skill被过度触发AI每次都要读一遍浪费上下文窗口。3.2 触发机制与加载顺序为什么你的skill有时候不生效我遇到过好几次“skill明明写了但AI不遵守”的情况排查下来基本都是触发机制的问题。不同工具对skill的加载逻辑不一样但核心原理类似AI会根据当前任务描述去匹配skill的triggers匹配上了才加载。这里有个坑如果你在对话里说“帮我看看这个组件”而skill的trigger写的是“修改组件”那可能匹配不上。因为“看看”和“修改”在语义上有关联但关键词不完全一致。解决办法有两个一是把trigger写得更宽泛比如“组件相关操作”二是在对话里明确说“按照前端代码风格规范来检查这个组件”。另一个坑是加载顺序。如果一个项目里有多个skill比如前端规范、测试规范、Git提交规范它们的加载顺序会影响AI的行为。我的经验是越具体的skill越靠后加载。比如先加载通用的代码风格再加载特定框架的规范最后加载当前任务的专项skill。这样AI会优先遵循最后加载的规则避免被通用规则覆盖。在claude code里你可以通过配置文件指定skill的加载顺序。在codex里通常是在项目根目录放一个.codex/skills/文件夹工具会按文件名排序加载。我一般用数字前缀来控制顺序比如01-base-style.md、02-react-patterns.md、03-testing.md。3.3 参数与配置那些容易写错的细节写skill的时候有几个参数和配置项特别容易出错我列个表对照一下配置项常见错误正确做法影响triggers写太多宽泛词3-5个具体场景词避免过度触发version不写或乱写语义化版本号方便追踪变更description写得太长一句话说清用途影响AI匹配精度文件编码用GBK统一UTF-8避免乱码导致解析失败缩进混用Tab和空格统一用空格部分工具解析会报错还有一个隐藏坑skill文件里的代码块语言标注。如果你在skill里写了示例代码一定要标注语言类型比如 typescript。否则AI可能会把示例代码当成实际代码去执行或者解析出错。我一开始没注意这个结果AI把我写的“错误示例”当成了“正确规范”产出的代码全是反例。注意skill文件不要写得太长。单个文件控制在200行以内超过就拆成多个skill。AI的上下文窗口有限加载太多内容会挤占实际任务的token。4. 实操过程与核心环节实现4.1 环境准备从零搭建skill目录结构假设你现在有一个前端项目想给它配置一套skills。第一步是建目录。我习惯在项目根目录下建一个.skills/文件夹结构如下项目根目录/ ├── .skills/ │ ├── 01-base-style.md │ ├── 02-react-patterns.md │ ├── 03-testing.md │ └── 04-git-commit.md ├── src/ ├── package.json └── ...为什么用数字前缀因为大部分工具按文件名排序加载数字前缀能确保基础规范先加载专项规范后加载。01-base-style.md放通用代码风格02-react-patterns.md放React特定模式03-testing.md放测试规范04-git-commit.md放提交信息格式。建好目录后需要在工具的配置里告诉它去哪里找skill。以claude code为例在项目根目录的.claude/config.json里加一行{ skillsPath: .skills/, autoLoadSkills: true }codex的配置类似但文件位置可能是.codex/config.toml[skills] path .skills/ auto_load true如果你用的是VS Code插件版的claude code配置入口在设置里搜索“skills path”填相对路径即可。热搜里vscode配置claude code、ubuntu配置claude code、claude code windows这些核心步骤都差不多区别只在路径分隔符和权限设置。4.2 编写第一个skill以“React组件规范”为例环境准备好之后开始写第一个skill。我拿02-react-patterns.md举例完整内容如下--- name: react-component-patterns description: React函数组件的编写模式与最佳实践 version: 1.0.0 triggers: - 新增React组件 - 重构组件 - 组件代码审查 --- # React组件编写模式 ## 组件定义 使用函数组件 TypeScript接口定义props typescript interface ButtonProps { label: string; onClick: () void; disabled?: boolean; } export function Button({ label, onClick, disabled false }: ButtonProps) { return ( button onClick{onClick} disabled{disabled} {label} /button ); }状态管理局部状态用useState初始值必须有明确类型副作用用useEffect依赖数组必须完整避免在render中直接修改状态性能优化列表渲染必须加key且key不能是数组索引复杂计算用useMemo包裹事件处理函数用useCallback包裹避免子组件不必要的重渲染禁止事项禁止使用index作为key禁止在useEffect中缺少依赖项禁止直接修改props写完之后保存文件。然后在对话里测试让AI“新增一个Modal组件”。如果配置正确AI应该会按照这个skill里的模式来写代码——函数组件、TypeScript接口、明确的props类型。 我实测下来第一次配置经常不生效原因通常是路径写错了或者文件编码不对。排查方法很简单在对话里问AI“你现在加载了哪些skill”它会列出当前生效的skill列表。如果列表是空的说明配置没生效回去检查路径和文件名。 ### 4.3 多工具适配让同一套skill在claude code和codex里都能用 前面提到我希望同一套skill文件能在不同工具里复用。实际操作中claude code 和 codex 对skill文件的解析略有差异主要体现在元信息字段上。claude code 支持 triggers 字段做自动匹配codex 更依赖文件名和目录结构。 我的做法是**核心规范写成纯Markdown元信息尽量精简只保留name和description**。然后在各工具的配置里分别指定加载规则。比如在 codex 里我通过 .codex/config.toml 指定 toml [skills] path .skills/ auto_load true load_order [01-base-style.md, 02-react-patterns.md, 03-testing.md]这样即使codex不解析triggers字段也能按顺序加载所有skill。而在claude code里triggers字段能帮它更精准地匹配场景减少不必要的加载。热搜里codex接入deepseek、claude code 调用lmstudio的本地模型这些涉及的是模型后端切换跟skill机制是两层东西。skill管的是“行为规范”模型管的是“生成能力”。两者可以独立配置互不影响。4.4 团队协作把skill纳入代码审查流程个人用skill是一回事团队用是另一回事。我现在的做法是把.skills/目录纳入Git管理任何修改都要走Pull Request。这样有几个好处一是规范变更可追溯二是新成员入职时直接clone仓库就能获得完整的AI辅助配置三是可以通过CI检查skill文件的格式是否合法。具体操作上我在项目的package.json里加了一个脚本{ scripts: { lint:skills: node scripts/validate-skills.js } }validate-skills.js的作用是检查每个skill文件是否有合法的元信息、triggers是否超过5个、文件编码是否为UTF-8。这个脚本不复杂核心逻辑就是读文件、解析frontmatter、做几个断言。跑一次大概两秒钟放在CI的lint阶段就行。提示团队协作时skill的命名要统一。我见过有的项目用中文文件名有的用英文还有的用拼音最后乱成一锅粥。建议统一用英文kebab-case比如react-patterns.md、api-conventions.md。5. 常见问题与排查技巧实录5.1 skill不生效的排查清单这是被问得最多的问题。我整理了一个排查清单按顺序检查排查项检查方法常见问题路径配置确认配置文件里的skillsPath指向正确相对路径基准目录搞错文件编码用file命令查看GBK编码导致解析失败元信息格式检查---是否成对出现缺少闭合的---triggers匹配在对话里问AI加载了哪些skilltrigger词与任务描述不匹配加载顺序检查文件名排序后面的skill覆盖了前面的工具版本确认工具支持skill功能旧版本不支持我遇到最多的是路径问题。比如在claude code里skillsPath是相对于项目根目录还是当前工作目录不同版本行为不一样。保险的做法是写绝对路径或者用./明确表示当前目录。另一个高频问题是triggers写得太窄。比如你写的是“修改React组件”但实际对话里说的是“调整一下这个组件的样式”语义匹配不上。解决办法是在triggers里加一些同义词或者干脆在对话里明确说“按照React组件规范来改”。5.2 多个skill冲突怎么办当项目里有多个skill时可能会出现规则冲突。比如01-base-style.md说“变量用camelCase”但02-react-patterns.md说“组件文件名用PascalCase”。这其实不算冲突因为作用对象不同。但如果是同一条规则被两个skill以不同方式定义就会出问题。我的处理原则是后加载的skill覆盖先加载的。所以把更具体、更特殊的规则放在后面。比如通用命名规范放01React特定命名放02测试文件命名放03。这样AI会优先遵循最后加载的规则。如果冲突无法通过顺序解决那就需要合并。我一般会在01-base-style.md里写一个“规则优先级”章节明确说明当本文件与其他skill冲突时以更具体的skill为准。这样AI在解析时会有个判断依据。5.3 性能与上下文窗口的平衡skill文件不是越多越好。每加载一个skill就会占用一部分上下文窗口。如果你的项目有20个skill每个200行那就是4000行文本AI可能还没开始干活就已经被规范淹没了。我的经验值是单个项目控制在5到8个skill总行数不超过1000行。超过这个量就要考虑合并或者按需加载。按需加载的做法是不在配置里开启autoLoadSkills而是在对话里手动指定“加载前端规范skill”。这样只有当前任务相关的skill才会被加载节省上下文。另外skill文件里的示例代码要精简。我见过有人在skill里贴了完整的组件实现两百多行其实没必要。示例只需要展示关键模式比如props定义、状态管理方式不需要把整个组件写出来。5.4 从热搜词看常见误区翻一遍热搜词能看出不少人在踩同样的坑。比如cc switch local proxy failed while handling codex endpoint /responses这明显是配置代理时出的问题跟skill本身没关系但很多人会误以为是skill写错了。再比如your organization has disabled claude subscription access for claude code这是账号权限问题也不是skill能解决的。还有安卓脱壳skills、前任skills官方下载这种明显是搜错了词把“skills”当成了别的什么东西。这也说明“skills”这个词的语义确实比较宽泛容易混淆。我的建议是在搜索相关资料时加上具体工具名比如claude code skills、codex skills这样结果会精准很多。agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这个热搜词涉及的是agent安全领域跟日常开发用的skill机制关系不大但提醒我们一点skill文件如果被恶意篡改可能会影响AI的行为。所以在团队协作中skill文件的变更一定要走审查流程不能随便改。6. 我个人的一些实操体会写了这么多最后分享几个我在实际使用中总结的小经验不一定对所有人适用但至少帮我省了不少时间。第一个是从最小可用skill开始。不要一上来就写十个skill先把最核心的代码风格规范写出来跑通流程确认AI能正确加载和遵循再逐步增加。我一开始贪多写了八个skill结果互相冲突排查了一整天才找到问题。第二个是定期清理skill。项目技术栈会变团队规范也会变半年前写的skill可能已经过时了。我现在的习惯是每个季度review一次.skills/目录把不再适用的规则删掉把新的实践加进去。skill文件不是写完就一劳永逸的它需要跟项目一起演进。第三个是不要过度依赖skill。skill能约束AI的行为但不能替代人的判断。AI产出的代码最终还是要人来审查。我见过有人把skill写得极其详细然后完全信任AI的输出结果出了bug才发现skill里有一条规则写反了。skill是辅助工具不是保险箱。第四个是多和社区交流。热搜里skills推荐、codex好用的skills、claude agent skills这些搜索说明很多人都在探索这个方向。我经常在技术社区看别人分享的skill写法有时候一个巧妙的triggers设计就能解决我困扰很久的问题。闭门造车不如多看看别人怎么做的。这个领域变化很快工具在迭代最佳实践也在不断更新。今天好用的方案三个月后可能就有更好的替代品。保持关注保持动手比收藏一堆教程更有用。