1. 从“skills”这个热词说起：它到底在解决什么问题
最近半年，不管是在技术群还是各种开发者社区，“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到：claude code、codex、agents、plugin、skills推荐、codex skills、claude agent skills……这些词几乎绑在一起出现。很多人第一次看到“skills”会以为是某种新框架或者新语言，其实不是。它更像是一种给 AI 编程助手“装技能包”的机制——把一套可复用的指令、工具调用逻辑、上下文约束打包成一个独立单元，让 AI 在特定任务上表现得更像“老手”。
我最早接触这个概念是在折腾claude code的时候。当时想让它在终端里帮我处理一些重复性的代码重构，结果发现默认状态下它虽然能干活，但每次都要重新解释一遍规则，效率很低。后来看到有人提到“skills”，试了一下，发现这东西本质上就是把“你希望 AI 怎么干活”这件事标准化、模块化。你可以把它理解成给 AI 装了一个“职业培训包”：装上前端开发的 skills，它就懂你的组件规范；装上论文写作的 skills，它就知道引用格式和逻辑结构。
这个机制解决的核心痛点很明确：AI 助手的能力是通用的，但你的项目是具体的。通用能力再强，落到你的代码库、你的写作风格、你的工具链上，总差那么一口气。skills 就是补这口气的东西。它适合谁？我觉得三类人最该关注：一是每天用claude code或codex写代码的开发者；二是想用 AI 辅助写作但苦于输出不稳定的内容创作者；三是那些在团队里负责“把 AI 工具落地”的技术负责人。哪怕你只是刚装好claude code的新手，了解 skills 也能让你少走很多弯路。
2. skills 的核心设计思路：为什么不是简单的“提示词模板”
2.1 从“一次性提示”到“可复用技能单元”的转变
很多人第一次听说 skills，会觉得“这不就是提示词模板吗？我写个 system prompt 不就行了”。我一开始也这么想，但实际用下来发现差别很大。普通的提示词模板是扁平的、静态的，你写一段话，AI 照着执行。而 skills 是结构化的、带元信息的，它通常包含几个关键部分：技能名称、适用场景描述、依赖的工具或插件、执行步骤、输出格式约束，甚至还有版本号和作者信息。
这种结构带来的直接好处是可发现性和可组合性。你可以像逛应用商店一样浏览别人写好的 skills，找到适合自己场景的直接装。比如热搜里提到的find skills、skills推荐、claude 国内安装skills 官方市场，这些词反映的就是大家在找“哪里能拿到好用的技能包”。而skills开发、codex skills、claude agent skills则说明另一拨人已经在写自己的技能包了。
我个人的判断是：skills 的真正价值不在于“省了几行提示词”，而在于它把 AI 协作的经验沉淀成了可传播的资产。你团队里那个最懂代码规范的人，可以把他的经验写成一个 skill，然后全组共用。这比口口相传或者写文档靠谱得多。
2.2 为什么 skills 和 agents、plugin 总是绑在一起
看热词列表会发现，agents、plugin、skills这三个词几乎形影不离。这不是巧合。从架构上看，它们解决的是不同层次的问题：
- agents是“执行者”，负责决定什么时候调用什么能力；
- plugin是“工具箱”，提供具体的功能接口，比如读写文件、发请求、查数据库；
- skills是“操作手册”，告诉 agent 在什么场景下该用哪个 plugin、按什么顺序用、注意什么坑。
打个比方：agent 是一个新来的员工，plugin 是办公室里的各种设备，skills 就是老员工留下的“设备使用指南和避坑手册”。没有 skills，agent 也能干活，但容易乱来；有了 skills，它就知道“打印文件之前先检查纸张”“导出数据要用 CSV 而不是 Excel”。这也是为什么claude code和codex都在大力推 skills 机制——它们想让自己的 agent 更可靠。
2.3 本地化与跨平台：skills 的部署形态
热搜里还有几个词很值得注意：claude code 调用lmstudio的本地模型、ubuntu配置claude code、claude code windows、vscode配置claude code。这说明大家关心的不只是 skills 本身，还有在什么环境里跑。skills 通常是跟着宿主工具走的，claude code装在 Ubuntu 上、Windows 上、或者作为 VS Code 插件跑，skills 的加载路径和生效方式可能不一样。
我实测下来，比较稳妥的做法是：先把宿主工具装好、跑通，再考虑 skills 的安装和开发。很多人一上来就折腾 skills，结果claude code本身都没配置好，自然各种报错。另外，如果你用的是本地模型（比如通过 LM Studio 加载的模型），skills 的兼容性需要额外验证，因为不同模型对指令格式的敏感度差异很大。
3. 核心细节解析：一个 skill 到底长什么样
3.1 skill 的典型结构拆解
虽然不同平台对 skill 的格式定义略有差异，但核心要素是相通的。我拿一个“前端组件代码审查”的 skill 举例，它通常包含以下部分：
- 元信息：名称、版本、作者、适用工具（比如
claude code或codex）； - 触发条件：什么情况下激活这个 skill，比如“当用户要求审查 React 组件时”；
- 前置检查：执行前需要确认什么，比如“确认项目使用 TypeScript”；
- 执行步骤：分步骤描述操作流程，每一步可能调用不同的 plugin；
- 输出规范：结果以什么格式呈现，比如“按严重程度分组，每条附上修改建议”；
- 边界与禁忌：明确不能做什么，比如“不要自动修改文件，只给建议”。
这种结构的精髓在于把隐性知识显性化。你平时审查代码时脑子里那套“先看命名、再看逻辑、最后看边界”的流程，写进 skill 之后就变成了可复用的资产。
3.2 参数与配置：容易踩坑的地方
在配置 skill 时，有几个参数特别容易出问题。我整理了一个对照表，都是实际调试中遇到的：
| 配置项 | 常见错误 | 正确做法 | 影响 |
|---|---|---|---|
| 触发关键词 | 写得太宽泛，比如“代码” | 用具体场景词，如“React 组件审查” | 太宽泛会导致 skill 被频繁误触发 |
| 工具依赖 | 声明了未安装的 plugin | 先确认 plugin 可用再写进 skill | 执行时报“工具不存在” |
| 输出格式 | 只写“输出报告” | 明确字段和顺序 | AI 输出随机，难以程序化处理 |
| 版本兼容 | 忽略宿主工具版本 | 在元信息里标注适配版本 | 升级后 skill 失效 |
提示：如果你在
codex里看到类似codex is ignoring 1 unrecognized configuration setting的警告，大概率是 skill 或配置文件里有个字段名拼错了。别慌，先检查拼写，再确认该字段是否被当前版本支持。
3.3 安装与加载：路径和顺序很关键
skills 的安装方式取决于宿主工具。以claude code为例，常见做法是把 skill 文件放到指定的 skills 目录下，然后重启工具或执行重载命令。在 Ubuntu 和 Windows 上，这个目录的位置可能不同。我建议你先用find skills或工具自带的列表命令确认当前已加载的 skills，再决定往哪里放新文件。
另外，热词里有个cc switch local proxy failed while handling codex endpoint /responses，这类报错通常和网络代理配置有关。如果你在公司内网或特殊网络环境下使用，需要确保宿主工具能正常访问它需要的端点。这不是 skills 本身的问题，但会直接影响 skill 的加载和执行。
4. 实操过程：从零写一个可用的 skill
4.1 场景选择：先挑一个“高频且规则明确”的任务
写第一个 skill，千万别挑那种“需要大量主观判断”的任务。我建议从高频、规则明确、输出格式固定的场景入手。比如：
- 把一段 JSON 转成 TypeScript 接口定义；
- 按团队规范生成 Git commit message；
- 检查代码里是否有硬编码的密钥；
- 把会议纪要整理成待办列表。
这些任务的共同点是：输入输出清晰，判断标准明确，不容易产生歧义。我第一个 skill 就是“把 API 响应示例转成 TypeScript 类型”，写完之后每天省下不少时间。
4.2 编写步骤：从草稿到可执行
假设我们要写一个“生成规范 commit message”的 skill。步骤如下：
- 定义元信息：名称叫
commit-message-helper，适用claude code和codex，版本 1.0。 - 写触发条件：当用户说“帮我写 commit”或“生成提交信息”时激活。
- 描述执行逻辑：先读取当前 git diff，提取变更文件类型和主要改动，然后按“类型(范围): 描述”的格式生成。
- 约束输出：类型限定为 feat、fix、docs、refactor、test、chore；描述不超过 50 字；不包含句号。
- 加边界条件：如果 diff 为空，提示用户先暂存更改；如果变更涉及多个不相关模块，建议拆分提交。
写完之后，先在一个测试仓库里跑几遍，看看输出是否符合预期。别一上来就在主仓库用，万一 skill 有 bug，可能生成一堆奇怪的提交信息。
4.3 调试与迭代：怎么判断 skill 好不好用
调试 skill 的核心指标就一个：稳定性。同一个输入，跑十次，输出应该基本一致。如果每次都不一样，说明约束写得不够死。我常用的调试方法是：
- 准备一组测试用例，覆盖正常情况、边界情况、异常情况；
- 每次修改 skill 后，全部跑一遍，记录通过率；
- 重点关注“AI 自作主张”的情况，比如你让它只给建议，它却直接改了文件。
注意：有些宿主工具在执行 skill 时会默认允许写操作。如果你不希望 AI 自动修改文件，一定要在 skill 里明确写“只读模式”或“仅输出建议”。这个坑我踩过，差点让 AI 把生产配置改了。
4.4 分享与复用：让 skill 产生复利
skill 写完之后，可以分享给团队或社区。分享时建议附上：适用场景、依赖条件、测试用例、已知限制。这样别人用起来心里有数。热词里的skills推荐、codex好用的skills、claude 国内安装skills 官方市场反映的就是这种需求——大家都想要“拿来就能用”的好东西。
5. 常见问题与排查技巧实录
5.1 安装类问题速查
| 问题现象 | 可能原因 | 排查步骤 | 解决方向 |
|---|---|---|---|
| 安装后找不到 skill | 目录放错或未重载 | 用列表命令确认加载路径 | 放到正确目录并重启 |
| 提示组织禁用订阅 | 账号权限或组织策略限制 | 检查账号状态和组织设置 | 联系管理员或换个人账号 |
| 下载安装包失败 | 网络或源地址问题 | 检查网络连通性和源配置 | 换源或手动下载 |
| VS Code 里不生效 | 插件版本或配置冲突 | 查看插件日志和配置项 | 更新插件或调整配置 |
5.2 执行类问题速查
| 问题现象 | 可能原因 | 排查步骤 | 解决方向 |
|---|---|---|---|
| skill 不触发 | 触发词不匹配 | 检查用户输入和触发条件 | 放宽或调整触发词 |
| 执行中断 | 依赖的 plugin 不可用 | 确认 plugin 已安装并启用 | 安装缺失 plugin |
| 输出格式乱 | 约束不够明确 | 检查输出规范部分 | 增加格式示例 |
| 结果不稳定 | 模型对指令敏感度不同 | 换模型或增加约束 | 用更确定的表达 |
5.3 几个我踩过的坑
第一个坑是触发词写得太泛。我写过一个“代码优化”的 skill，结果每次 AI 看到代码就想优化，连我贴个报错日志它都要“优化”一下。后来把触发词改成“当用户明确要求优化指定函数时”，才消停。
第二个坑是忽略宿主工具的版本差异。同一个 skill 在claude code旧版本能用，升级后字段名变了，直接失效。所以我现在写 skill 都会在元信息里标注“适配版本”，升级宿主工具后先跑一遍回归测试。
第三个坑是在 skill 里写了太多“建议性”语言。比如“你可以考虑检查一下……”，AI 会把这当成可选步骤，经常跳过。后来改成“必须检查……否则输出无效”，执行率立刻上来了。给 AI 写指令，确定性比礼貌重要。
6. 进阶方向：skills 还能怎么玩
6.1 组合多个 skill 完成复杂任务
单个 skill 解决单点问题，组合起来就能处理复杂流程。比如“代码审查”可以拆成：安全检查+性能检查+规范检查，三个 skill 依次执行，最后汇总报告。这种组合方式在agents场景下特别有用，因为 agent 可以按需调度不同的 skill。
6.2 针对特定领域定制 skill
热词里出现了codex写论文的skills、安卓脱壳skills、前端开发skills、superpower skills，说明大家已经在往垂直领域深耕了。我的经验是：领域越具体，skill 的价值越高。一个通用的“写作助手”skill 可能谁都能写，但一个“按某期刊格式整理参考文献”的 skill，对特定人群就是刚需。
6.3 测试与安全：别忽视的一环
热词里有个agent skills测试，还有agentpoison: red-teaming llm agents via poisoning memory or knowledge ba，这提醒我们：skills 也是攻击面。如果你从不可信来源安装 skill，它可能包含恶意指令。我的建议是：只从可信来源获取 skill，安装前通读内容，尤其是涉及文件操作和网络请求的部分。自己写的 skill 也要做基本测试，确保不会误删文件或泄露信息。
6.4 本地模型与 skills 的配合
如果你用claude code 调用lmstudio的本地模型，需要注意：本地模型对 skill 指令的遵循程度可能不如云端大模型。解决办法是把 skill 写得更“死”，减少模糊表达，增加示例。另外，本地模型的上下文窗口可能有限，skill 不宜过长，必要时拆成多个小 skill。
7. 我个人的一些实操体会
折腾 skills 这段时间，最大的感受是：它把“用 AI”从一门玄学变成了一门工程。以前大家比的是谁提示词写得好，现在比的是谁的 skill 设计得更合理、更稳定、更可复用。这对整个行业是好事。
另外，别指望一个 skill 解决所有问题。我见过有人想写一个“万能编程 skill”，结果什么都不精。好的 skill 是窄而深的，它只解决一个具体场景，但解决得很彻底。你先把这个场景吃透，再考虑扩展。
最后分享一个小技巧：写 skill 的时候，先手动做一遍任务，把每一步记下来，再翻译成 skill 指令。这样写出来的 skill 最贴近实际工作流，也最容易调试。直接凭空想“AI 应该怎么做”，往往漏掉关键步骤。
