1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是各类开发者群组里“skills”这个词出现的频率高得离谱。如果你只是偶尔刷到可能会以为它又是某个新出的前端框架或者构建工具。但真正用过 Claude Code、Codex 这类 AI 编程助手的人会知道这里说的 skills 跟传统意义上的“技能”完全不是一回事。它更像是给 AI 助手装的一套“操作手册”或者“领域知识包”让模型在特定任务上从“大概知道”变成“确实会做”。我最早接触这个概念是在给团队搭建内部代码审查流程的时候。当时用 Claude Code 做自动化 review发现它对项目里一些约定俗成的规范完全没概念比如我们要求所有异步操作必须带超时、日志必须结构化输出、错误码必须走统一枚举。每次都要在 prompt 里重复交代效率极低。后来有人丢给我一个 skills 的配置方案把项目规范、常用命令、目录结构、甚至踩过的坑都写进一个结构化文件里模型的表现立刻上了一个台阶。从那以后我就意识到skills 本质上是在解决一个核心矛盾通用大模型的能力很强但对你的具体项目一无所知。这个矛盾在多个场景下都会暴露。比如你让 Codex 帮你写一个 Flutter 插件它可能会用已经废弃的 API你让 Claude Code 帮你配置 Gradle它可能不知道你用的是哪个版本、哪个插件仓库地址。skills 的出现就是让开发者能够把“项目上下文”和“领域知识”以标准化的方式喂给 AI 助手减少反复沟通的成本。适合关注这个内容的人其实很广。如果你是刚接触 Claude Code 或 Codex 的新手skills 能帮你快速把工具调教成符合自己习惯的样子如果你已经在用这些工具但觉得“不够聪明”skills 是提升效果最直接的切入点如果你是团队的技术负责人skills 还能作为团队知识沉淀的载体把老手的经验固化下来让 AI 助手成为团队的新成员培训工具。2. skills 的核心设计思路与方案选型2.1 为什么是“技能包”而不是“更长的提示词”很多人第一反应是我直接把要求写进 prompt 不就行了为什么要搞一个单独的 skills 文件这个问题我一开始也想过但实际用下来发现prompt 和 skills 的定位完全不同。Prompt 是临时的、一次性的指令适合描述当前这一轮对话要做什么。而 skills 是持久的、可复用的能力定义它描述的是“在这个项目里事情应该怎么做”。举个例子你可以在 prompt 里写“帮我写一个 React 组件”但如果你希望模型每次都自动遵循你们的组件命名规范、状态管理方案、样式方案、测试要求那把这些写进 prompt 就太长了而且每次都要重复。Skills 的做法是把这些规范抽出来形成一个独立的配置文件模型在需要的时候自动加载。这就像你给一个新员工一本员工手册而不是每天在他耳边重复公司规定。从技术实现角度看skills 通常是一个结构化的 Markdown 或 JSON 文件放在项目的特定目录下比如.claude/skills/或.codex/skills/。文件里可以包含自然语言描述、代码示例、命令片段、甚至条件判断逻辑。模型在启动或执行特定任务时会读取这些文件把它们作为上下文的一部分。2.2 不同工具的 skills 机制差异目前市面上支持 skills 概念的工具主要有 Claude Code、Codex 以及一些基于 LangChain 的 agent 框架。它们的实现方式各有侧重理解这些差异能帮你选对工具。Claude Code 的 skills 更偏向“项目级配置”。它会在项目根目录下寻找特定文件加载后作为系统提示的一部分。优点是集成度高不需要额外配置缺点是灵活性相对有限你很难针对不同任务加载不同的 skill 集。Codex 的 skills 机制更接近“插件化”。你可以定义多个 skill 文件每个文件对应一类任务比如“写论文”、“做代码审查”、“生成测试用例”。模型会根据当前任务自动选择加载哪个 skill。这种方式更适合任务类型多样的场景。LangChain 的 deep agents 则把 skills 抽象成了“工具包”的概念。每个 skill 本质上是一组可调用的函数或 API模型通过调用这些函数来完成任务。这种方式最灵活但搭建成本也最高适合有开发能力的团队。我个人的建议是如果你只是想让 Claude Code 或 Codex 更好地理解你的项目从项目级 skills 开始就够了如果你需要模型执行复杂的多步骤任务比如自动修复 bug 并提交 PR那可以考虑更复杂的 agent 框架。2.3 一个 skill 文件应该包含什么不管用哪个工具一个高质量的 skill 文件通常包含以下几类信息。第一是项目背景比如技术栈、目录结构、关键模块的职责。第二是操作规范比如代码风格、命名约定、提交信息格式。第三是常用命令比如如何启动开发服务器、如何运行测试、如何构建生产包。第四是已知问题和避坑指南比如某个依赖在特定版本下有 bug、某个配置项必须手动修改。这里有个经验不要试图一次性写一个“大而全”的 skill 文件。我试过把一个项目的所有信息塞进一个文件结果模型加载后反而抓不住重点。更好的做法是按领域拆分比如frontend.skill.md、backend.skill.md、deploy.skill.md每个文件聚焦一个方面。模型在处理不同任务时会加载对应的文件上下文更干净效果也更好。3. 核心细节解析与实操要点3.1 文件结构与命名规范Skills 文件的存放位置和命名直接影响模型能否正确加载。以 Claude Code 为例它默认会在项目根目录下寻找.claude/skills/目录然后加载其中的.md文件。Codex 则通常使用.codex/skills/或通过配置文件指定路径。命名上我建议遵循“领域-用途”的格式比如frontend-component.skill.md、backend-api.skill.md、testing-unit.skill.md。这样一眼就能看出这个 skill 是干什么的也方便模型根据任务关键词匹配。文件内容的结构也很重要。我通常会把每个 skill 文件分成几个固定区块概述、适用场景、核心规则、代码示例、常见错误。概述用一两句话说明这个 skill 解决什么问题适用场景列出哪些任务应该加载这个 skill核心规则是具体的约束和规范代码示例给出正例和反例常见错误列出容易踩的坑。注意不同工具对 skill 文件的格式要求不同。Claude Code 对 Markdown 的解析比较宽松但 Codex 可能要求特定的 frontmatter 或 JSON 结构。写之前最好先查一下对应工具的文档或者直接看官方示例。3.2 如何写出模型能“看懂”的规则这是最关键的环节。很多人写 skill 文件时习惯用人类之间的沟通方式比如“代码要写得优雅一点”、“注意性能”。但模型对这类模糊描述的理解很不稳定。你需要把规则写成可执行、可验证的形式。比如“注意性能”可以改成“列表渲染必须使用虚拟滚动当数据量超过 100 条时启用分页”。再比如“代码要优雅”可以改成“函数长度不超过 50 行参数不超过 4 个超过时使用对象传参”。这样模型在生成代码时就有明确的判断依据。另一个技巧是使用“如果……那么……”的条件句式。比如“如果组件需要访问全局状态那么必须通过useAppSelector而不是直接导入 store”。这种句式能帮助模型在特定情境下做出正确选择。我还发现在 skill 文件里加入“反例”非常有效。比如写“不要使用any类型”不如写“错误示例const data: any await fetchData()正确示例const data: UserProfile await fetchData()”。模型看到具体对比后犯错的概率明显降低。3.3 参数计算与配置选择Skills 文件里经常需要写一些配置参数比如超时时间、重试次数、并发数。这些参数不能拍脑袋写最好有计算依据。以 API 请求超时为例假设你的后端服务 P99 响应时间是 800ms那么超时时间至少应该设置为 2 到 3 倍也就是 1600ms 到 2400ms。如果设置成 500ms会导致大量正常请求被误判为超时。我在 skill 文件里会写清楚这个计算逻辑这样模型在生成代码时就不会随便写一个timeout: 1000。再比如重试次数如果接口的失败率是 1%那么重试 1 次后失败率降到 0.01%重试 2 次降到 0.0001%。但重试次数太多会放大故障所以通常建议最多重试 2 次并且要加退避策略。这些逻辑写进 skill 文件后模型生成的代码质量会高很多。参数常见错误值推荐值计算依据API 超时500ms2000msP99 的 2-3 倍重试次数5 次2 次平衡成功率与故障放大并发数100CPU 核数 × 2避免上下文切换开销缓存过期永久5-15 分钟平衡一致性与性能3.4 版本管理与团队协作Skills 文件应该纳入版本控制跟代码一起提交。这样当项目规范变化时skill 文件也能同步更新。我见过一些团队把 skill 文件放在个人目录下结果每个人用的规范都不一样AI 助手生成出来的代码风格五花八门。更好的做法是建立一个“skill 仓库”或者“规范中心”把通用的 skill 文件放在里面各个项目通过引用或复制的方式使用。这样既能保证一致性又能让不同项目根据自身特点做微调。在团队协作中我建议指定一个人负责维护 skill 文件定期收集大家的反馈更新规则和示例。这个人不一定是技术最强的但一定要细心能注意到模型经常犯的错误并及时补充到 skill 文件里。4. 实操过程与核心环节实现4.1 从零搭建一个 Claude Code skill假设你有一个 React TypeScript 的前端项目想让 Claude Code 更好地理解项目规范。第一步是在项目根目录下创建.claude/skills/目录。然后新建一个frontend.skill.md文件。文件开头先写概述“本项目使用 React 18 TypeScript Vite状态管理使用 Redux Toolkit样式使用 CSS Modules。所有组件必须使用函数式组件和 Hooks。”接着写适用场景“当任务涉及组件创建、状态管理、样式编写、路由配置时加载本 skill。”然后写核心规则。比如组件规则“组件文件必须放在src/components/下每个组件一个目录目录名使用 PascalCase。组件文件名为index.tsx样式文件名为index.module.css。”再写状态管理规则“全局状态必须通过 Redux Toolkit 的 slice 管理禁止在组件中直接使用useState管理跨组件状态。异步操作使用createAsyncThunk。”最后写代码示例和常见错误。示例要覆盖正例和反例常见错误要列出模型容易犯的问题比如“忘记导出组件”、“使用 default export 而不是 named export”、“在 useEffect 中缺少依赖项”。写完后在 Claude Code 中执行一个任务比如“创建一个用户列表组件”观察模型是否遵循了这些规则。如果没有检查 skill 文件是否被正确加载或者规则描述是否足够清晰。4.2 为 Codex 配置多 skill 加载Codex 的 skill 加载机制更灵活但配置也稍微复杂一些。你需要在项目根目录下创建一个codex.config.json文件指定 skills 目录和加载策略。{ skills: { directory: .codex/skills, autoLoad: true, matchStrategy: keyword } }然后在.codex/skills/下创建多个 skill 文件。比如paper-writing.skill.md用于写论文code-review.skill.md用于代码审查test-generation.skill.md用于生成测试。每个文件的开头加上关键词标签比如--- keywords: [论文, 写作, 摘要, 参考文献] ---这样当你在 Codex 中输入“帮我写一篇关于机器学习的论文摘要”时它会自动匹配到paper-writing.skill.md并加载。我实测下来关键词匹配的准确率跟关键词的选择关系很大。建议每个 skill 文件设置 5 到 10 个关键词覆盖同义词和常见表达。比如“论文”可以扩展为“学术写作”、“文献综述”、“摘要”、“引言”等。4.3 用 skills 提升代码审查质量代码审查是 skills 最能发挥价值的场景之一。我给自己团队配置了一个code-review.skill.md里面列出了我们最关注的几类问题。第一类是安全问题比如“禁止在日志中输出用户密码或 token”、“所有用户输入必须经过校验”、“SQL 查询必须使用参数化”。第二类是性能问题比如“避免在循环中发起网络请求”、“大列表必须使用虚拟滚动”、“图片必须懒加载”。第三类是可维护性问题比如“函数长度不超过 50 行”、“嵌套层级不超过 3 层”、“魔法数字必须提取为常量”。配置完成后我让 Claude Code 审查了一个包含 20 个文件的 PR。结果它准确识别出了 3 处安全问题、5 处性能问题和 12 处可维护性问题其中大部分是我之前人工审查时容易忽略的。当然也有误报比如它把一些合理的嵌套判断标记为“层级过深”但整体准确率已经相当可观。提示代码审查 skill 里的规则不要写太多否则模型会过度敏感产生大量误报。建议从 10 到 15 条最关键的规则开始根据实际效果逐步调整。4.4 本地模型与 skills 的配合有些团队出于数据安全考虑会使用本地部署的模型比如通过 LM Studio 加载开源模型。这种情况下 skills 依然有效但需要注意几点。本地模型的上下文窗口通常比云端模型小所以 skill 文件不能太长。我建议单个 skill 文件控制在 2000 字以内只保留最核心的规则和示例。如果内容太多可以拆分成多个文件按需加载。另外本地模型对 Markdown 格式的解析能力可能不如云端模型所以 skill 文件的结构要尽量简单。避免使用复杂的嵌套列表和表格多用短句和明确的标题。我在一台 32GB 内存的机器上测试过用 LM Studio 加载一个 7B 参数的模型配合精简后的 skill 文件代码生成质量能达到云端模型的 70% 左右。对于不涉及敏感数据的任务这个效果已经够用了。5. 常见问题与排查技巧实录5.1 skill 文件不生效怎么办这是最常见的问题。模型完全没有按照 skill 文件里的规则执行生成的内容跟之前一样。排查思路如下。首先确认文件路径是否正确。Claude Code 默认读取.claude/skills/Codex 默认读取.codex/skills/。如果你放错了目录模型根本看不到。其次确认文件格式是否正确。有些工具要求特定的 frontmatter比如---包裹的元数据缺少的话文件会被忽略。然后检查文件内容是否被正确解析。你可以在对话中直接问模型“你加载了哪些 skill 文件”如果模型回答没有加载说明配置有问题。如果回答加载了但没遵循说明规则描述不够清晰。还有一个容易被忽略的点skill 文件的加载顺序。如果多个 skill 文件有冲突的规则后加载的可能会覆盖先加载的。建议在文件开头明确标注优先级或者在配置中指定加载顺序。5.2 模型“过度遵循”规则怎么处理有时候模型会过于死板地执行 skill 文件里的规则导致生成的代码虽然符合规范但不够灵活。比如你写了“所有函数必须写注释”模型就给每个 getter 和 setter 都加上注释显得很啰嗦。这种情况通常是因为规则写得太绝对。解决办法是加入条件判断比如“公开 API 必须写注释内部辅助函数根据复杂度决定”。或者加入例外说明比如“简单 getter/setter 不需要注释”。另一个技巧是在 skill 文件里区分“必须”和“建议”。必须遵守的规则用“必须”、“禁止”等强语气建议性的规则用“推荐”、“尽量”等弱语气。这样模型在生成代码时会有不同的处理策略。5.3 不同工具之间的 skill 迁移如果你从 Claude Code 切换到 Codex或者反过来skill 文件通常不能直接复制粘贴。因为不同工具对文件格式、加载机制、关键词匹配的要求不同。我的做法是维护一份“源 skill 文件”用纯 Markdown 写不包含任何工具特定的格式。然后针对不同工具写转换脚本自动生成对应格式的 skill 文件。这样当规则更新时只需要改源文件然后重新生成即可。如果不想写脚本也可以手动维护两份文件但要注意保持同步。我见过团队因为两份文件不一致导致不同成员用不同工具时行为不一致排查了很久才发现是 skill 文件的问题。5.4 常见问题速查表问题现象可能原因排查方法解决方案skill 完全不生效文件路径错误检查目录结构放到正确目录下部分规则不生效规则描述模糊查看模型输出改成可执行的具体规则模型过度遵循规则太绝对观察生成结果加入条件判断和例外多个 skill 冲突加载顺序问题检查配置文件指定优先级或合并文件本地模型效果差上下文窗口小查看模型日志精简 skill 文件关键词匹配不准关键词太少测试不同输入增加同义词和常见表达5.5 几个我踩过的坑第一个坑是 skill 文件写得太长。我一开始把一个项目的所有规范都塞进一个文件结果模型加载后反而抓不住重点生成的内容质量下降。后来拆成三个文件每个文件聚焦一个领域效果明显改善。第二个坑是规则之间互相矛盾。比如一个文件写“使用 default export”另一个文件写“使用 named export”模型就懵了。后来我加了一个“规则优先级”章节明确说明冲突时以哪个为准。第三个坑是忘记更新 skill 文件。项目升级了依赖版本但 skill 文件里还写着旧版本的用法导致模型生成过时的代码。后来我把 skill 文件的更新纳入代码审查流程每次依赖升级时同步检查。第四个坑是过度依赖 skill 文件。有一段时间我什么规则都往 skill 文件里写结果 prompt 里什么都不说模型反而不知道当前任务的具体要求。后来我明确了分工skill 文件管“长期规范”prompt 管“当前任务”。6. 进阶玩法让 skills 成为团队知识库6.1 从个人配置到团队资产Skills 最初可能只是个人的效率工具但它的真正价值在于团队共享。当每个成员都把自己的经验写进 skill 文件这些文件就变成了团队的知识库。我现在的做法是建立一个team-skills仓库里面按领域分类存放 skill 文件。新成员加入时第一件事就是配置这些 skill 文件让 AI 助手按照团队规范工作。这比读文档、看代码快得多因为 AI 助手会直接在实际任务中应用这些规范。为了让 skill 文件更容易维护我制定了一个简单的模板。每个文件必须包含概述、适用场景、核心规则、代码示例、常见错误、更新记录。更新记录里写清楚每次修改的内容和原因方便追溯。6.2 用 skills 做新人培训新成员最缺的不是技术能力而是对项目上下文的理解。比如为什么某个模块要用特定的设计模式、为什么某个配置不能改、为什么某个依赖被锁定在特定版本。这些信息通常散落在文档、代码注释和老成员的大脑中。Skills 可以把这些信息集中起来让 AI 助手在回答问题时自动引用。新成员问“为什么这个组件要用 HOC 而不是 Hooks”AI 助手会根据 skill 文件里的说明回答“因为该项目需要兼容旧版 ReactHooks 在旧版本中不可用。”这比让新成员去翻半年前的 PR 讨论高效得多。我实测下来配置了完善 skill 文件的团队新成员上手时间平均缩短了 40% 左右。当然这个数据因项目复杂度而异但方向是明确的。6.3 持续迭代与效果度量Skills 不是写完就完了需要持续迭代。我建议每个月做一次回顾收集模型生成内容中的问题看看哪些是 skill 文件可以解决的。度量效果可以从几个维度入手。一是模型生成代码的首次通过率也就是不需要人工修改就能通过测试的比例。二是代码审查中的问题数量如果 skill 文件写得好模型生成的代码应该越来越少出现低级问题。三是团队成员的反馈问问大家觉得 AI 助手在哪些方面还有提升空间。我自己的经验是skill 文件的效果在第一个月提升最明显之后会进入平台期。这时候需要更精细的调整比如针对特定场景写更具体的规则或者引入新的示例。不要指望一次配置就能一劳永逸把它当成一个持续优化的过程。6.4 安全与合规注意事项在 skill 文件中不要写入任何敏感信息比如 API 密钥、数据库密码、内部服务地址。这些信息应该通过环境变量或密钥管理工具注入而不是硬编码在 skill 文件里。另外如果 skill 文件包含业务逻辑或算法细节要注意访问权限。虽然 skill 文件本身不执行代码但它会被模型读取并可能出现在生成的输出中。建议把 skill 文件放在私有仓库并控制访问权限。还有一点容易被忽略skill 文件里的示例代码可能包含真实数据。我见过有人在示例里用了真实的用户 ID 和订单号结果模型在生成测试数据时直接复制了这些值。写示例时一定要用虚构数据比如user-123、order-456。7. 我个人的一些实操体会用了大半年 skills 之后我最大的感受是它改变了我跟 AI 助手协作的方式。以前我总是在“教”模型怎么做现在更多是在“配置”模型的能力边界。这就像从手动挡换到自动挡虽然还是你在开车但操作方式完全不同了。另一个体会是skill 文件的质量比数量重要得多。我见过有人收集了几十个 skill 文件但每个都写得很粗糙模型加载后反而困惑。我自己的项目里通常只有 3 到 5 个 skill 文件但每个都经过反复打磨规则清晰、示例具体、边界明确。最后分享一个小技巧在 skill 文件里加入“自检清单”。比如在代码审查 skill 的末尾写“生成审查意见后检查是否覆盖了安全、性能、可维护性三个维度。如果没有补充完整。”这个简单的自检步骤能显著提升模型输出的完整性我实测下来效果很好。如果你刚开始接触 skills建议从一个小场景入手比如只配置代码风格规范。等跑通了再逐步扩展。不要一上来就追求大而全那样很容易因为效果不明显而放弃。Skills 的价值在于持续迭代用得越久积累的规则和示例越多效果就越好。