1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。你随便翻一下热搜词列表就能看到claude code skills、codex skills、agent skills测试、skills推荐、好用的skills、skills开发……一大堆。很多人第一次看到会懵这玩意儿到底是插件是脚本还是某种新的配置文件格式我刚开始接触的时候也绕了不少弯路。简单来说skills 是一套让 AI 编程助手比如 Claude Code、Codex 这类工具具备“可复用专业能力”的机制。你可以把它理解成给 AI 装了一个“技能包”——原本它只会通用地回答问题、写代码装上 skills 之后它就能按照你预设的流程、规范、模板去完成特定任务比如写论文、做代码审查、生成特定格式的文档、执行某个领域的标准操作流程。为什么这个东西突然火了因为大家发现光靠一个通用大模型输出质量太不稳定了。你今天让它写个接口文档它给你写成一坨明天让它按团队规范提交代码它又忘了格式。每次都要重新贴一遍提示词效率极低。skills 的出现本质上是把“提示词工程”升级成了“能力工程”——你不再是一次性写一段 prompt而是定义一个可持久化、可复用、可分享的能力单元。这篇文章我会从零开始把 skills 的核心概念、安装配置、开发方法、实际使用中的坑以及我自己的实操经验全部拆开讲清楚。不管你是刚听说这个词的新手还是已经在用 Claude Code 或 Codex 但还没碰过 skills 的老用户都能从中找到能直接抄作业的内容。提示本文提到的所有工具和操作均基于公开可获取的官方文档和社区实践不涉及任何特殊网络环境配置。2. skills 的核心概念与运行机制拆解2.1 skills 到底是什么从“提示词”到“能力包”的进化要理解 skills先得理解它的前身——提示词prompt。你用 ChatGPT 也好用 Claude 也好每次对话你输入的那段文字就是提示词。提示词的问题是它是临时的、一次性的、不可复用的。你关掉对话窗口它就没了。下次想用同样的能力你得重新写一遍。skills 解决的就是这个问题。它把一段经过验证的、能稳定产出高质量结果的指令集封装成一个结构化的文件或目录。这个封装体里通常包含触发条件什么情况下应该激活这个 skill执行指令具体要 AI 做什么、怎么做、按什么顺序做输入输出规范需要什么参数、产出什么格式示例和边界情况给 AI 参考的样例以及遇到异常时怎么处理你可以把它类比成手机里的“快捷指令”或者“自动化脚本”。原本你要手动点十几步才能完成的操作现在一键触发自动跑完。skills 就是给 AI 编程助手用的“快捷指令”。2.2 为什么 Claude Code 和 Codex 都开始支持 skillsClaude Code 和 Codex 是目前最主流的两款 AI 编程助手一个来自 Anthropic一个来自 OpenAI。它们都支持 skills但实现方式略有不同。Claude Code 的 skills 机制更偏向“文件系统驱动”。你在项目目录下创建一个特定结构的文件夹里面放上SKILL.md或者类似的定义文件Claude Code 在运行时会自动扫描并加载这些 skill。它的优势是跟项目绑定团队共享方便你把 skill 文件提交到代码仓库所有人拉下来就能用。Codex 的 skills 则更偏向“配置驱动”。你需要在配置文件里注册 skill指定它的路径、触发方式、参数等。Codex 的优势是灵活性更高可以跨项目复用也可以从远程仓库拉取 skill 包。两者共同的核心理念是一样的让 AI 的能力从“每次重新教”变成“一次定义到处使用”。这也是为什么热搜里会出现codex好用的skills、claude 国内安装skills 官方市场这类词——大家都在找现成的、别人已经写好的 skill直接拿来用。2.3 skills 与 plugin、agents 的关系和区别热搜词里还有几个相关概念plugin、agents、langchain deep agents。很多人搞不清楚它们之间的区别我在这里一次性说清楚。概念定位与 skills 的关系plugin插件扩展工具本身的功能skills 可以打包成 plugin 分发agents智能体能自主决策和执行任务skills 是 agent 的能力单元skills技能包定义具体任务怎么做核心复用单元prompt一次性指令skills 是 prompt 的结构化升级简单说agent 是“人”skills 是“这个人掌握的技能”plugin 是“装技能的盒子”。一个 agent 可以加载多个 skills每个 skill 定义一项具体能力。你让 agent 去写论文它就调用“论文写作 skill”你让它做代码审查它就调用“代码审查 skill”。理解了这层关系后面配置和开发的时候就不会迷糊了。3. 环境准备Claude Code 与 Codex 的安装配置实操3.1 Claude Code 安装与 skills 目录结构Claude Code 的安装方式根据操作系统不同略有差异。Windows 用户可以通过官方提供的安装包或者包管理器安装macOS 和 Linux 用户通常用命令行安装。安装完成后你需要在项目根目录下创建一个.claude文件夹有些版本是.claude-code然后在里面创建skills子目录。一个标准的 skill 目录结构长这样.claude/ skills/ paper-writing/ SKILL.md examples/ sample-input.md sample-output.md templates/ outline-template.md code-review/ SKILL.md rules/ style-guide.mdSKILL.md是这个 skill 的核心定义文件。它的内容通常包括--- name: paper-writing description: 用于撰写学术论文的 skill支持从大纲到成稿的全流程 trigger: 当用户要求写论文、撰写学术文章时激活 --- ## 执行步骤 1. 先确认论文主题、目标期刊/会议、字数要求 2. 生成三级大纲等待用户确认 3. 按大纲逐节展开每节不少于 500 字 4. 最后统一检查引用格式和术语一致性 ## 输出规范 - 使用学术化表达避免口语 - 引用格式默认使用 APA - 每节末尾附上关键参考文献这个文件就是 skill 的“说明书”。Claude Code 读取它之后就知道在什么情况下激活、按什么步骤执行、产出什么格式。3.2 Codex 安装与 skill 注册流程Codex 的安装相对更“工程化”一些。你需要先安装 Codex CLI 工具然后通过配置文件注册 skill。配置文件通常位于用户主目录下的.codex/config.json或项目目录下的.codex.json。一个典型的 skill 注册配置如下{ skills: [ { name: code-review, path: ./skills/code-review, trigger: review, autoLoad: true }, { name: paper-writing, path: ./skills/paper-writing, trigger: write paper, autoLoad: false } ] }autoLoad: true表示这个 skill 在 Codex 启动时自动加载false表示需要手动触发。trigger是触发关键词当你的指令里包含这个词时Codex 会激活对应的 skill。注意Codex 对配置文件的格式要求比较严格如果你看到codex is ignoring 1 unrecognized configuration setting这类报错通常是因为配置项名称拼写错误或者版本不兼容。建议对照官方文档逐项检查。3.3 常见安装报错与排查思路安装过程中最容易遇到的问题我整理成了下面这张表报错信息可能原因解决方法organization has disabled claude subscription access账号权限问题检查账号类型确认是否支持 Claude Codecc switch local proxy failed本地代理配置冲突检查环境变量中的代理设置临时关闭unrecognized configuration setting配置项拼写错误对照官方文档检查 config 文件plugin version not found插件版本不匹配更新到最新版本或指定兼容版本skill 不生效目录结构错误确认 SKILL.md 路径和文件名正确我踩过最坑的一次是skill 文件明明放对了位置但 Claude Code 就是不加载。排查了半小时才发现SKILL.md的文件名大小写敏感我写成了skill.md系统识别不到。这种细节问题官方文档里往往一笔带过但实际用的时候真的会卡住。4. 开发一个自己的 skill从需求到落地4.1 确定 skill 的边界什么该做什么不该做开发 skill 的第一步不是写代码而是想清楚这个 skill 到底要解决什么问题边界在哪里我见过很多人一上来就想写一个“万能 skill”结果写出来的东西又长又杂AI 执行的时候经常跑偏。正确的做法是一个 skill 只做一件事并且把这件事做到极致。比如“论文写作 skill”它的边界应该是从大纲到成稿的写作流程。它不应该包含“文献检索”“数据分析”“图表制作”这些功能——那些应该拆成独立的 skill。这样做的好处是每个 skill 的逻辑清晰AI 不容易混淆可以单独调试和优化不同 skill 可以组合使用灵活性更高判断边界是否合理的标准很简单如果你不能用一句话说清楚这个 skill 是干什么的那它的边界就太模糊了。4.2 编写 SKILL.md结构、语法与关键字段SKILL.md是 skill 的灵魂。它的结构直接决定了 AI 能不能正确理解和执行。我总结了一个经过实战验证的模板--- name: [skill 名称英文短横线分隔] description: [一句话描述这个 skill 做什么] trigger: [触发条件可以是关键词或场景描述] version: [版本号] author: [作者] --- ## 适用场景 [详细说明什么情况下应该使用这个 skill] ## 前置条件 [执行这个 skill 需要什么输入、什么环境] ## 执行步骤 1. [第一步具体到可操作] 2. [第二步] 3. [第三步] ## 输出规范 [产出物的格式、风格、长度要求] ## 示例 [给一个完整的输入输出示例] ## 异常处理 [遇到什么情况应该怎么处理]这里面有几个关键点trigger 字段要精准。写得太宽泛AI 会在不该激活的时候激活写得太窄该用的时候又用不上。我的经验是用“动作 对象”的组合比如“写论文”“审查代码”“生成接口文档”而不是单独一个“写”或者“文档”。执行步骤要可操作。不要写“分析用户需求”这种模糊的话要写“向用户确认三个信息主题、字数、目标格式”。AI 需要的是明确的指令不是抽象的原则。示例部分不能省。这是很多人容易忽略的。给一个完整的输入输出示例AI 的产出质量会提升一个档次。因为大模型本质上是“模仿学习”你给它看一个样例比写十句描述都管用。4.3 测试与迭代怎么判断一个 skill 好不好用写完 skill 只是开始真正的功夫在测试和迭代。我通常用三个维度来评估一个 skill稳定性同样的输入跑十次产出质量是否一致如果每次结果差异很大说明 skill 的指令不够明确AI 在“自由发挥”。边界清晰度给一个不属于这个 skill 范围的任务它会不会错误激活如果会说明 trigger 写得太宽。产出可用性产出的内容能不能直接用如果需要大量修改说明输出规范没写好。我一般会准备一组测试用例包含正常输入、边界输入、异常输入三类。每次修改 skill 之后跑一遍测试用例看看有没有退化。这个过程跟软件开发里的单元测试是一个道理。实操心得不要追求一次写出完美的 skill。先写一个能用的版本然后在实际使用中不断调整。我自己的“论文写作 skill”迭代了七八个版本才稳定下来前几版经常出现“写着写着跑题”的问题后来在 SKILL.md 里加了“每节写完后回顾大纲”的步骤才解决。5. 实战案例用 skills 完成一个完整任务5.1 案例背景用 skill 写一篇技术论文为了让你更直观地理解 skills 的用法我拿一个真实场景来演示用“论文写作 skill”写一篇关于前端性能优化的技术论文。首先确保 skill 已经正确加载。在 Claude Code 里你可以输入/skills查看当前可用的 skill 列表。如果看到paper-writing在列表里说明加载成功。然后输入触发指令帮我写一篇关于前端性能优化的技术论文目标是一万字的期刊投稿主题聚焦在首屏加载优化策略。Claude Code 识别到“写论文”这个触发词激活paper-writingskill然后按照 SKILL.md 里定义的步骤开始执行。5.2 执行过程拆解每一步发生了什么第一步信息确认。skill 会先跟你确认几个关键信息目标期刊的格式要求、引用风格、是否需要英文摘要。这一步很重要因为不同期刊的要求差异很大提前确认能避免后期大改。第二步大纲生成。skill 会根据你给的主题生成三级大纲。比如1. 引言 1.1 前端性能优化的背景与意义 1.2 首屏加载的核心指标 1.3 本文的研究范围与贡献 2. 首屏加载的性能瓶颈分析 2.1 资源加载瓶颈 2.2 渲染阻塞瓶颈 2.3 网络传输瓶颈 3. 优化策略 3.1 资源压缩与合并 3.2 懒加载与预加载 3.3 服务端渲染与静态生成 3.4 CDN 与缓存策略 4. 实验与结果分析 5. 结论与展望大纲生成后skill 会暂停等你确认。这一步是必须的因为大纲决定了整篇论文的结构如果方向不对后面写得再好也是白费。第三步逐节展开。确认大纲后skill 会按节展开内容。每一节写完后它会自动检查是否偏离大纲、字数是否达标、术语是否一致。如果发现问题会主动修正。第四步统一检查。全文写完后skill 会做一次通篇检查引用格式是否统一、图表编号是否连续、摘要和结论是否呼应。这一步是人工写作时最容易忽略的但 skill 可以自动化完成。5.3 产出效果与人工对比我用同一个主题做过对比测试一次用 skill一次纯手动写。结果如下对比维度手动写作使用 skill大纲耗时约 40 分钟约 3 分钟初稿耗时约 6 小时约 40 分钟格式一致性需要反复检查自动统一术语一致性容易前后不一致自动校验内容深度取决于个人状态稳定输出修改轮次平均 3-4 轮平均 1-2 轮当然skill 产出的内容不是完美的仍然需要人工润色和补充专业细节。但它的价值在于把重复性的、规范性的工作自动化了让你可以把精力集中在真正需要创造力的部分。6. 常见问题与避坑指南6.1 skill 不生效的排查清单这是被问得最多的问题。我整理了一个排查清单按顺序检查文件路径是否正确确认SKILL.md在正确的目录下文件名大小写是否匹配配置文件是否加载检查 Codex 的 config 文件是否被正确读取触发词是否匹配你的指令里是否包含了 skill 定义的 trigger 关键词版本是否兼容skill 的格式是否跟当前工具版本匹配权限是否足够某些 skill 可能需要额外的文件读写权限如果以上都检查了还是不生效可以尝试重启工具或者查看日志文件里的详细报错信息。6.2 skill 输出质量不稳定的优化方法AI 执行 skill 时输出质量波动大通常有三个原因指令不够具体。比如“写一段代码”就太模糊了“用 Python 写一个快速排序函数包含类型注解和单元测试”就具体得多。指令越具体输出越稳定。缺少示例。大模型是模仿学习给它一个高质量的示例它就能照着模仿。没有示例它只能靠猜。步骤之间有歧义。如果 SKILL.md 里的步骤存在多种理解方式AI 每次可能选不同的路径。解决办法是用明确的顺序词先做什么、再做什么、最后做什么。6.3 多个 skill 冲突怎么办当你加载了多个 skill可能会出现冲突两个 skill 的 trigger 有重叠AI 不知道该激活哪个。解决办法有两个方案一调整 trigger 的优先级。在配置文件里给每个 skill 设置优先级高优先级的先匹配。方案二合并相关 skill。如果两个 skill 经常一起使用可以考虑合并成一个更大的 skill用条件分支来处理不同情况。我个人的经验是skill 数量控制在 5-8 个比较合适。太少不够用太多容易冲突而且管理成本高。6.4 团队协作中的 skill 管理如果你在团队里推广 skills有几个实践建议统一存放位置所有 skill 放在项目的.claude/skills目录下提交到代码仓库版本化管理每个 skill 标注版本号重大修改时更新版本文档化每个 skill 配一个简短的 README说明用途和使用方法定期评审每隔一段时间回顾一下现有 skill删掉不再使用的优化效果不好的避坑提示不要把敏感信息如 API 密钥、内部地址写进 skill 文件。skill 文件通常会被提交到代码仓库一旦泄露后果严重。需要敏感配置的用环境变量或者单独的配置文件并加入.gitignore。7. 进阶方向skills 的扩展玩法7.1 skill 组合让多个能力协同工作单个 skill 的能力是有限的但多个 skill 组合起来就能完成复杂的任务链。比如需求分析 skill→架构设计 skill→代码生成 skill→测试用例 skill→文档生成 skill这条链走下来基本上覆盖了一个完整的开发流程。每个 skill 负责一个环节输出作为下一个 skill 的输入。实现组合的方式有两种一种是在 SKILL.md 里显式调用其他 skill另一种是通过 agent 来编排让 agent 根据任务自动选择合适的 skill 组合。7.2 动态 skill根据上下文自动切换高级玩法是让 skill 具备“上下文感知”能力。比如同一个“代码审查 skill”在审查前端代码和后端代码时应用不同的规则集。实现方式是在 SKILL.md 里加入条件判断## 执行步骤 1. 判断代码类型 - 如果是前端代码包含 .vue/.jsx/.tsx加载 frontend-rules.md - 如果是后端代码包含 .py/.go/.java加载 backend-rules.md 2. 按对应规则集执行审查 3. 输出审查报告这样一套 skill 就能覆盖多种场景不用为每种语言单独写一个。7.3 skill 市场与社区资源目前已经有一些社区在维护公开的 skill 集合你可以直接下载使用也可以贡献自己的 skill。搜索skills推荐、好用的skills能找到不少资源。选择社区 skill 的时候注意几点看更新频率长期不更新的 skill 可能跟新版本工具不兼容看文档质量文档写得清楚的通常质量也不会太差看使用反馈有没有人反馈问题作者是否积极回应自己测试下载后先在小项目里测试确认没问题再正式使用8. 我个人的实操体会从第一次听说 skills 到现在我大概用了小半年时间。踩过的坑不少但收获更大。最大的感受是skills 把 AI 从“聊天对象”变成了“工作伙伴”。以前用 AI 编程助手感觉像是在跟一个什么都懂一点但什么都不精的实习生对话现在有了 skills它更像是一个经过培训的、知道团队规范的专业助手。如果让我给刚入门的人一条建议那就是从一个小 skill 开始不要贪多。先写一个最简单的、你每天都要重复做的任务把它封装成 skill。用上一周感受一下效率的变化。然后再逐步扩展把更多任务 skill 化。另外不要指望 skill 一次就写对。我自己的经验是第一版能跑通就不错了真正的优化是在使用过程中慢慢磨出来的。每次遇到输出不理想的情况就回头改一改 SKILL.md加一条规则、补一个示例。改上五六次这个 skill 就变得非常顺手了。最后分享一个小技巧在 SKILL.md 里加一个“自检清单”让 AI 在输出前自己检查一遍。比如“检查字数是否达标、检查引用格式是否统一、检查是否有错别字”。这个简单的步骤能显著提升产出质量亲测有效。
