1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是各种开发者群组里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到skills、Claude Code、Codex、agents、plugin、find skills、codex skills、claude agent skills、skills推荐、skills开发……这些词扎堆出现说明一件事围绕 AI 编程助手的能力扩展正在从“模型本身有多强”转向“怎么给模型装上可复用的技能包”。我最早接触这个概念是在折腾 Claude Code 的时候。当时我的理解很朴素不就是给 AI 写一段提示词让它按我的要求干活吗后来踩了几次坑才发现事情没那么简单。你写一段提示词今天能用明天换个项目、换个上下文效果就崩了。问题出在哪出在提示词是“一次性”的而 skills 是“可复用、可组合、可版本管理”的。打个比方。提示词就像你临时给同事口头交代一件事“帮我把这个 Excel 里的重复行删掉然后按日期排序。”同事这次听懂了下次你不在他可能就忘了。而 skills 更像是你写了一份标准作业程序SOP放在团队共享盘里谁需要谁拿去用步骤、参数、注意事项全在里面甚至还能被其他流程调用。这就是 skills 和普通提示词的本质区别。那 skills 具体能做什么我总结下来主要是三件事。第一把重复性的操作固化下来。比如你每次新建一个前端项目都要配置 ESLint、Prettier、TypeScript、路径别名、环境变量这些步骤完全可以写成一个 skill下次一句话调用。第二让 AI 助手的行为更可控。你给 AI 一个 skill它就知道在什么场景下该做什么、不该做什么输出格式也稳定了。第三实现能力的跨工具迁移。你在 Claude Code 里写好的 skill理论上可以适配到 Codex 或其他支持 agents 的工具里不用重复造轮子。适合谁来参考我觉得三类人最需要关注。第一类是日常重度使用 AI 编程助手的开发者你已经在用 Claude Code、Codex 或者类似工具但总觉得每次都要重复交代背景效率上不去。第二类是团队里的技术负责人你想把团队的最佳实践沉淀下来让新人也能快速上手。第三类是对 agent 生态感兴趣的技术爱好者你想搞清楚 skills 的底层逻辑甚至自己开发 skill 分享给别人。接下来我会从设计思路、核心细节、实操过程、常见问题四个维度把 skills 这件事彻底讲透。文章里会涉及 Claude Code、Codex、agents、plugin 这些关键词的具体用法也会分享我自己踩过的坑和总结出来的技巧。不管你是刚听说 skills 的新手还是已经写过几个 skill 的老手应该都能找到对你有用的东西。2. 内容整体设计与思路拆解2.1 为什么是“技能包”而不是“提示词库”很多人第一次接触 skills 的时候会把它理解成“高级一点的提示词”。这个理解不能说错但不够准确。我刚开始也这么想直到我把同一个需求分别用提示词和 skill 实现了一遍才发现两者的设计哲学完全不同。提示词的核心是“描述意图”。你告诉 AI 你想干什么AI 根据它的理解去执行。问题在于AI 的理解是不稳定的。同一个提示词今天跑出来是 A 结果明天可能是 B 结果。你可能会说那我把提示词写详细一点不就行了确实详细提示词能提高稳定性但代价是提示词越来越长维护成本越来越高而且换个模型可能就失效了。skills 的核心是“封装能力”。一个 skill 不仅仅是一段文字它包含了触发条件、执行步骤、输入输出定义、依赖项、错误处理这些结构化信息。你可以把它想象成一个函数给定输入经过确定的处理流程返回输出。AI 助手在遇到匹配的场景时会自动调用这个 skill而不是靠临时理解。我举个例子你就明白了。假设你要让 AI 帮你“把一段 JSON 转成 TypeScript 类型定义”。用提示词的方式你得写“请把下面的 JSON 转换成 TypeScript interface注意嵌套对象要单独定义数组类型要推断元素类型可选字段用问号标记……”每次都要写一遍。而用 skill 的方式你只需要定义一个叫json-to-ts的技能里面写清楚转换规则、边界情况处理、输出格式要求。以后你只要说“用 json-to-ts 处理这段数据”AI 就知道该怎么做。提示skills 和提示词不是替代关系而是互补关系。简单的一次性任务用提示词就够了重复出现、有固定流程、需要稳定输出的任务才值得做成 skill。2.2 主流工具对 skills 的支持现状目前对 skills 支持比较完善的主要是 Claude Code 和 Codex 这两个工具。Claude Code 是 Anthropic 推出的命令行编程助手它有一套自己的 skill 管理机制支持从官方市场安装 skill也支持本地自定义。Codex 是 OpenAI 系的编程助手它的 skills 体系更偏向于“配置驱动”通过配置文件来定义 agent 的行为。除了这两个还有一些工具也在跟进。比如 Cursor 虽然主打的是编辑器集成但它也支持通过规则文件来约束 AI 行为本质上和 skills 的思路是一致的。VS Code 上的 Claude Code 插件也让 skills 的使用门槛降低了不少你不需要在终端里敲命令直接在编辑器里就能调用。这里要特别提一下plugin这个概念。在 Claude Code 的生态里plugin 和 skill 经常一起出现但它们是两个层面的东西。plugin 更像是“功能模块”比如一个 plugin 可能包含多个 skill还可能有自己的配置界面和依赖管理。skill 则是更细粒度的“能力单元”。你可以理解为plugin 是工具箱skill 是工具箱里的具体工具。2.3 方案选型的几个关键考量在实际动手之前有几个选型问题需要想清楚。第一个问题是用官方市场现成的 skill还是自己写我的建议是先逛一圈官方市场看看有没有能直接用的。Claude Code 的官方市场里已经有不少高质量的 skill覆盖了代码审查、文档生成、测试编写、重构建议等常见场景。如果现成的能满足你 80% 的需求就别重复造轮子。剩下 20% 的特殊需求再考虑自己写。第二个问题是skill 的粒度怎么控制太粗了不好复用太细了管理成本高。我的经验是一个 skill 最好只做一件事但这件事要足够完整。比如“生成 React 组件”这个粒度就比较好它包含了文件创建、模板填充、样式引入、导出配置这些步骤但不会把“生成整个页面”也塞进来。如果你发现一个 skill 的描述超过三句话还说不清楚那大概率是粒度太粗了需要拆分。第三个问题是怎么保证 skill 的可移植性如果你只在 Claude Code 里用那问题不大。但如果你同时用 Codex或者以后想换工具就要考虑 skill 的通用性。我的做法是把 skill 的核心逻辑写成与工具无关的文档然后用各工具自己的配置格式去“包装”它。这样即使换工具核心逻辑不用重写。3. 核心细节解析与实操要点3.1 skill 的文件结构与关键字段一个标准的 skill 通常包含这几个部分元信息、触发条件、执行指令、输入输出定义、示例。不同工具的格式略有差异但核心要素是相通的。以 Claude Code 的 skill 为例它通常是一个 Markdown 文件放在特定的目录下。文件开头是 YAML 格式的元信息包括 skill 的名称、描述、版本、作者这些。描述字段特别重要因为 AI 就是靠这个描述来判断什么时候该调用这个 skill 的。我见过很多人写描述写得很随意结果 AI 根本不知道什么时候该用这个 skill 就废了。触发条件可以写得很具体比如“当用户提到 JSON 转 TypeScript 时”也可以写得更抽象比如“当需要处理数据格式转换时”。我的建议是描述要具体但不要过于狭窄。太窄了覆盖场景少太宽了容易误触发。一个技巧是在描述里同时写上“做什么”和“什么时候做”比如“将 JSON 数据转换为 TypeScript 类型定义适用于前端项目初始化或 API 响应类型生成场景”。执行指令部分是 skill 的核心。这里要写清楚每一步做什么遇到分支怎么处理输出格式是什么。我习惯用有序列表来写步骤每一步都尽量具体。比如不要写“处理数据”而要写“遍历 JSON 对象的每个 key判断 value 类型如果是对象则递归处理如果是数组则推断元素类型”。输入输出定义经常被忽略但其实很重要。你定义了输入格式AI 就知道该向用户要什么信息。你定义了输出格式AI 就知道该生成什么样的结果。这能大大减少来回沟通的成本。3.2 触发机制与调用逻辑skill 的触发机制是我觉得最值得深入理解的部分。它不像函数调用那样有明确的调用语句而是靠 AI 根据上下文“判断”是否该用某个 skill。这就带来一个问题AI 怎么知道该用哪个 skill答案在 skill 的描述和 AI 的系统提示里。当你安装了一个 skill它的描述会被注入到 AI 的上下文中。AI 在收到用户请求时会拿请求和所有可用 skill 的描述做匹配找到最合适的那个。所以描述写得好不好直接决定了 skill 能不能被正确触发。我踩过一个坑有一次我写了一个叫code-review的 skill描述写的是“审查代码”。结果我发现 AI 几乎从来不用它即使我明确说“帮我审查一下这段代码”。后来我把描述改成“对指定代码文件进行静态审查检查潜在 bug、代码风格问题和性能隐患输出审查报告”触发率立刻上去了。原因很简单原来的描述太笼统AI 不确定这个 skill 到底能做什么就不敢用。还有一个技巧是在 skill 的描述里加入一些“关键词”。比如你的 skill 是关于 React 组件生成的那就在描述里写上“React、组件、JSX、前端”这些词。这样当用户提到相关概念时AI 更容易联想到你的 skill。注意不要为了让 skill 更容易被触发而把描述写得太宽泛。我见过有人把描述写成“处理所有编程相关任务”结果这个 skill 频繁误触发反而干扰了正常使用。3.3 参数传递与上下文管理skill 在执行过程中往往需要从用户那里获取一些参数。比如一个“生成 API 请求代码”的 skill需要知道请求方法、URL、请求体格式、认证方式这些信息。这些参数怎么传递给 skill是一个需要设计的问题。最简单的方式是让 AI 从对话上下文中提取。用户说“帮我生成一个 GET 请求地址是 /api/users需要 Bearer token”AI 就能从这句话里提取出方法、URL、认证方式。这种方式的好处是自然用户不需要按固定格式输入。坏处是有时候 AI 会漏掉一些参数或者理解错。更可靠的方式是在 skill 里定义明确的参数列表然后让 AI 主动询问缺失的参数。比如 skill 里写“需要以下参数请求方法、URL、请求体可选、认证方式可选。如果用户未提供逐一询问。”这样虽然多几轮对话但参数完整性有保障。上下文管理是另一个容易出问题的地方。skill 在执行时会占用 AI 的上下文窗口。如果你的 skill 特别长或者一次调用了多个 skill上下文可能会不够用。我的经验是尽量把 skill 写得精简把详细的参考文档放在外部文件里需要时再读取。Claude Code 支持在 skill 里引用外部文件这个功能很实用。3.4 版本管理与团队协作当你写了几个 skill 之后版本管理就成了一个问题。今天改了一版明天又改了一版过段时间自己都忘了哪个版本好用。我的做法是把 skill 文件纳入 Git 管理每次修改都写清楚改了什么、为什么改。这样即使改坏了也能回滚。团队协作场景下skill 的共享就更重要了。我们团队的做法是建一个专门的 skill 仓库每个人都可以提交自己的 skill经过 review 后合并到主分支。新同事入职时直接 clone 这个仓库把 skill 安装到自己的环境里就能复用团队积累的能力。这比口头传授或者写文档高效多了。还有一个细节skill 的命名要规范。我见过有人用中文命名 skill结果在某些工具里会出现编码问题。建议统一用英文小写加连字符比如json-to-ts、react-component-gen、api-request-builder。这样跨工具、跨平台都不容易出问题。4. 实操过程与核心环节实现4.1 环境准备Claude Code 与 Codex 的安装配置在开始写 skill 之前得先把工具装好。Claude Code 的安装方式有几种我推荐用官方提供的安装脚本最省事。在终端里执行安装命令后你需要配置 API 密钥或者登录账号。如果你在国内可能会遇到网络问题这个需要自己想办法解决我就不展开说了。安装完成后你可以通过claude --version来验证是否安装成功。然后运行claude进入交互模式看看能不能正常对话。如果一切正常就可以开始配置 skill 了。Codex 的安装稍微不同它更依赖配置文件。你需要先下载 Codex 的安装包然后按照官方文档配置config文件。Codex 的配置项比较多我建议先用默认配置跑通再逐步调整。特别要注意的是Codex 对配置文件的格式要求很严格一个拼写错误就可能导致启动失败。我遇到过codex is ignoring 1 unrecognized configuration setting这个报错排查了半天才发现是某个字段名多了一个字母。如果你同时用 Claude Code 和 Codex可以考虑用cc switch这类工具来管理配置切换。不过这类工具偶尔会出现local proxy failed的问题我的建议是如果遇到代理相关报错先检查网络配置再检查工具版本是否兼容。4.2 从零写一个 skill以“JSON 转 TypeScript”为例下面我带你完整走一遍写 skill 的流程。我们以“JSON 转 TypeScript 类型定义”这个需求为例这个 skill 在前端开发里特别实用尤其是对接后端 API 的时候。第一步确定 skill 的存放位置。Claude Code 默认会从特定目录读取 skill你可以在配置里查看或修改这个路径。我习惯在项目根目录下建一个.claude/skills文件夹把项目相关的 skill 放在这里这样跟着项目走换电脑也不用重新配置。第二步创建 skill 文件。文件名就叫json-to-ts.md内容结构如下。元信息部分名称写json-to-ts描述写“将 JSON 数据转换为 TypeScript 类型定义适用于前端项目对接 API 时生成响应类型”。版本写1.0.0作者写你自己的名字。第三步写执行指令。我一般会分成几个步骤来写。首先是解析输入让 AI 确认用户提供的 JSON 是有效的。然后是递归遍历对每个字段判断类型。接着是生成 TypeScript 代码注意嵌套对象要提取成独立的 interface数组要推断元素类型可选字段要加问号。最后是输出把生成的代码放在代码块里并附上使用说明。第四步定义输入输出。输入就是一个 JSON 字符串或者文件路径。输出是 TypeScript 代码格式要求是每个 interface 单独一段用export导出。第五步写示例。给一个简单的 JSON 输入和对应的 TypeScript 输出这样 AI 能更准确地理解你的意图。示例不用太复杂覆盖主要情况就行。写完之后把文件放到 skill 目录下重启 Claude Code 或者重新加载配置。然后你就可以测试了。输入一段 JSON说“用 json-to-ts 转换一下”看看输出是否符合预期。如果不符合就调整 skill 里的指令直到满意为止。4.3 调试与优化让 skill 真正好用写完 skill 只是第一步调试和优化才是重头戏。我总结了一个“三轮调试法”分享给你。第一轮功能验证。确认 skill 能跑通能产生输出。这一轮不用太在意输出质量先保证流程是通的。如果 AI 根本不触发这个 skill那就是描述的问题回去改描述。如果触发了但输出不对那就是执行指令的问题检查步骤是否清晰。第二轮边界测试。拿一些特殊的输入来测试比如空 JSON、嵌套很深的 JSON、包含特殊字符的 JSON、数组里混合类型的 JSON。看看 skill 能不能正确处理。我就是在这一轮发现原来的 skill 遇到空对象会报错后来加了一个判断才解决。第三轮效率优化。看看 skill 的执行时间、消耗的 token 数、输出的可读性。如果 skill 太长导致上下文不够用就精简指令把详细说明移到外部文件。如果输出格式不够好就调整输出模板。这里分享一个我常用的技巧在 skill 里加入“自检”步骤。比如让 AI 在生成 TypeScript 代码后自己检查一遍是否有语法错误、是否有遗漏的字段、命名是否规范。这个自检步骤能显著提高输出质量而且成本很低。提示调试 skill 时建议开一个专门的测试对话不要在日常工作的对话里调试。这样避免污染上下文也方便你反复测试。4.4 组合多个 skill 完成复杂任务单个 skill 的能力是有限的真正强大的是把多个 skill 组合起来用。比如你要做一个“从 API 文档生成前端请求代码”的任务可以拆成几个 skill一个负责解析 API 文档一个负责生成 TypeScript 类型一个负责生成请求函数一个负责生成 Mock 数据。然后在一个主流程里依次调用这些 skill。Claude Code 支持在 skill 里调用其他 skill这叫做“skill 编排”。你可以在一个 skill 的执行指令里写“调用 json-to-ts 处理响应数据然后调用 api-request-builder 生成请求代码”。AI 会自动按顺序执行。不过要注意skill 编排会增加上下文消耗也更容易出错。我的建议是先从简单的两三个 skill 组合开始跑通了再增加复杂度。另外每个子 skill 的输出格式要统一否则下一个 skill 可能解析不了。Codex 在 skill 编排方面有自己的机制它更偏向于用配置文件定义 agent 的行为链。如果你同时用两个工具可以考虑把核心逻辑写成通用的然后用各自的配置去适配。5. 常见问题与排查技巧实录5.1 skill 不触发或误触发怎么办这是最常见的问题没有之一。我统计了一下我遇到的 skill 问题里大概有六成是触发相关的。不触发的典型表现是你明明说了相关的话但 AI 就是不用你的 skill。原因通常有三个。第一描述写得太笼统AI 不确定这个 skill 是否匹配。解决办法是把描述写具体加入场景关键词。第二skill 没有被正确加载。检查一下文件路径对不对文件格式是否符合要求。第三有多个 skill 的描述相似AI 不知道该选哪个。这时候需要给每个 skill 更独特的描述或者合并相似的 skill。误触发的典型表现是你只是随口提了一句AI 就兴冲冲地调用了 skill结果做了一堆你不需要的事。原因通常是描述写得太宽泛。解决办法是收紧描述加入更明确的触发条件。比如把“处理代码”改成“对指定代码文件进行静态审查并输出报告”。下面这个表格是我整理的触发问题速查表你可以对照排查。问题现象可能原因排查方法解决措施skill 完全不触发文件未加载检查 skill 目录和文件格式确认路径正确重启工具skill 偶尔触发描述不够具体查看 AI 的匹配日志在描述中加入场景关键词skill 频繁误触发描述过于宽泛观察触发时的用户输入收紧描述明确触发条件多个 skill 冲突描述相似度高列出所有 skill 的描述合并或差异化描述5.2 输出格式不稳定的处理思路即使 skill 触发了输出格式也可能不稳定。今天生成的 TypeScript 代码用interface明天可能就用type。今天缩进是两个空格明天变成四个。这种不一致在团队协作里特别让人头疼。我的解决办法是在 skill 里明确指定输出模板。不要只说“生成 TypeScript 代码”而要给出一个具体的模板包括用什么关键字、缩进多少、是否加分号、导出方式是什么。模板越具体输出越稳定。另一个技巧是加入“格式检查”步骤。让 AI 在输出前自己检查一遍格式是否符合要求。这个步骤虽然增加了一点开销但能显著提高一致性。如果格式问题依然存在可以考虑在 skill 里嵌入一个格式化脚本的调用。比如生成代码后自动调用 Prettier 格式化。Claude Code 支持执行 shell 命令这个能力可以用来做后处理。5.3 上下文超限与性能优化skill 用多了之后上下文超限是个绕不开的问题。尤其是当你同时加载了十几个 skill每个 skill 的描述和指令都占用上下文留给实际任务的上下文就少了。我的优化策略是按需加载。不是所有 skill 都需要一直可用。你可以把 skill 分成“常用”和“备用”两类常用的放在默认加载目录备用的放在另一个目录需要时再手动加载。Claude Code 支持这种动态加载机制。另一个策略是精简 skill 内容。把详细的参考文档、示例代码、边界情况说明移到外部文件里skill 本身只保留核心指令和触发条件。需要时让 AI 去读取外部文件。这样 skill 的上下文占用能减少一半以上。还有一个容易被忽略的点是对话历史的管理。长对话会积累大量上下文即使 skill 本身很短对话历史也可能把上下文撑爆。我的习惯是完成一个阶段性任务后开一个新对话把必要的背景信息重新交代一下。虽然麻烦一点但能避免上下文超限导致的性能下降。5.4 跨工具兼容的注意事项如果你同时用 Claude Code 和 Codex或者以后打算换工具跨工具兼容就是个必须考虑的问题。我踩过的坑包括skill 文件格式不兼容、描述字段名称不同、调用语法有差异。我的应对方法是分层设计。把 skill 的核心逻辑写成一份通用的 Markdown 文档不依赖任何特定工具的语法。然后针对每个工具写一个薄的“适配层”把通用文档转换成该工具要求的格式。这样核心逻辑只需要维护一份适配层的工作量很小。另外不同工具对 skill 的触发机制也有差异。Claude Code 更依赖描述匹配Codex 更依赖配置规则。在写通用文档时要把触发条件写得足够清晰这样不管哪个工具都能正确识别。注意跨工具兼容不是必须的。如果你只用 Claude Code那就按 Claude Code 的最佳实践来写不用考虑其他工具。兼容性是有成本的只在真正需要时才做。5.5 安全与权限的边界控制skill 在执行时可能会读写文件、执行命令、访问网络。这些操作如果不受控制可能会带来风险。我建议在 skill 里明确声明它需要哪些权限然后在工具层面做限制。比如一个只负责生成代码的 skill就不应该给它文件写入权限。一个只负责读取配置的 skill就不应该给它网络访问权限。Claude Code 支持在配置里设置权限白名单我强烈建议开启这个功能。另外从官方市场安装 skill 时要看一下它的权限声明。如果一个简单的格式化 skill 要求网络访问权限那就要警惕了。自己写 skill 时也要遵循最小权限原则只申请必要的权限。6. 我个人的实操心得与进阶建议6.1 从“能用”到“好用”的关键跨越写了十几个 skill 之后我最大的体会是skill 的质量不取决于它有多复杂而取决于它有多稳定。一个简单的、每次都能正确执行的 skill比一个功能强大但时灵时不灵的 skill 有价值得多。怎么做到稳定我的经验是三点。第一指令要具体到近乎啰嗦。不要假设 AI 能理解你的意图把每一步都写清楚。第二边界情况要提前处理。空输入、异常输入、超大输入这些都要在 skill 里写明怎么处理。第三输出格式要固定。给一个模板让 AI 照着填不要让它自由发挥。6.2 建立自己的 skill 库我建议每个重度使用 AI 编程助手的人都建立自己的 skill 库。不用一开始就追求大而全从你最常做的任务开始一个一个积累。我最初只有三个 skill代码审查、提交信息生成、JSON 转 TypeScript。后来慢慢增加到十几个覆盖了日常工作的大部分场景。skill 库要定期整理。过时的、不好用的、重复的该删就删。我每季度会花半小时过一遍自己的 skill 库把用不上的清理掉把常用的优化一下。这个习惯让我的 skill 库始终保持精简高效。6.3 关注社区动态与 skill 分享skills 这个领域变化很快新工具、新玩法层出不穷。我建议关注几个渠道Claude Code 的官方市场、GitHub 上的 skill 仓库、技术社区的讨论。看到好的 skill可以下载下来研究一下它的写法往往能学到新的技巧。我自己也从社区里受益很多。有一次看到一个 skill 用了“分步确认”的机制就是每执行一步都让用户确认一下特别适合那些高风险的操作。我把这个思路借鉴到了自己的 skill 里效果很好。6.4 给新手的三个建议如果你刚开始接触 skills我给你三个建议。第一先从用别人的 skill 开始。官方市场里有很多高质量的 skill先拿来用感受一下 skill 能做什么。第二从最简单的 skill 写起。不要一上来就写复杂的编排先写一个只做一件事的 skill跑通了再扩展。第三不要追求完美。skill 是迭代出来的第一版能用就行后面根据实际使用情况慢慢优化。我见过太多人卡在“想写一个完美的 skill”这一步结果什么都没写出来。先写出来再改好这个顺序不能反。6.5 后续可以扩展的方向如果你已经能熟练写 skill 了可以考虑几个进阶方向。一是skill 的自动化测试写一套测试用例每次修改 skill 后自动跑一遍确保没有回归。二是skill 的版本发布把你的 skill 打包分享给团队或社区收集反馈持续改进。三是skill 与 CI/CD 的集成让 skill 在代码提交、构建、部署等环节自动执行。这些方向我自己也在探索中有些已经跑通了有些还在试验。等有成熟的经验了再找机会分享。skills 这个生态还在快速演进现在投入时间学习后面应该会有不错的回报。