AI Agent技能包skills实战：从设计原理到Claude Code与Codex开发指南

1. 从“skills”这个热词说起它到底是什么为什么突然火了如果你最近在AI编程工具圈子里混一定绕不开“skills”这个词。不管是Claude Code、Codex还是各种agents框架skills几乎成了标配概念。但很多人第一次听到这个词是懵的——它跟插件plugin有什么区别跟普通的函数调用有什么不同为什么大家都在讨论“skills推荐”“好用的skills”“skills开发”我最初接触skills是在折腾Claude Code的时候。当时想让AI帮我处理一些重复性的代码审查工作单纯靠prompt写来写去每次都要重新描述一遍规则效率极低。后来发现skills这套机制可以把一套固定的指令、工具调用逻辑、上下文约束打包成一个可复用的单元AI在需要的时候自动加载不需要的时候不占用上下文窗口。这个设计思路一下子就解决了我之前的痛点。简单来说skills就是给AI agent用的“技能包”。一个skill通常包含一段描述告诉AI这个技能是干什么的、什么时候该用、一套指令具体怎么执行、以及可选的工具或脚本执行时需要调用的外部能力。它跟传统plugin最大的区别在于plugin是给开发者用的扩展机制需要写代码注册、处理生命周期而skills更像是给AI看的“操作手册”用自然语言描述加上少量结构化配置就能定义AI自己决定什么时候加载、怎么组合使用。这个区别很关键。传统plugin的开发门槛高你得懂宿主应用的API、事件模型、状态管理skills的门槛低很多一个懂业务逻辑但不太会写代码的人也能写出一份高质量的skill描述。这就解释了为什么“skills开发”和“skills推荐”会成为热词——它把AI能力的扩展权从纯技术人员手里部分转移到了领域专家手里。适合谁来了解这个内容三类人最应该关注一是日常使用Claude Code、Codex这类AI编程工具的开发者学会写skills能大幅提升效率二是做AI agent产品的工程师理解skills机制有助于设计更好的agent架构三是对AI工作流感兴趣的产品经理或技术管理者skills代表了一种“轻量级能力封装”的思路值得借鉴到自己的业务里。接下来我会从设计思路、核心机制、实操步骤、常见问题几个维度把skills这套东西拆开讲清楚。内容会涉及Claude Code和Codex两个主流平台的具体用法也会补充一些通用的agent skills设计原则。不管你是刚听说这个词的新手还是已经用过几个现成skills想自己动手写的老手应该都能找到有用的部分。2. skills的核心设计思路为什么是“技能包”而不是“插件”2.1 从prompt工程到skill工程的演进逻辑早期用AI编程工具大家都是把指令写在prompt里。比如“你是一个资深Python开发者请按照PEP8规范审查以下代码重点关注命名规范和异常处理”。这种方式的问题很明显每次对话都要重复写稍微复杂一点的规则就写得很长而且不同项目之间的规则无法复用。后来有人想到把常用指令存成模板用的时候粘贴进去。这算是skill的雏形但还是很原始——模板是静态的AI不知道什么时候该主动使用也不会根据上下文自动调整。真正的转折点是agent架构的成熟。当AI不再只是被动回答问题而是能主动调用工具、执行多步任务时“什么时候用什么能力”就成了核心问题。如果把所有能力都塞进系统prompt上下文窗口很快就被撑爆如果让AI自己从零开始推理每一步效率和准确性都不可控。skills机制的本质是把“能力”从“推理”中解耦出来。AI的推理能力负责判断当前任务需要什么技能然后加载对应的skill包按照里面预定义的流程执行。这样既保留了AI的灵活性又保证了关键操作的稳定性和一致性。打个比方以前的prompt工程像是每次做饭都从洗菜切菜开始教厨师skills机制像是给厨师一本菜谱告诉他“做川菜的时候翻到第3章”厨师只需要专注火候和调味就行。2.2 skill与plugin、function call的本质区别很多人把skills和plugin混为一谈其实三者的定位完全不同。我用一个表格来对比维度PluginFunction CallSkill面向对象开发者开发者AI agent定义方式代码注册、API对接JSON schema描述自然语言结构化配置加载时机应用启动时注册模型推理时决定agent根据任务上下文动态加载上下文占用常驻内存按需传入按需加载用完可释放开发门槛高需懂宿主API中需懂schema设计低懂业务逻辑即可复用范围同一应用内同一模型内跨agent、跨平台可移植这个对比能看出skills的独特价值它是唯一一个“写给AI看”的扩展机制。plugin和function call都是写给机器执行的需要严格的格式和错误处理skill是写给AI理解的允许一定的模糊性和自然语言描述AI会自己补全细节。举个例子一个“代码审查”的skill可以这样描述“当用户要求审查代码时按以下优先级检查1. 安全漏洞SQL注入、XSS等2. 逻辑错误边界条件、空指针3. 性能问题N1查询、不必要的循环4. 代码风格。每个问题给出具体行号和修改建议。”这段描述人类读起来很自然AI也能准确理解并执行。如果换成plugin你得写一堆if-else来判断什么时候触发、怎么解析代码、怎么生成报告。2.3 为什么Claude Code和Codex都选择了skills路线Claude Code和Codex虽然底层模型不同但在扩展机制上都选择了skills路线这不是巧合。第一个原因是agent场景的复杂性。编程任务千变万化不可能预先定义所有可能的操作。如果靠plugin来扩展每加一个功能都要发版、审核、用户更新周期太长。skills允许用户自己写、自己用甚至社区共享扩展速度是指数级的。第二个原因是上下文管理的需要。编程agent的上下文窗口很宝贵系统prompt、对话历史、代码文件、工具定义都在抢空间。skills按需加载的机制让agent只在需要某个技能时才把相关描述读进来用完就释放大大节省了上下文。第三个原因是AI能力的进化。早期的模型理解自然语言指令的能力有限必须用结构化格式。现在的模型对自然语言的理解已经足够好用自然语言描述技能反而比写代码更高效、更灵活。Claude Code的skills文档里明确说了skill的描述部分就是给模型看的模型会根据描述判断是否加载。注意虽然skills门槛低但不代表可以随便写。描述模糊的skill会导致agent误加载或加载后执行偏差后面我会专门讲怎么写好skill描述。3. Claude Code中skills的完整实操流程3.1 环境准备与Claude Code安装在讲skills之前先把Claude Code跑起来。Claude Code是Anthropic推出的命令行AI编程工具支持macOS、Linux和Windows通过WSL。安装方式有几种我推荐用官方脚本最省心。macOS和Linux下打开终端执行curl -fsSL https://claude.ai/install.sh | shWindows用户建议先在WSL2里装Ubuntu然后按Linux的方式安装。原生Windows支持还在完善中WSL下体验更稳定。安装完成后运行claude命令会提示你登录。如果你有Claude的订阅账号直接浏览器授权即可。如果没有也可以用API key的方式在环境变量里设置ANTHROPIC_API_KEY。登录成功后进入你的项目目录运行claude就会启动交互式会话。第一次启动会问你是否信任当前目录选yes。然后你就可以用自然语言让它帮你写代码、改bug、审查代码了。提示国内用户如果遇到网络问题导致安装脚本下载失败可以手动下载安装包。具体方法这里不展开核心是确保claude命令能在终端里正常运行。3.2 skills的目录结构与加载机制Claude Code的skills放在特定目录下启动时会自动扫描。默认位置是项目根目录的.claude/skills/也可以放在用户主目录的~/.claude/skills/下作为全局skill。每个skill是一个独立的文件夹文件夹名就是skill的标识符。文件夹里至少有一个SKILL.md文件这是skill的核心描述文件。还可以放其他辅助文件比如脚本、模板、示例代码等。目录结构大概长这样.claude/ skills/ code-review/ SKILL.md templates/ review-template.md commit-message/ SKILL.md test-generator/ SKILL.md examples/ sample-test.py加载机制是这样的Claude Code启动时会扫描skills目录读取每个SKILL.md的元数据部分通常是文件开头的frontmatter把skill的名称和简短描述加载到agent的“技能索引”里。当对话进行到某个节点agent判断当前任务需要某个技能时才会把完整的SKILL.md内容读入上下文然后按照里面的指令执行。这个“索引按需加载”的设计很巧妙。假设你有50个skill每个完整描述2000字如果全部加载就是10万字上下文直接爆了。但索引只加载名称和一句话描述50个skill也就几千字完全可控。真正用到的可能就一两个加载进来也就几千字。3.3 手把手写第一个skill代码审查助手光说理论没意思直接动手写一个。我们就以“代码审查”为例创建一个skill。首先在项目根目录创建目录结构mkdir -p .claude/skills/code-review然后创建SKILL.md文件内容如下--- name: code-review description: 当用户要求审查代码、检查代码质量、或提交代码前需要review时使用。适用于Python、JavaScript、TypeScript、Java等主流语言。 --- # 代码审查技能 ## 审查优先级 按以下顺序检查代码高优先级问题必须报告低优先级问题酌情报告 1. **安全漏洞**必须报告 - SQL注入检查是否有字符串拼接SQL - XSS检查是否有未转义的用户输入直接输出到HTML - 敏感信息泄露检查是否有硬编码的密码、密钥、token - 权限校验缺失检查敏感操作是否有权限验证 2. **逻辑错误**必须报告 - 边界条件数组越界、空指针、除零 - 并发问题竞态条件、死锁风险 - 资源泄漏未关闭的文件、数据库连接、网络连接 - 异常处理是否有吞异常、异常范围过大 3. **性能问题**建议报告 - N1查询循环内查询数据库 - 不必要的循环可以用内置函数替代的手写循环 - 内存问题大对象未释放、缓存未设上限 4. **代码风格**酌情报告 - 命名规范变量、函数、类名是否符合语言惯例 - 注释复杂逻辑是否有注释 - 重复代码是否有可以抽取的重复逻辑 ## 输出格式 对每个问题按以下格式输出 - **文件**: 文件路径 - **行号**: 具体行号 - **严重程度**: 高/中/低 - **问题描述**: 一句话说明问题 - **修改建议**: 具体的修改代码或思路 ## 注意事项 - 不要报告纯格式问题如空格、换行除非项目有明确的lint规则 - 如果代码整体质量很好也要给出肯定不要只挑毛病 - 对于不确定的问题标注“疑似”并说明原因写完之后重启Claude Code或者运行/skills reload如果支持的话然后试着让它审查一段代码。比如你贴一段有SQL注入风险的Python代码它应该会自动加载这个skill按照你定义的优先级和格式来审查。3.4 skill描述文件的编写要点与避坑指南写完第一个skill后你可能会发现效果不太稳定——有时候agent不加载有时候加载了但执行偏差。问题通常出在描述文件的编写上。我踩过几次坑之后总结了几个关键点。description字段要精准触发。这个字段是agent判断是否加载skill的唯一依据。写得太宽泛比如“用于代码相关任务”会导致agent在几乎所有编程场景都加载它浪费上下文写得太窄比如“用于审查Python代码中的SQL注入问题”又会导致很多该用的时候不用。好的description应该覆盖主要触发场景同时排除明显不相关的场景。上面例子里的“当用户要求审查代码、检查代码质量、或提交代码前需要review时使用”就是一个比较平衡的写法。指令要具体可执行。不要写“检查代码质量”这种模糊指令要写“检查是否有字符串拼接SQL”“检查数组访问是否越界”。agent需要明确的检查项越具体执行越稳定。优先级要明确。如果所有问题都标“必须报告”agent会陷入细节把大量低优先级问题也报出来噪音太大。用“必须/建议/酌情”三级来区分让agent知道什么该重点说、什么可以略过。输出格式要固定。指定输出格式能让结果更规整方便后续处理。上面例子里的“文件-行号-严重程度-问题描述-修改建议”五段式读起来清晰也方便复制到issue跟踪系统里。控制篇幅。SKILL.md不要写太长控制在2000字以内。太长的skill会占用大量上下文而且agent可能读到后面忘了前面。如果内容确实多拆成多个skill或者把详细内容放到辅助文件里在SKILL.md里引用。实操心得我一开始写skill喜欢把所有想到的规则都塞进去结果agent执行时经常“选择性遗忘”后面的规则。后来把skill拆小每个skill只做一件事执行稳定性大幅提升。一个skill解决一个问题这是最重要的原则。4. Codex中的skills机制与跨平台实践4.1 Codex skills的配置方式与Claude Code的差异Codex是OpenAI推出的编程agent它的skills机制跟Claude Code思路类似但具体实现有差异。Codex的skills通常放在项目根目录的.codex/skills/下文件格式也是Markdown但frontmatter的字段名和加载逻辑略有不同。Codex的skill描述文件里除了name和description还支持triggers字段可以列出具体的触发词或触发模式。比如--- name: test-generator description: 生成单元测试 triggers: - 写测试 - 生成测试 - unit test - pytest ---这样配置后当用户输入包含这些触发词时Codex会更积极地加载这个skill。Claude Code目前主要靠description的语义匹配没有显式的triggers字段但实际效果差不多因为现代模型的语义理解能力已经很强了。另一个差异是Codex支持skill的“继承”机制。你可以定义一个base skill包含通用的指令和工具然后其他skill继承它只覆盖差异部分。这在写多个相似skill时能减少重复。Claude Code目前没有这个机制每个skill都是独立的。4.2 跨平台skill的兼容性设计如果你同时用Claude Code和Codex肯定希望skill能复用。虽然两者格式有差异但核心内容指令部分是通用的。我的做法是维护一份“源skill”然后用脚本生成两个平台的版本。具体来说源skill用纯Markdown写不包含平台特定的frontmatter。然后写一个简单的转换脚本读取源文件根据目标平台生成对应的frontmatter输出到对应目录。这样改一处两个平台都能更新。转换脚本用Python写大概是这样import re from pathlib import Path def convert_skill(source_path, target_platform): content Path(source_path).read_text() # 提取标题作为name title_match re.search(r^#\s(.)$, content, re.MULTILINE) name title_match.group(1).strip().lower().replace( , -) if title_match else unnamed # 提取第一段作为description desc_match re.search(r^#\s.\n(.?)(?:\n\n|\n#), content, re.DOTALL) description desc_match.group(1).strip() if desc_match else if target_platform claude: frontmatter f---\nname: {name}\ndescription: {description}\n---\n\n output_dir Path(.claude/skills) / name elif target_platform codex: frontmatter f---\nname: {name}\ndescription: {description}\ntriggers: []\n---\n\n output_dir Path(.codex/skills) / name output_dir.mkdir(parentsTrue, exist_okTrue) (output_dir / SKILL.md).write_text(frontmatter content) # 使用示例 convert_skill(skills-src/code-review.md, claude) convert_skill(skills-src/code-review.md, codex)这个脚本很简单但能省去手动维护两份文件的麻烦。实际用的时候可以根据需要加更多转换逻辑比如处理平台特定的工具调用语法。4.3 用skills串联多步骤工作流单个skill解决单个问题但实际工作中往往需要多个skill配合。比如“提交代码”这个场景可能涉及代码审查、生成commit message、运行测试、创建PR。如果每个步骤都手动触发效率不高。我的做法是写一个“工作流skill”它本身不执行具体操作而是定义步骤顺序和条件然后调用其他skill。比如--- name: pre-commit-workflow description: 提交代码前的完整检查流程包括代码审查、测试生成、commit message生成 --- # 提交前工作流 当用户要求提交代码时按以下顺序执行 1. 加载 code-review skill审查暂存区的代码变更 2. 如果审查发现高严重程度问题停止流程并报告 3. 加载 test-generator skill为新增或修改的函数生成单元测试 4. 运行测试如果失败则停止并报告 5. 加载 commit-message skill根据变更内容生成commit message 6. 输出最终的commit message和变更摘要等待用户确认 ## 注意事项 - 每一步完成后简要报告结果不要静默执行 - 如果任何一步失败给出明确的错误信息和修复建议 - 用户确认前不要实际执行git commit这个工作流skill把多个单点skill串起来形成了一个完整的“提交前检查”流程。agent加载这个skill后会按照定义的顺序依次调用其他skill中间不需要用户干预。这种“编排型skill”是skills机制的高级用法。它让agent的行为更可控也更容易复用。你可以为不同的场景定义不同的工作流比如“新功能开发流程”“bug修复流程”“代码重构流程”等。注意编排型skill依赖其他skill的存在部署时要确保依赖的skill都已安装。可以在skill描述里注明依赖关系方便排查问题。5. skills开发中的常见问题与排查技巧5.1 skill不加载或加载错误的排查思路这是最常见的问题。你写了一个skill但agent就是不用或者该用A的时候用了B。排查思路按以下顺序来第一步检查文件位置和命名。确认SKILL.md在正确的目录下文件夹名和name字段一致。Claude Code对大小写敏感Code-Review和code-review可能被当成两个不同的skill。第二步检查frontmatter格式。YAML格式对缩进和冒号很敏感。name: code-review是对的name:code-review冒号后没空格可能解析失败。description如果有多行要用|或符号。第三步测试description的触发效果。在对话里输入明显应该触发skill的请求看agent是否加载。如果不加载说明description的语义匹配有问题换更直白的表述。如果加载了但不该加载的时候也加载说明description太宽泛加限定条件。第四步检查skill内容是否被截断。如果SKILL.md太长agent可能只读了前面一部分。把核心指令放在文件前三分之一的位置详细说明放后面。第五步看agent的调试输出。Claude Code和Codex都支持某种形式的调试日志能看到agent加载了哪些skill、为什么加载。开启调试模式通常是--debug或环境变量可以看到详细的决策过程。5.2 skill执行结果不稳定的原因与对策有时候skill加载了但执行结果时好时坏。同一个skill同样的输入两次运行结果不一样。这通常不是skill本身的问题而是agent的推理随机性导致的。对策有几个。一是把指令写得更具体减少agent的自由发挥空间。比如“检查安全问题”改成“检查以下五类安全问题SQL注入、XSS、CSRF、敏感信息泄露、权限缺失”。二是给出示例输入输出让agent有参照。在SKILL.md里加一个“示例”章节展示一个完整的执行案例。三是用temperature参数控制随机性如果平台支持的话把temperature调低。还有一个容易被忽视的原因skill之间的干扰。如果同时加载了多个skill它们的指令可能冲突。比如skill A说“输出用JSON格式”skill B说“输出用Markdown表格”agent就懵了。解决方法是明确skill的适用范围避免功能重叠。如果确实需要多个skill配合用编排型skill显式定义顺序和优先级。5.3 常见问题速查表问题现象可能原因排查方法解决方案skill完全不加载文件位置错误检查目录结构放到正确的skills目录下skill完全不加载frontmatter格式错误用YAML校验工具检查修正缩进和冒号空格skill完全不加载description太窄换更宽泛的触发词测试调整description覆盖主要场景skill不该加载时加载description太宽看哪些不相关请求触发了加限定条件排除不相关场景skill加载但执行偏差指令模糊对比实际输出和预期把指令改具体加示例skill执行结果不稳定agent随机性多次运行对比降低temperature加示例多个skill冲突指令矛盾看同时加载了哪些skill拆分skill用编排型skill协调skill内容被截断文件太长检查agent读了多少精简内容核心前置5.4 独家避坑经验分享说几个我踩过的坑都是文档里不会写的。坑一skill名用中文。我一开始觉得中文名直观写了个“代码审查”的skill。结果在某些终端环境下中文文件夹名导致路径解析出错skill死活加载不了。后来全部改成英文短横线命名问题消失。建议skill名只用小写字母、数字和短横线。坑二在skill里写死文件路径。我写过一个skill里面写了“读取./src/config.py文件”。结果换了个项目路径不对skill直接报错。后来改成“读取项目中的配置文件通常在src目录下”让agent自己找兼容性好很多。坑三skill依赖特定工具版本。有个skill里调用了某个命令行工具我本地是v2版本语法是tool --input file。同事的机器上是v1版本语法是tool -i file执行就失败了。后来在skill里加了版本检测逻辑或者用更通用的调用方式。坑四忘了处理空输入。写了个“生成commit message”的skill假设用户一定有暂存的变更。结果有一次用户没有暂存任何东西就触发了agent拿着空diff去生成message输出了一堆废话。后来在skill开头加了检查“如果暂存区为空提示用户先暂存变更不要继续执行。”坑五skill之间循环调用。写了个工作流skill A里面调用了skill Bskill B里又调用了skill A。结果agent陷入死循环一直加载来加载去。后来规定skill不能互相调用只能由工作流skill单向调用功能skill问题解决。这些坑的共同点是在单一场景下测试没问题换环境或换输入就出问题。所以写完skill后一定要用不同的项目、不同的输入多测几次确保鲁棒性。6. skills的进阶用法与生态展望6.1 用skills封装团队规范与最佳实践skills最被低估的用法是把团队的编码规范、审查清单、部署流程封装成skill。新成员加入后不需要读一堆文档直接让AI agent加载对应的skill就能按照团队标准执行任务。比如我们团队有个“API设计规范”的skill里面定义了URL命名规则、HTTP方法使用、错误码格式、分页参数等。写新接口的时候agent会自动加载这个skill生成的代码天然符合规范。代码审查时也加载这个skill检查是否符合规范。这样规范不再是文档里的死条文而是嵌入到工作流里的活约束。类似的还有“数据库迁移规范”“日志格式规范”“安全编码规范”等。每个规范一个skill按需加载。新人上手快老人也不会因为疏忽违反规范。6.2 skill的组合与编排构建复杂agent工作流单个skill是积木组合起来才能搭出复杂的结构。除了前面说的串行工作流还支持条件分支和并行执行。条件分支的例子一个“bug修复”skill先判断bug类型。如果是语法错误走快速修复流程如果是逻辑错误走详细分析流程如果是性能问题走 profiling 流程。在SKILL.md里用自然语言描述这些条件分支agent会自己判断走哪条路。并行执行的例子一个“代码审查”skill同时检查安全、性能、风格三个维度最后汇总报告。可以写成三个子skill并行执行也可以在一个skill里让agent同时考虑三个方面。实际测试下来并行执行的速度更快但汇总时需要注意去重和优先级排序。编排的关键是定义清晰的接口。每个skill的输入是什么、输出是什么、失败时怎么处理都要在skill描述里写清楚。这样组合的时候才不会乱。6.3 skills生态的现状与个人开发者的机会目前skills生态还处于早期。Claude Code和Codex都有自己的skill市场或共享机制但内容质量参差不齐。大部分是个人开发者随手写的真正经过打磨、适用于生产环境的skill还不多。这对个人开发者来说是个机会。如果你在某个领域有深厚的经验把它封装成高质量的skill解决一类具体问题很容易获得关注。比如“React性能优化检查”“Django安全审查”“Kubernetes配置审查”这类垂直领域的skill需求明确竞争少。写高质量skill的关键是“窄而深”。不要试图写一个“万能代码助手”skill而是聚焦一个具体场景把每个细节都考虑到。比如“检查React useEffect依赖数组”这个skill就专门检查useEffect的第二个参数是否完整、是否有不必要的依赖、是否应该用useCallback包裹。这种skill虽然小但实用性强用一次就能感受到价值。另外skill的文档和示例很重要。一个skill如果只有指令没有示例使用者不知道效果如何。加上“输入示例”和“输出示例”让人一眼就能看懂这个skill能做什么、怎么做。这比写一堆抽象描述有效得多。6.4 我个人的skill管理习惯最后分享几个我管理skill的个人习惯不一定适合所有人但可以参考。第一skill按项目分目录。全局skill放~/.claude/skills/项目特定的放项目里的.claude/skills/。项目skill优先级高于全局skill同名时项目skill覆盖全局skill。这样通用skill全局共享项目特殊规则项目内定义。第二skill加版本号。在SKILL.md的frontmatter里加version: 1.2.0字段。每次修改skill版本号递增。这样出问题时能快速定位是哪个版本引入的。第三skill写变更日志。在SKILL.md末尾加一个“变更记录”章节记录每次修改的内容和原因。比如“v1.1.0增加对TypeScript的支持”“v1.2.0修复空输入时的报错”。时间长了回头看能理清skill的演进脉络。第四定期清理不用的skill。skill多了之后agent的索引会变长虽然每个索引项很短但积少成多也会占用上下文。每隔一段时间review一下把不再使用的skill删掉或归档。第五skill的测试用例单独存。每个skill配一个测试文件里面放几个典型的输入和预期输出。修改skill后跑一遍测试确保没有回归。这个习惯是从写代码那里迁移过来的对skill同样适用。这些习惯看起来琐碎但坚持下来能省很多事。尤其是版本号和变更日志在排查“为什么昨天还好好的今天就不行了”这类问题时能快速缩小范围。skills这套机制还在快速演进Claude Code和Codex每隔几周就有更新。保持关注官方文档和社区讨论及时了解新特性。但核心思路是不变的把可复用的能力封装成skill让agent按需加载用组合编排解决复杂问题。掌握这个思路不管平台怎么变你都能快速适应。