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 ## 状态管理 - 全局状态用Zustand，store放在 `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的时候，有几个参数和配置项特别容易出错，我列个表对照一下：

还有一个隐藏坑：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不生效的排查清单

这是被问得最多的问题。我整理了一个排查清单，按顺序检查：

我遇到最多的是路径问题。比如在claude code里，skillsPath是相对于项目根目录还是当前工作目录，不同版本行为不一样。保险的做法是写绝对路径，或者用./明确表示当前目录。

另一个高频问题是triggers写得太窄。比如你写的是“修改React组件”，但实际对话里说的是“调整一下这个组件的样式”，语义匹配不上。解决办法是在triggers里加一些同义词，或者干脆在对话里明确说“按照React组件规范来改”。

5.2 多个skill冲突怎么办

当项目里有多个skill时，可能会出现规则冲突。比如01-base-style.md说“变量用camelCase”，但02-react-patterns.md说“组件文件名用PascalCase”。这其实不算冲突，因为作用对象不同。但如果是同一条规则被两个skill以不同方式定义，就会出问题。

我的处理原则是：后加载的skill覆盖先加载的。所以把更具体、更特殊的规则放在后面。比如通用命名规范放01，React特定命名放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设计就能解决我困扰很久的问题。闭门造车不如多看看别人怎么做的。

这个领域变化很快，工具在迭代，最佳实践也在不断更新。今天好用的方案，三个月后可能就有更好的替代品。保持关注，保持动手，比收藏一堆教程更有用。