1. 从“skills”这个热词说起它到底是什么为什么突然火了最近半年不管是在开发者社区还是各种技术群里“skills”这个词出现的频率高得离谱。很多人第一次看到它会以为是某个新出的前端框架或者某个插件市场的名字。其实不是。这里的skills指的是围绕 AI 编程助手尤其是 Claude Code、Codex 这类终端里的智能体构建的一套可复用能力单元。你可以把它理解成给 AI 助手装的“技能包”——每个 skill 就是一段封装好的指令、脚本或者工作流让 AI 在特定场景下知道该怎么做、按什么规范做、调用哪些工具去做。我最早接触这个概念是在折腾 Claude Code 的时候。当时我让它帮我改一个 Flutter 项目的 Gradle 配置结果它给出的方案总是差那么点意思要么漏了 plugin 的声明顺序要么把apply plugin的写法搞混。后来我才意识到问题不在于模型不够聪明而在于它缺少这个项目、这个技术栈的“上下文技能”。于是我开始研究怎么把常用的操作规范、项目约定、工具调用方式沉淀成 skill让 AI 每次都能按我期望的方式来干活。这一研究就停不下来了因为 skills 这套机制一旦用顺效率提升是肉眼可见的。这篇文章我想聊的不是某个官方文档的复述而是我自己从零开始搭建、调试、踩坑、优化 skills 的完整经验。内容包括 skills 的核心设计思路、怎么写出一个好用的 skill、在 Claude Code 和 Codex 里怎么落地、遇到报错怎么排查以及我整理出来的一套常见问题速查表。不管你是刚听说 skills 想入门还是已经在用但总觉得效果不稳定应该都能从里面找到能直接抄作业的东西。提示本文提到的所有操作均基于公开的开发者工具和本地环境配置不涉及任何特殊网络手段。如果你在安装或配置过程中遇到环境问题优先检查本地依赖版本和官方文档的说明。2. skills 的核心设计思路为什么不是简单的提示词2.1 从“一次性提示”到“可复用能力”的转变很多人用 AI 编程助手的方式还是停留在“我问一句它答一句”的阶段。这种方式在简单任务上没问题但一旦任务变复杂比如要改一个多模块项目的构建脚本或者要按团队规范生成一套测试代码纯靠临时提示词就会非常不稳定。原因很简单每次对话都是独立的AI 不知道你上次是怎么做的也不知道你们团队的代码规范是什么。skills 要解决的就是这个问题。它把“怎么做某件事”的知识从一次性的对话里抽出来变成一个持久化的、可被反复调用的能力单元。这个单元里可以包含自然语言指令、示例代码、参数模板、甚至是对外部工具的调用逻辑。当 AI 遇到相关任务时它会自动加载对应的 skill按照里面定义的流程来执行。我打个比方临时提示词就像你每次去一家新餐厅都要跟服务员从头解释你想吃什么、忌口什么、口味偏好如何而 skill 就像你在这家餐厅办了一张会员卡卡里存好了你的所有偏好下次来直接刷卡就行。效率差距不是一点半点。2.2 skills 的组成结构一个 skill 里到底装了什么根据我的实际使用经验一个完整的 skill 通常包含以下几个部分触发条件定义这个 skill 在什么情况下被激活。可以是指令关键词也可以是任务类型比如“当用户要求修改 Gradle 配置时”。执行指令告诉 AI 具体要做什么、按什么顺序做、每一步的输入输出是什么。参考示例给出正确和错误的示例帮助 AI 理解边界。这一步非常关键我后面会详细讲。工具依赖声明这个 skill 需要调用哪些外部命令或工具比如dsh plugin --profile web add dshmarket这类插件管理命令。校验规则定义执行完成后如何验证结果是否正确比如检查某个配置文件是否被正确修改。这五个部分里参考示例和校验规则是最容易被忽略但最重要的。很多人写 skill 只写“你要做什么”不写“做对了长什么样、做错了长什么样”结果 AI 执行出来的东西时好时坏。我的经验是一个好的 skill 里示例代码的篇幅应该占到整个 skill 内容的三分之一以上。2.3 为什么 skills 对 Claude Code 和 Codex 特别重要Claude Code 和 Codex 这类工具的运行环境是终端它们能直接读写文件、执行命令、查看输出。这个能力很强但也意味着一旦出错影响是直接的——可能改坏你的项目文件可能执行了不该执行的命令。skills 在这里起到的作用相当于给 AI 加了一层“操作规范护栏”。举个例子我在用 Codex 接入本地模型比如通过 LM Studio的时候如果没有 skill 约束它可能会尝试用一些不兼容的 API 格式去请求导致cc switch local proxy failed while handling codex endpoint /responses这类报错。后来我写了一个专门的 skill在里面明确规定了本地模型的 endpoint 格式、请求头设置、以及失败后的重试逻辑这个问题就再也没出现过。另外skills 还能解决“组织设置无法加载”这类问题。Codex 在某些环境下会提示codex无法加载组织设置这通常是因为配置文件路径或者权限不对。我在 skill 里加了一段环境检查逻辑让 AI 在执行任务前先确认配置文件是否存在、是否有读权限如果没有就给出明确的修复步骤而不是直接报错退出。3. 动手写第一个 skill从需求拆解到落地3.1 先想清楚这个 skill 要解决什么具体问题写 skill 最忌讳的就是“大而全”。我见过有人试图写一个“万能前端开发 skill”结果里面塞了几百行指令AI 加载后反而不知道该听哪条。正确的做法是一个 skill 只解决一个具体问题问题越具体skill 的效果越好。比如与其写“帮我处理 Flutter 项目的构建问题”不如拆成几个独立的 skillflutter-gradle-plugin-order专门处理 Gradle plugin 声明顺序问题flutter-build-variant-config专门处理构建变体配置flutter-dependency-conflict专门处理依赖冲突排查这样拆的好处是每个 skill 的触发条件清晰执行指令短小精悍AI 不容易混淆。而且当某个 skill 效果不好时你可以单独调试它不会影响其他 skill。3.2 写 skill 的实操步骤以 Gradle 配置为例下面我以“修复 Flutter 项目中 Gradle plugin 声明顺序”这个具体问题为例完整走一遍写 skill 的流程。第一步收集正确和错误的示例。我先在项目里找到一段有问题的 Gradle 配置它长这样// 错误示例plugin 声明顺序不对 apply plugin: com.android.application apply plugin: kotlin-android apply plugin: flutter // 正确示例Flutter 的 plugin 应该在最前面 apply plugin: flutter apply plugin: com.android.application apply plugin: kotlin-android这个顺序问题会导致you are applying flutters main gradle plugin imperatively using the apply s这类警告严重时构建会失败。第二步把问题描述和示例写成 skill 内容。我的 skill 文件大概长这样# Skill: flutter-gradle-plugin-order ## 触发条件 当用户要求修改 Flutter 项目的 build.gradle 文件或者构建时出现 plugin 声明顺序相关警告时激活。 ## 执行指令 1. 读取项目根目录和 android/app 目录下的 build.gradle 文件。 2. 检查 apply plugin 语句的顺序。 3. 确保 apply plugin: flutter 出现在所有其他 plugin 声明之前。 4. 如果顺序不对调整后保存文件。 5. 运行 flutter clean 和 flutter pub get 验证。 ## 正确示例 此处放入上面那段正确代码 ## 错误示例 此处放入上面那段错误代码 ## 校验规则 - 调整后再次读取文件确认 flutter plugin 在第一位。 - 运行构建命令确认没有 plugin 顺序相关警告。第三步在 Claude Code 或 Codex 中注册这个 skill。不同工具的注册方式略有不同。Claude Code 通常是通过配置文件或者项目根目录下的特定文件夹来识别 skill。Codex 则可能需要通过插件机制或者环境变量来加载。我一般会把 skill 文件放在项目根目录的.skills/文件夹下然后在工具的配置里指向这个目录。注意skill 文件的命名要清晰最好用英文小写加连字符避免空格和特殊字符。我踩过一次坑用中文命名 skill 文件结果在某些环境下加载失败排查了半天才发现是编码问题。3.3 让 skill 真正好用的三个细节写完第一个 skill 后我发现效果并没有想象中那么好。AI 有时候会加载 skill有时候不会加载了之后执行结果也时对时错。后来我总结了三个关键细节调整之后效果明显提升。细节一触发条件要写得“窄”而不是“宽”。一开始我把触发条件写成“当用户要求修改 Gradle 文件时”结果 AI 在任何跟 Gradle 相关的任务里都会加载这个 skill包括那些跟 plugin 顺序无关的任务。后来我改成“当用户要求修改 Gradle 文件且任务涉及 plugin 声明或构建警告时”精准度就上来了。细节二执行指令要分步骤每步都有明确的输入输出。不要写“检查并修复 plugin 顺序”这种笼统的指令。要写成“第一步读取文件第二步定位 apply plugin 语句第三步比较顺序第四步调整第五步验证”。每一步都清楚AI 执行起来才不会跳步。细节三校验规则要可执行不能是“确认没问题”这种主观判断。“确认没问题”这种校验等于没校验。要写成具体的命令或检查项比如“运行flutter build apk --debug确认退出码为 0”。这样 AI 才能真的去验证而不是假装验证。4. 在 Claude Code 和 Codex 中落地 skills 的完整流程4.1 Claude Code 的 skills 加载机制与配置要点Claude Code 对 skills 的支持相对成熟它会在启动时扫描指定目录下的 skill 文件并在对话过程中根据触发条件自动加载。我在 Ubuntu 和 Windows 上都配置过流程基本一致但有几个细节需要注意。在 Ubuntu 上我通常把 skill 目录放在~/.claude/skills/下然后在 Claude Code 的配置文件里加上一行指向这个目录。Windows 上则是放在%USERPROFILE%\.claude\skills\。如果你用的是 VS Code 里的 Claude Code 插件配置路径可能会有所不同需要看插件的文档。一个常见的坑是skill 文件写好了但 Claude Code 启动时没有加载。这通常是因为文件权限不对或者目录路径里有中文。我建议 skill 目录和文件名全部用英文权限设置为当前用户可读写。另外Claude Code 在加载 skill 时会解析文件内容如果文件里有语法错误比如 Markdown 格式不对它可能会静默跳过这个 skill。所以写完 skill 后最好用 Markdown 预览工具检查一下格式。4.2 Codex 的 skills 接入方式与本地模型适配Codex 的 skills 机制跟 Claude Code 不太一样它更依赖插件系统。我一般是通过dsh plugin --profile web add dshmarket这类命令来安装和管理插件然后把 skill 作为插件的一部分来加载。Codex 接入本地模型比如通过 LM Studio 提供的本地推理服务时skills 的作用尤其明显。因为本地模型的指令遵循能力通常不如云端大模型如果没有 skill 约束它很容易跑偏。我在 skill 里会明确写出本地模型的 endpoint 格式、请求参数、以及超时重试逻辑。这里有一个我踩过的坑Codex 在请求本地模型时如果 endpoint 配置不对会报cc switch local proxy failed while handling codex endpoint /responses。这个报错的字面意思是代理在处理/responses端点时失败了但实际原因可能是 endpoint 路径写错、端口不对、或者本地服务没启动。我在 skill 里加了一段前置检查让 AI 先确认本地服务是否在运行、端口是否可访问再去发请求这样就能在早期发现问题而不是等到报错。4.3 跨工具通用的 skill 设计原则虽然 Claude Code 和 Codex 的加载机制不同但 skill 的内容设计原则是通用的。我总结了几条指令要短单个 skill 的执行指令最好控制在 20 行以内太长了 AI 容易漏读。示例要全正确示例和错误示例都要有而且错误示例要标注清楚错在哪里。依赖要明skill 里用到的外部命令、环境变量、文件路径都要明确写出来。版本要标如果 skill 是针对特定版本的工具有效的要在文件头部标注版本号避免升级后失效。下面这张表是我整理的 Claude Code 和 Codex 在 skills 支持上的对比方便你根据自己的工具选择配置方式对比项Claude CodeCodexskill 存放位置~/.claude/skills/或项目内.skills/插件目录或通过插件命令注册加载方式启动时扫描对话中自动加载通过插件系统加载触发机制基于关键词和任务类型基于插件激活条件本地模型适配支持需配置 endpoint支持需注意 endpoint 格式常见报错skill 未加载、格式解析失败插件未激活、endpoint 请求失败5. 常见问题与排查技巧实录5.1 skill 不生效的排查思路skill 不生效是最常见的问题表现是 AI 完全没有按照 skill 里的指令执行。我一般按以下顺序排查确认 skill 文件是否被加载在 Claude Code 里可以通过查看启动日志确认在 Codex 里可以通过插件列表确认。检查触发条件是否匹配有时候 skill 加载了但触发条件写得太窄当前任务没有命中。可以临时把触发条件放宽测试是否能激活。检查文件格式Markdown 格式错误、编码问题、特殊字符都可能导致解析失败。用纯文本编辑器打开确认。检查权限文件是否可读目录是否可访问。检查版本兼容性工具升级后skill 的加载机制可能变化需要对照最新文档调整。5.2 常见报错速查表下面这张表是我在实际使用中整理出来的常见报错和对应的排查方向覆盖了 Claude Code、Codex 以及相关插件环境报错信息可能原因排查方向cc switch local proxy failed while handling codex endpoint /responsesendpoint 配置错误或本地服务未启动检查本地模型服务状态、endpoint 路径和端口codex无法加载组织设置配置文件路径错误或权限不足检查配置文件位置、读权限、格式you are applying flutters main gradle plugin imperativelyGradle plugin 声明顺序不对调整 apply plugin 顺序flutter 放最前in order to access this application, you must install the j2se plugin缺少 J2SE 插件依赖安装对应插件版本检查环境变量qt.qpa.plugin: could not find the qt platform plugin windowsQt 平台插件缺失或路径不对检查 Qt 安装、插件路径、环境变量your organization has disabled claude subscription access组织策略限制检查账号权限和组织设置skill 加载后无效果触发条件不匹配或指令不清晰放宽触发条件拆分指令步骤5.3 我踩过的三个典型坑坑一skill 文件里用了中文标点。这个问题看起来很小但影响很大。我在一个 skill 里用了中文的冒号和引号结果 Claude Code 解析时把整段指令当成了一个字符串完全没有按步骤执行。后来全部改成英文标点问题解决。建议写 skill 时全程用英文标点中文只出现在注释和说明文字里。坑二skill 之间互相冲突。我有两个 skill一个负责“修改 Gradle 配置”一个负责“检查构建警告”。结果在一次任务中两个 skill 同时被激活一个让 AI 改配置一个让 AI 先检查再改AI 在两条指令之间来回跳最后什么都没做成。后来我给每个 skill 加了优先级标记并在触发条件里明确互斥关系才解决这个问题。坑三本地模型不支持 skill 里的某些指令格式。我在 skill 里用了一种比较复杂的嵌套列表格式云端模型能正确解析但本地模型通过 LM Studio 加载的解析不了导致 skill 执行到一半就停了。后来我把嵌套列表改成扁平列表本地模型就能正常处理了。如果你也在用本地模型建议 skill 的格式尽量简单避免多层嵌套。5.4 提升 skill 稳定性的几个实操技巧除了上面说的还有几个技巧是我在实际使用中总结出来的能明显提升 skill 的稳定性给 skill 加版本号在文件头部写上version: 1.0每次修改后更新版本号。这样当 skill 行为异常时你能快速确认是不是最近改过。给 skill 加测试用例写一个简单的测试任务每次修改 skill 后跑一遍确认行为符合预期。给 skill 加日志输出在关键步骤让 AI 输出当前执行到哪一步方便排查问题。定期清理不再使用的 skillskill 太多会拖慢加载速度也会增加冲突概率。我一般每个月清理一次。6. 关于 skills 的一些个人体会和后续扩展方向用 skills 这套机制大概半年多最大的感受是它把 AI 编程助手从“一个聪明的聊天对象”变成了“一个能按规范干活的团队成员”。以前我要反复解释需求、纠正错误、检查结果现在很多重复性的任务只要 skill 写好了AI 就能稳定地完成我只需要做最后的审核。当然skills 也不是万能的。它适合处理那些流程明确、规范清晰、重复性高的任务。对于需要大量创造性判断的任务skill 的作用有限还是得靠人来主导。我现在的做法是把日常工作中那些“每次都要跟 AI 解释一遍”的事情写成 skill把精力省下来处理真正需要思考的问题。后续我打算继续扩展的方向有几个一是把更多项目级的规范沉淀成 skill比如代码风格检查、提交信息格式、分支命名规则二是研究怎么让 skill 之间更好地协作比如一个 skill 的输出直接作为另一个 skill 的输入三是把 skill 和 CI 流程结合起来让 AI 在提交代码前自动跑一遍相关 skill 做预检。如果你也在用 Claude Code 或 Codex我建议你从最小的 skill 开始写起不要一上来就搞大而全的。先解决一个你每天都会遇到的具体问题把 skill 写出来、跑通、优化到稳定然后再扩展。这个过程本身就会让你对 AI 编程助手的能力边界有更清晰的认识。