1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术群还是各种开发者社区“skills”这个词出现的频率高得离谱。一开始我也纳闷一个英文单词而已怎么突然就火了后来自己上手折腾了一圈 Claude Code、Codex 这些工具之后才明白这里的 skills 根本不是指“技能”这个泛泛的概念而是指给 AI 编程助手挂载的一套可复用的能力模块。打个比方你就懂了。你新招了一个实习生他脑子很聪明但对你公司的代码规范、部署流程、日志格式一无所知。你要让他干活得先给他一份操作手册。skills 就是这份操作手册的标准化封装——你把某个特定任务的上下文、步骤、约束条件写成一个结构化的文件AI 助手在执行相关任务时就会自动加载这份“手册”按照你预设的方式来干活。这件事为什么重要因为大模型本身是通用的它不知道你们团队用的是什么构建工具、代码审查有什么规矩、API 返回格式长什么样。每次对话你都得重新解释一遍效率极低。skills 机制让这些领域知识变成可持久化、可复用、可分享的资产。你写一次团队所有人用你今天调好了明天它还记得。这篇文章我打算把 skills 这个东西从里到外讲透。包括它的核心设计思路是什么、怎么从零写一个能用的 skill、在 Claude Code 和 Codex 里分别怎么配置、实际用下来哪些坑必须提前知道。不管你是刚听说这个概念的新手还是已经在用但总觉得哪里不对劲的老手应该都能从里面找到有用的东西。2. skills 的核心设计逻辑为什么是这种形态2.1 从 prompt 工程到 skill 工程的演进早两年大家用 AI 写代码基本就是打开对话框把需求描述一遍等它生成。这种方式的问题很明显每次都是从零开始上下文全靠你手动喂。后来有了 system prompt你可以预设一些角色设定和规则但 system prompt 是全局的所有任务共享同一套指令没法针对不同场景做差异化。再往后发展就出现了 skills 这种形态。它的核心思路是按需加载、场景隔离。每个 skill 是一个独立的单元只在你需要的时候才被激活。比如你有一个专门处理数据库迁移的 skill只有当你提到“migration”或者“数据库变更”的时候它才会被加载进来。平时它就在那里待着不占用上下文窗口。这个设计的好处是显而易见的。第一上下文窗口是稀缺资源你不可能把所有规则都塞进 system prompt 里那样既浪费 token 又容易让模型注意力分散。第二不同任务需要的知识完全不同前端构建的规则和后端 API 设计的规则放在一起只会互相干扰。第三skill 可以独立版本管理你可以像维护代码一样维护你的 skill 库。2.2 skill 文件的解剖一个标准结构长什么样一个典型的 skill 通常包含以下几个部分。我用一个实际例子来说明假设我们要写一个“生成 RESTful API 接口”的 skill--- name: restful-api-generator description: 当用户需要创建新的 RESTful API 接口时使用此 skill trigger: 创建接口、新增 API、添加 endpoint --- ## 上下文 本项目使用 FastAPI 框架所有接口定义在 app/api/v1/ 目录下。 路由注册采用自动发现机制新增文件后无需手动注册。 ## 执行步骤 1. 在 app/api/v1/ 下创建新的路由文件命名格式为 {resource_name}.py 2. 使用 Pydantic 定义请求体和响应体放在 app/schemas/ 目录 3. 数据库操作统一走 app/crud/ 层的封装函数 4. 接口必须包含分页参数默认 page_size20最大不超过 100 5. 错误处理使用项目统一的 AppException 类 ## 约束条件 - 不允许在路由函数中直接写 SQL - 所有接口必须添加 OpenAPI 的 summary 和 description - 返回值统一使用 { code, data, message } 格式你看这个结构其实很直白。头部是元信息告诉系统这个 skill 叫什么、什么时候该用它。中间是具体的执行指令相当于给 AI 的一份 SOP。最后是硬性约束相当于代码规范里的 lint 规则。关键在于这些内容不是随便写的。每一条都对应着实际开发中容易出问题的地方。比如“不允许在路由函数中直接写 SQL”这条就是因为之前团队里有人图省事直接在路由里写查询后来改数据库的时候漏改了好几处出了线上事故。把这种教训固化到 skill 里后来的人就不会再犯同样的错误。2.3 触发机制skill 是怎么被“唤醒”的这是很多人容易忽略的一个细节。skill 不是自动生效的它需要一个触发机制。目前主流的触发方式有两种一种是关键词匹配。你在 skill 的元信息里定义一组 trigger 词当用户的输入包含这些词时系统就把对应的 skill 加载进来。这种方式简单直接但不够精准。比如你定义了“接口”作为触发词用户说“这个接口文档在哪”也会触发但其实他并不需要生成新接口。另一种是语义匹配。系统会根据 skill 的 description 和当前对话的语义相似度来决定是否加载。这种方式更智能但需要模型本身有较强的理解能力。实际用下来Claude Code 在这方面的表现比较自然它能根据上下文判断你到底是要“创建接口”还是只是“讨论接口”。我个人的经验是description 的写法比 trigger 词更重要。你要用自然语言清楚地描述“什么情况下应该使用这个 skill”而不是只堆砌几个关键词。比如上面那个例子description 写的是“当用户需要创建新的 RESTful API 接口时使用”这就比只写“接口、API、endpoint”要准确得多。3. 在 Claude Code 中配置和使用 skills 的完整流程3.1 环境准备与安装要点Claude Code 的安装本身不复杂但有几个地方容易卡住。首先是 Node.js 版本建议用 18 以上的 LTS 版本。我试过用 16 的版本安装过程没报错但运行的时候会出现一些奇怪的模块加载问题。安装命令很简单npm install -g anthropic-ai/claude-code装完之后第一次运行claude命令会引导你完成认证。这里注意如果你是在公司网络环境下可能会遇到证书问题。我遇到过一次是因为公司的代理证书没有被 Node.js 信任。解决办法是设置NODE_EXTRA_CA_CERTS环境变量指向公司的 CA 证书文件。认证完成后你的配置会保存在~/.claude/目录下。这个目录很重要后面配置 skills 也要在这里操作。3.2 skills 目录结构与加载规则Claude Code 默认从以下几个位置加载 skills优先级路径适用场景1项目根目录.claude/skills/项目专属 skill随代码仓库一起管理2用户目录~/.claude/skills/个人通用 skill跨项目复用3系统级/etc/claude/skills/团队或组织级别的共享 skill优先级高的会覆盖优先级低的同名 skill。这个设计很合理你可以在项目里放一个针对当前项目的定制版本同时保留用户目录下的通用版本给其他项目用。每个 skill 是一个独立的子目录目录名就是 skill 的标识符。目录里面至少包含一个SKILL.md文件也就是我们前面说的那个结构化文档。你还可以在目录里放其他辅助文件比如模板文件、示例代码、配置片段等skill 执行过程中可以引用这些文件。3.3 写一个能用的 skill从草稿到上线我来完整走一遍写 skill 的流程。假设我们要写一个“生成单元测试”的 skill。第一步确定边界。这个 skill 只负责生成单元测试不负责运行测试、不负责修复失败的测试。边界清晰很重要一个 skill 什么都管最后什么都管不好。第二步收集上下文。我需要知道项目用什么测试框架假设是 pytest、测试文件放在哪里假设是tests/目录镜像源码目录结构、有没有公共的 fixture假设conftest.py里有数据库 session 和 mock 用户、命名规范是什么假设是test_{function_name}.py。第三步写 SKILL.md--- name: unit-test-generator description: 当用户需要为某个函数或模块生成单元测试时使用此 skill --- ## 项目测试规范 - 测试框架pytest pytest-asyncio - 测试文件位置tests/ 目录目录结构与 src/ 保持一致 - 命名规范test_{module_name}.py测试函数命名为 test_{function_name}_{scenario} - 公共 fixture 定义在 tests/conftest.py包括 db_session 和 mock_user ## 生成步骤 1. 读取目标函数的源码识别其输入参数、返回值、副作用 2. 识别所有分支条件if/else、try/except、循环边界 3. 为每个分支生成至少一个测试用例 4. 使用 db_session fixture 处理数据库相关测试 5. 使用 mock_user fixture 处理需要认证的测试 6. 异步函数使用 pytest.mark.asyncio 装饰器 ## 必须遵守的规则 - 每个测试函数只测试一个行为 - 使用 assert 而不是 unittest.TestCase 的断言方法 - mock 外部服务调用不依赖真实网络请求 - 测试数据使用 factory 模式创建不硬编码第四步测试。写完之后在 Claude Code 里实际跑几个任务看看它是不是按照你预期的步骤在执行。我一般会准备三到五个典型场景来验证简单函数、带分支的函数、异步函数、依赖数据库的函数、需要 mock 外部服务的函数。第五步迭代。第一版肯定不完美。你可能会发现某些情况下 AI 没有按照你的步骤来或者生成的测试有重复。这时候不要急着推翻重写而是在原有基础上补充约束条件。比如发现它经常忘记加pytest.mark.asyncio那就在规则里把这条加粗强调。3.4 实操心得让 skill 真正好用的几个技巧用了几个月下来我总结了几个让 skill 效果明显提升的技巧。技巧一用“反例”代替“正例”。与其告诉 AI“应该怎么做”不如告诉它“不要怎么做”。因为大模型见过的好代码太多了你不需要教它怎么写好代码你需要的是防止它写出不符合你项目规范的代码。比如“不要使用print调试使用logger”就比“使用 logger 记录日志”更有效。技巧二把决策树写进去。很多任务不是线性的而是有分支的。比如“如果函数是异步的用 asyncio 测试如果是同步的直接调用”。把这种判断逻辑明确写出来AI 就不会搞混。技巧三控制 skill 的粒度。一个 skill 不要太长超过 200 行的 SKILL.md 效果会明显下降。如果内容太多拆成多个 skill通过组合来使用。比如“生成测试”和“运行测试”分成两个 skill各司其职。技巧四定期清理。项目在演进规范在变化skill 也要跟着更新。我一般每个月会花半小时 review 一下现有的 skill把过时的规则删掉把新踩的坑补进去。4. Codex 环境下的 skills 配置与差异对比4.1 Codex 的 skill 加载机制Codex 这边的 skill 机制和 Claude Code 大同小异但在细节上有一些值得注意的差异。Codex 的 skill 配置文件通常放在项目根目录的.codex/目录下文件名是skills.yaml或者skills.json。它采用的是集中式配置所有 skill 的元信息在一个文件里管理具体的 skill 内容可以放在单独的 markdown 文件里。这种设计的好处是总览性强你打开一个文件就能看到项目里所有可用的 skill。缺点是当 skill 数量多了之后这个文件会变得很长维护起来有点麻烦。Codex 的触发机制更偏向于显式调用。你可以在对话中直接说“使用 xxx skill 来完成这个任务”它就会加载对应的 skill。当然也支持自动匹配但实际用下来显式调用的准确率明显更高。4.2 两个平台 skill 写法的关键区别我整理了一个对比表格方便你快速了解差异维度Claude CodeCodex配置位置.claude/skills/目录每个 skill 独立目录.codex/skills.yaml集中管理元信息格式YAML frontmatterYAML/JSON 配置项触发方式语义匹配为主关键词为辅显式调用为主自动匹配为辅文件引用支持引用同目录下的辅助文件支持引用项目内任意路径的文件优先级项目 用户 系统项目配置覆盖全局配置调试方式/skills命令查看已加载的 skill日志中查看 skill 加载记录实际使用中我发现 Claude Code 的 skill 更适合“润物细无声”式的辅助你正常干活它在背后默默按照你的规范来。Codex 的 skill 更适合“明确指令”式的调用你告诉它用什么 skill它就严格按照那个 skill 的流程来执行。4.3 跨平台复用的实践方案如果你同时用 Claude Code 和 Codex肯定不想维护两套 skill。我的做法是内容与配置分离。具体的 skill 内容也就是那些执行步骤、约束条件写在一个独立的 markdown 文件里放在项目的docs/skills/目录下。然后 Claude Code 的SKILL.md和 Codex 的skills.yaml都引用这个文件。这样内容只需要维护一份配置各写各的。# .codex/skills.yaml skills: - name: restful-api-generator description: 创建新的 RESTful API 接口 content_file: docs/skills/restful-api-generator.md triggers: - 创建接口 - 新增 API!-- .claude/skills/restful-api-generator/SKILL.md -- --- name: restful-api-generator description: 当用户需要创建新的 RESTful API 接口时使用此 skill --- !-- 引用共享内容 --这个方案的好处是当你更新了 skill 内容两个平台同时生效不会出现版本不一致的问题。5. 常见问题与排查技巧实录5.1 skill 不生效的排查思路这是被问得最多的问题。你明明写了 skill但 AI 好像完全没看到。排查步骤我一般按这个顺序来第一步确认 skill 是否被加载。在 Claude Code 里输入/skills命令看看列表里有没有你的 skill。如果没有说明路径或者文件格式有问题。检查目录名是否正确、SKILL.md是否存在、frontmatter 格式是否合法。第二步确认触发条件是否满足。如果 skill 在列表里但没被激活说明触发条件没匹配上。这时候可以尝试在对话中显式提及 skill 的名称看看能不能手动触发。如果能手动触发但自动触发不行那就是 description 或者 trigger 词写得不够准确。第三步确认 skill 内容是否被正确解析。有时候 skill 被加载了但内容格式有问题导致 AI 理解不了。检查 markdown 格式是否正确有没有未闭合的代码块有没有特殊字符导致解析失败。第四步确认上下文窗口是否足够。如果你同时加载了太多 skill或者对话历史太长可能导致 skill 内容被截断。这时候需要精简 skill 内容或者开启新的对话。5.2 常见问题速查表问题现象可能原因解决方法skill 列表里找不到路径错误或文件缺失检查目录结构和文件名skill 加载了但不生效触发条件不匹配优化 description增加 trigger 词skill 内容被忽略格式解析失败检查 markdown 语法确保 frontmatter 正确skill 执行结果不稳定指令不够明确增加约束条件使用反例说明多个 skill 冲突优先级或触发重叠调整优先级明确各 skill 的边界skill 更新后不生效缓存问题重启 Claude Code 或清除缓存5.3 避坑经验那些文档里不会写的事坑一不要在 skill 里写太具体的代码。我一开始图省事直接把一段模板代码贴在 skill 里想着 AI 直接复制就行。结果发现它会把模板代码原封不动地输出连里面的示例变量名都不改。正确的做法是描述代码的结构和规则让 AI 根据实际情况生成。坑二skill 的命名要见名知义。我见过有人把 skill 命名为helper、utils这种过两个月自己都忘了是干什么的。建议用{动作}-{对象}的格式比如generate-api、review-pr、fix-lint。坑三不要试图用一个 skill 覆盖所有场景。我试过写一个“万能”的代码生成 skill结果就是什么场景都处理不好。后来拆成了五个小 skill每个针对特定场景效果反而好得多。坑四skill 也需要 code review。团队协作的时候skill 是共享的一个人写错了所有人都会受影响。我们现在的做法是 skill 的修改也要走 PR 流程至少一个人 review 过才能合并。坑五注意 skill 的加载顺序。当多个 skill 同时被触发时加载顺序会影响最终效果。一般来说越具体的 skill 应该越晚加载这样它的指令会覆盖前面更通用的指令。这个顺序可以通过目录命名或者配置项来控制。6. 进阶玩法让 skills 组合出更强的能力6.1 skill 链式调用单个 skill 的能力是有限的但多个 skill 组合起来就能完成复杂的任务。比如“创建一个新功能”这个任务可以拆解成生成数据模型 - 生成 API 接口 - 生成单元测试 - 生成文档。每个环节对应一个 skill按顺序执行。实现链式调用的方式有两种。一种是显式编排你在对话中依次调用各个 skill每一步确认结果后再进行下一步。这种方式可控性强但需要人工介入。另一种是隐式组合你写一个“元 skill”在里面定义好调用链AI 会自动按顺序执行。这种方式效率高但调试起来比较麻烦。我个人的建议是对于关键任务用显式编排确保每一步都符合预期。对于重复性高的常规任务可以用隐式组合来提效。6.2 动态 skill根据项目状态自动调整进阶一点的玩法是让 skill 能够感知项目的当前状态动态调整自己的行为。比如一个“生成数据库迁移”的 skill它可以先检查当前的数据库版本然后根据版本差异生成对应的迁移脚本。实现这个功能需要在 skill 里嵌入一些探测指令比如“先运行alembic current查看当前版本”。AI 会执行这个命令拿到结果后再决定下一步怎么做。这比写死规则的 skill 灵活得多但也要注意安全性不要让 skill 执行危险的操作。6.3 团队协作中的 skill 管理当团队规模超过三五个人之后skill 的管理就需要一些规范了。我们目前的做法是所有 skill 放在项目的.claude/skills/目录下随代码一起版本管理每个 skill 必须有明确的 owner负责维护和更新skill 的修改走 PR 流程至少一人 review每月一次 skill review清理过时的补充新踩的坑新成员入职第一周要求阅读所有 skill 并尝试写一个自己的 skill这套流程跑下来效果还是很明显的。新人的上手时间从原来的两周缩短到了三天代码 review 中因为规范问题被打回的次数也少了很多。7. 我个人的一些体会写了这么多最后说几句掏心窝子的话。skills 这个东西本质上是在做一件事把隐性的团队知识显性化。以前这些知识散落在各种文档、口口相传、甚至某个老员工的脑子里现在你把它们固化下来变成 AI 能理解、能执行的指令。这件事的价值不在于让 AI 多干了多少活而在于让团队的每一个成员包括新人和 AI都能按照同一套标准来做事。标准统一了沟通成本就降下来了返工就少了整体效率自然就上去了。我刚开始写 skill 的时候总想着写得大而全恨不得把所有情况都覆盖到。后来发现好的 skill 都是从小处着手的。先解决一个具体的、高频的、容易出错的问题跑通了再慢慢扩展。一个能稳定运行的简单 skill比十个花哨但不可靠的 skill 有价值得多。另外不要指望 AI 能 100% 按照你的 skill 来执行。它有时候会“自作主张”有时候会“理解偏差”。这很正常毕竟它不是 deterministic 的程序。你要做的是通过不断的反馈和调整让它的准确率从 70% 提到 85%再到 95%。每提高一个百分点你省下的时间都是实实在在的。最后分享一个小技巧每次 AI 没有按照 skill 执行的时候不要只是重新说一遍而是想一想“为什么它没理解”。往往是因为你的指令有歧义或者缺少了某个关键上下文。把这个原因补进 skill 里下次它就不会再犯同样的错误了。这个过程本身就是在把你的经验沉淀成可复用的资产。 
长河君 · 2026/10/8 10:06:58 · 阅读 1.2k AI编程助手skills实战：从配置到进阶的完整指南
1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术群还是各种开发者社区“skills”这个词出现的频率高得离谱。一开始我也纳闷一个英文单词而已怎么突然就火了后来自己上手折腾了一圈 Claude Code、Codex 这些工具之后才明白这里的 skills 根本不是指“技能”这个泛泛的概念而是指给 AI 编程助手挂载的一套可复用的能力模块。打个比方你就懂了。你新招了一个实习生他脑子很聪明但对你公司的代码规范、部署流程、日志格式一无所知。你要让他干活得先给他一份操作手册。skills 就是这份操作手册的标准化封装——你把某个特定任务的上下文、步骤、约束条件写成一个结构化的文件AI 助手在执行相关任务时就会自动加载这份“手册”按照你预设的方式来干活。这件事为什么重要因为大模型本身是通用的它不知道你们团队用的是什么构建工具、代码审查有什么规矩、API 返回格式长什么样。每次对话你都得重新解释一遍效率极低。skills 机制让这些领域知识变成可持久化、可复用、可分享的资产。你写一次团队所有人用你今天调好了明天它还记得。这篇文章我打算把 skills 这个东西从里到外讲透。包括它的核心设计思路是什么、怎么从零写一个能用的 skill、在 Claude Code 和 Codex 里分别怎么配置、实际用下来哪些坑必须提前知道。不管你是刚听说这个概念的新手还是已经在用但总觉得哪里不对劲的老手应该都能从里面找到有用的东西。2. skills 的核心设计逻辑为什么是这种形态2.1 从 prompt 工程到 skill 工程的演进早两年大家用 AI 写代码基本就是打开对话框把需求描述一遍等它生成。这种方式的问题很明显每次都是从零开始上下文全靠你手动喂。后来有了 system prompt你可以预设一些角色设定和规则但 system prompt 是全局的所有任务共享同一套指令没法针对不同场景做差异化。再往后发展就出现了 skills 这种形态。它的核心思路是按需加载、场景隔离。每个 skill 是一个独立的单元只在你需要的时候才被激活。比如你有一个专门处理数据库迁移的 skill只有当你提到“migration”或者“数据库变更”的时候它才会被加载进来。平时它就在那里待着不占用上下文窗口。这个设计的好处是显而易见的。第一上下文窗口是稀缺资源你不可能把所有规则都塞进 system prompt 里那样既浪费 token 又容易让模型注意力分散。第二不同任务需要的知识完全不同前端构建的规则和后端 API 设计的规则放在一起只会互相干扰。第三skill 可以独立版本管理你可以像维护代码一样维护你的 skill 库。2.2 skill 文件的解剖一个标准结构长什么样一个典型的 skill 通常包含以下几个部分。我用一个实际例子来说明假设我们要写一个“生成 RESTful API 接口”的 skill--- name: restful-api-generator description: 当用户需要创建新的 RESTful API 接口时使用此 skill trigger: 创建接口、新增 API、添加 endpoint --- ## 上下文 本项目使用 FastAPI 框架所有接口定义在 app/api/v1/ 目录下。 路由注册采用自动发现机制新增文件后无需手动注册。 ## 执行步骤 1. 在 app/api/v1/ 下创建新的路由文件命名格式为 {resource_name}.py 2. 使用 Pydantic 定义请求体和响应体放在 app/schemas/ 目录 3. 数据库操作统一走 app/crud/ 层的封装函数 4. 接口必须包含分页参数默认 page_size20最大不超过 100 5. 错误处理使用项目统一的 AppException 类 ## 约束条件 - 不允许在路由函数中直接写 SQL - 所有接口必须添加 OpenAPI 的 summary 和 description - 返回值统一使用 { code, data, message } 格式你看这个结构其实很直白。头部是元信息告诉系统这个 skill 叫什么、什么时候该用它。中间是具体的执行指令相当于给 AI 的一份 SOP。最后是硬性约束相当于代码规范里的 lint 规则。关键在于这些内容不是随便写的。每一条都对应着实际开发中容易出问题的地方。比如“不允许在路由函数中直接写 SQL”这条就是因为之前团队里有人图省事直接在路由里写查询后来改数据库的时候漏改了好几处出了线上事故。把这种教训固化到 skill 里后来的人就不会再犯同样的错误。2.3 触发机制skill 是怎么被“唤醒”的这是很多人容易忽略的一个细节。skill 不是自动生效的它需要一个触发机制。目前主流的触发方式有两种一种是关键词匹配。你在 skill 的元信息里定义一组 trigger 词当用户的输入包含这些词时系统就把对应的 skill 加载进来。这种方式简单直接但不够精准。比如你定义了“接口”作为触发词用户说“这个接口文档在哪”也会触发但其实他并不需要生成新接口。另一种是语义匹配。系统会根据 skill 的 description 和当前对话的语义相似度来决定是否加载。这种方式更智能但需要模型本身有较强的理解能力。实际用下来Claude Code 在这方面的表现比较自然它能根据上下文判断你到底是要“创建接口”还是只是“讨论接口”。我个人的经验是description 的写法比 trigger 词更重要。你要用自然语言清楚地描述“什么情况下应该使用这个 skill”而不是只堆砌几个关键词。比如上面那个例子description 写的是“当用户需要创建新的 RESTful API 接口时使用”这就比只写“接口、API、endpoint”要准确得多。3. 在 Claude Code 中配置和使用 skills 的完整流程3.1 环境准备与安装要点Claude Code 的安装本身不复杂但有几个地方容易卡住。首先是 Node.js 版本建议用 18 以上的 LTS 版本。我试过用 16 的版本安装过程没报错但运行的时候会出现一些奇怪的模块加载问题。安装命令很简单npm install -g anthropic-ai/claude-code装完之后第一次运行claude命令会引导你完成认证。这里注意如果你是在公司网络环境下可能会遇到证书问题。我遇到过一次是因为公司的代理证书没有被 Node.js 信任。解决办法是设置NODE_EXTRA_CA_CERTS环境变量指向公司的 CA 证书文件。认证完成后你的配置会保存在~/.claude/目录下。这个目录很重要后面配置 skills 也要在这里操作。3.2 skills 目录结构与加载规则Claude Code 默认从以下几个位置加载 skills优先级路径适用场景1项目根目录.claude/skills/项目专属 skill随代码仓库一起管理2用户目录~/.claude/skills/个人通用 skill跨项目复用3系统级/etc/claude/skills/团队或组织级别的共享 skill优先级高的会覆盖优先级低的同名 skill。这个设计很合理你可以在项目里放一个针对当前项目的定制版本同时保留用户目录下的通用版本给其他项目用。每个 skill 是一个独立的子目录目录名就是 skill 的标识符。目录里面至少包含一个SKILL.md文件也就是我们前面说的那个结构化文档。你还可以在目录里放其他辅助文件比如模板文件、示例代码、配置片段等skill 执行过程中可以引用这些文件。3.3 写一个能用的 skill从草稿到上线我来完整走一遍写 skill 的流程。假设我们要写一个“生成单元测试”的 skill。第一步确定边界。这个 skill 只负责生成单元测试不负责运行测试、不负责修复失败的测试。边界清晰很重要一个 skill 什么都管最后什么都管不好。第二步收集上下文。我需要知道项目用什么测试框架假设是 pytest、测试文件放在哪里假设是tests/目录镜像源码目录结构、有没有公共的 fixture假设conftest.py里有数据库 session 和 mock 用户、命名规范是什么假设是test_{function_name}.py。第三步写 SKILL.md--- name: unit-test-generator description: 当用户需要为某个函数或模块生成单元测试时使用此 skill --- ## 项目测试规范 - 测试框架pytest pytest-asyncio - 测试文件位置tests/ 目录目录结构与 src/ 保持一致 - 命名规范test_{module_name}.py测试函数命名为 test_{function_name}_{scenario} - 公共 fixture 定义在 tests/conftest.py包括 db_session 和 mock_user ## 生成步骤 1. 读取目标函数的源码识别其输入参数、返回值、副作用 2. 识别所有分支条件if/else、try/except、循环边界 3. 为每个分支生成至少一个测试用例 4. 使用 db_session fixture 处理数据库相关测试 5. 使用 mock_user fixture 处理需要认证的测试 6. 异步函数使用 pytest.mark.asyncio 装饰器 ## 必须遵守的规则 - 每个测试函数只测试一个行为 - 使用 assert 而不是 unittest.TestCase 的断言方法 - mock 外部服务调用不依赖真实网络请求 - 测试数据使用 factory 模式创建不硬编码第四步测试。写完之后在 Claude Code 里实际跑几个任务看看它是不是按照你预期的步骤在执行。我一般会准备三到五个典型场景来验证简单函数、带分支的函数、异步函数、依赖数据库的函数、需要 mock 外部服务的函数。第五步迭代。第一版肯定不完美。你可能会发现某些情况下 AI 没有按照你的步骤来或者生成的测试有重复。这时候不要急着推翻重写而是在原有基础上补充约束条件。比如发现它经常忘记加pytest.mark.asyncio那就在规则里把这条加粗强调。3.4 实操心得让 skill 真正好用的几个技巧用了几个月下来我总结了几个让 skill 效果明显提升的技巧。技巧一用“反例”代替“正例”。与其告诉 AI“应该怎么做”不如告诉它“不要怎么做”。因为大模型见过的好代码太多了你不需要教它怎么写好代码你需要的是防止它写出不符合你项目规范的代码。比如“不要使用print调试使用logger”就比“使用 logger 记录日志”更有效。技巧二把决策树写进去。很多任务不是线性的而是有分支的。比如“如果函数是异步的用 asyncio 测试如果是同步的直接调用”。把这种判断逻辑明确写出来AI 就不会搞混。技巧三控制 skill 的粒度。一个 skill 不要太长超过 200 行的 SKILL.md 效果会明显下降。如果内容太多拆成多个 skill通过组合来使用。比如“生成测试”和“运行测试”分成两个 skill各司其职。技巧四定期清理。项目在演进规范在变化skill 也要跟着更新。我一般每个月会花半小时 review 一下现有的 skill把过时的规则删掉把新踩的坑补进去。4. Codex 环境下的 skills 配置与差异对比4.1 Codex 的 skill 加载机制Codex 这边的 skill 机制和 Claude Code 大同小异但在细节上有一些值得注意的差异。Codex 的 skill 配置文件通常放在项目根目录的.codex/目录下文件名是skills.yaml或者skills.json。它采用的是集中式配置所有 skill 的元信息在一个文件里管理具体的 skill 内容可以放在单独的 markdown 文件里。这种设计的好处是总览性强你打开一个文件就能看到项目里所有可用的 skill。缺点是当 skill 数量多了之后这个文件会变得很长维护起来有点麻烦。Codex 的触发机制更偏向于显式调用。你可以在对话中直接说“使用 xxx skill 来完成这个任务”它就会加载对应的 skill。当然也支持自动匹配但实际用下来显式调用的准确率明显更高。4.2 两个平台 skill 写法的关键区别我整理了一个对比表格方便你快速了解差异维度Claude CodeCodex配置位置.claude/skills/目录每个 skill 独立目录.codex/skills.yaml集中管理元信息格式YAML frontmatterYAML/JSON 配置项触发方式语义匹配为主关键词为辅显式调用为主自动匹配为辅文件引用支持引用同目录下的辅助文件支持引用项目内任意路径的文件优先级项目 用户 系统项目配置覆盖全局配置调试方式/skills命令查看已加载的 skill日志中查看 skill 加载记录实际使用中我发现 Claude Code 的 skill 更适合“润物细无声”式的辅助你正常干活它在背后默默按照你的规范来。Codex 的 skill 更适合“明确指令”式的调用你告诉它用什么 skill它就严格按照那个 skill 的流程来执行。4.3 跨平台复用的实践方案如果你同时用 Claude Code 和 Codex肯定不想维护两套 skill。我的做法是内容与配置分离。具体的 skill 内容也就是那些执行步骤、约束条件写在一个独立的 markdown 文件里放在项目的docs/skills/目录下。然后 Claude Code 的SKILL.md和 Codex 的skills.yaml都引用这个文件。这样内容只需要维护一份配置各写各的。# .codex/skills.yaml skills: - name: restful-api-generator description: 创建新的 RESTful API 接口 content_file: docs/skills/restful-api-generator.md triggers: - 创建接口 - 新增 API!-- .claude/skills/restful-api-generator/SKILL.md -- --- name: restful-api-generator description: 当用户需要创建新的 RESTful API 接口时使用此 skill --- !-- 引用共享内容 --这个方案的好处是当你更新了 skill 内容两个平台同时生效不会出现版本不一致的问题。5. 常见问题与排查技巧实录5.1 skill 不生效的排查思路这是被问得最多的问题。你明明写了 skill但 AI 好像完全没看到。排查步骤我一般按这个顺序来第一步确认 skill 是否被加载。在 Claude Code 里输入/skills命令看看列表里有没有你的 skill。如果没有说明路径或者文件格式有问题。检查目录名是否正确、SKILL.md是否存在、frontmatter 格式是否合法。第二步确认触发条件是否满足。如果 skill 在列表里但没被激活说明触发条件没匹配上。这时候可以尝试在对话中显式提及 skill 的名称看看能不能手动触发。如果能手动触发但自动触发不行那就是 description 或者 trigger 词写得不够准确。第三步确认 skill 内容是否被正确解析。有时候 skill 被加载了但内容格式有问题导致 AI 理解不了。检查 markdown 格式是否正确有没有未闭合的代码块有没有特殊字符导致解析失败。第四步确认上下文窗口是否足够。如果你同时加载了太多 skill或者对话历史太长可能导致 skill 内容被截断。这时候需要精简 skill 内容或者开启新的对话。5.2 常见问题速查表问题现象可能原因解决方法skill 列表里找不到路径错误或文件缺失检查目录结构和文件名skill 加载了但不生效触发条件不匹配优化 description增加 trigger 词skill 内容被忽略格式解析失败检查 markdown 语法确保 frontmatter 正确skill 执行结果不稳定指令不够明确增加约束条件使用反例说明多个 skill 冲突优先级或触发重叠调整优先级明确各 skill 的边界skill 更新后不生效缓存问题重启 Claude Code 或清除缓存5.3 避坑经验那些文档里不会写的事坑一不要在 skill 里写太具体的代码。我一开始图省事直接把一段模板代码贴在 skill 里想着 AI 直接复制就行。结果发现它会把模板代码原封不动地输出连里面的示例变量名都不改。正确的做法是描述代码的结构和规则让 AI 根据实际情况生成。坑二skill 的命名要见名知义。我见过有人把 skill 命名为helper、utils这种过两个月自己都忘了是干什么的。建议用{动作}-{对象}的格式比如generate-api、review-pr、fix-lint。坑三不要试图用一个 skill 覆盖所有场景。我试过写一个“万能”的代码生成 skill结果就是什么场景都处理不好。后来拆成了五个小 skill每个针对特定场景效果反而好得多。坑四skill 也需要 code review。团队协作的时候skill 是共享的一个人写错了所有人都会受影响。我们现在的做法是 skill 的修改也要走 PR 流程至少一个人 review 过才能合并。坑五注意 skill 的加载顺序。当多个 skill 同时被触发时加载顺序会影响最终效果。一般来说越具体的 skill 应该越晚加载这样它的指令会覆盖前面更通用的指令。这个顺序可以通过目录命名或者配置项来控制。6. 进阶玩法让 skills 组合出更强的能力6.1 skill 链式调用单个 skill 的能力是有限的但多个 skill 组合起来就能完成复杂的任务。比如“创建一个新功能”这个任务可以拆解成生成数据模型 - 生成 API 接口 - 生成单元测试 - 生成文档。每个环节对应一个 skill按顺序执行。实现链式调用的方式有两种。一种是显式编排你在对话中依次调用各个 skill每一步确认结果后再进行下一步。这种方式可控性强但需要人工介入。另一种是隐式组合你写一个“元 skill”在里面定义好调用链AI 会自动按顺序执行。这种方式效率高但调试起来比较麻烦。我个人的建议是对于关键任务用显式编排确保每一步都符合预期。对于重复性高的常规任务可以用隐式组合来提效。6.2 动态 skill根据项目状态自动调整进阶一点的玩法是让 skill 能够感知项目的当前状态动态调整自己的行为。比如一个“生成数据库迁移”的 skill它可以先检查当前的数据库版本然后根据版本差异生成对应的迁移脚本。实现这个功能需要在 skill 里嵌入一些探测指令比如“先运行alembic current查看当前版本”。AI 会执行这个命令拿到结果后再决定下一步怎么做。这比写死规则的 skill 灵活得多但也要注意安全性不要让 skill 执行危险的操作。6.3 团队协作中的 skill 管理当团队规模超过三五个人之后skill 的管理就需要一些规范了。我们目前的做法是所有 skill 放在项目的.claude/skills/目录下随代码一起版本管理每个 skill 必须有明确的 owner负责维护和更新skill 的修改走 PR 流程至少一人 review每月一次 skill review清理过时的补充新踩的坑新成员入职第一周要求阅读所有 skill 并尝试写一个自己的 skill这套流程跑下来效果还是很明显的。新人的上手时间从原来的两周缩短到了三天代码 review 中因为规范问题被打回的次数也少了很多。7. 我个人的一些体会写了这么多最后说几句掏心窝子的话。skills 这个东西本质上是在做一件事把隐性的团队知识显性化。以前这些知识散落在各种文档、口口相传、甚至某个老员工的脑子里现在你把它们固化下来变成 AI 能理解、能执行的指令。这件事的价值不在于让 AI 多干了多少活而在于让团队的每一个成员包括新人和 AI都能按照同一套标准来做事。标准统一了沟通成本就降下来了返工就少了整体效率自然就上去了。我刚开始写 skill 的时候总想着写得大而全恨不得把所有情况都覆盖到。后来发现好的 skill 都是从小处着手的。先解决一个具体的、高频的、容易出错的问题跑通了再慢慢扩展。一个能稳定运行的简单 skill比十个花哨但不可靠的 skill 有价值得多。另外不要指望 AI 能 100% 按照你的 skill 来执行。它有时候会“自作主张”有时候会“理解偏差”。这很正常毕竟它不是 deterministic 的程序。你要做的是通过不断的反馈和调整让它的准确率从 70% 提到 85%再到 95%。每提高一个百分点你省下的时间都是实实在在的。最后分享一个小技巧每次 AI 没有按照 skill 执行的时候不要只是重新说一遍而是想一想“为什么它没理解”。往往是因为你的指令有歧义或者缺少了某个关键上下文。把这个原因补进 skill 里下次它就不会再犯同样的错误了。这个过程本身就是在把你的经验沉淀成可复用的资产。