1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会懵——这词太泛了技能、能力、插件、扩展什么都能套。但结合热搜词里高频出现的 Claude Code、Codex、plugin、agents 这几个词方向其实很明确这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code 和 Codex 这类终端/编辑器内的智能体工具构建的可复用能力单元。你可以把它理解成给 AI 助手装的技能包。原生模型再强它也不知道你团队内部的代码规范、你们私有 API 的调用方式、你们部署流程里的那些约定俗成的步骤。skills 就是把这些隐性知识显性化、模块化让 AI 在需要的时候自动加载、按你的方式干活。我接触这块是从 Claude Code 开始的。当时最大的痛点不是模型不够聪明而是每次都要重复交代同样的背景我们项目用 pnpm 不用 npm提交信息要遵循 Conventional Commits测试文件放在tests目录下。说一次两次还行天天说就是折磨。后来发现 skills 机制能把这些固化下来才算真正把 AI 助手用顺手了。这篇文章适合三类人看一是刚装上 Claude Code 或 Codex、还在摸索怎么让它懂自己的新手二是已经用了一阵、但每次都要重复提示词、想提效的中级用户三是想自己写 skills、做团队内部分享的进阶玩家。我会从概念讲到实操再讲我踩过的坑尽量让你少走弯路。需要先说明一点skills 这个概念在不同工具里叫法不完全一样。Claude Code 里叫 skillsCodex 生态里有时叫 plugin 或 agent 配置社区里还有 superpower skills 这种说法。名字不同本质是一回事——把可复用的指令、脚本、上下文打包让 AI 按需调用。下面我主要围绕 Claude Code 的 skills 展开因为它的机制最清晰、文档最全其他工具的玩法可以类比迁移。2. skills 的底层逻辑为什么它比写长提示词更靠谱2.1 提示词工程的瓶颈在哪里大多数人用 AI 编程助手第一反应是把要求写详细点。于是提示词越写越长从一句话变成一段话再变成一个小文档。这招在单次任务里有效但放到日常开发里问题就来了。首先是上下文浪费。你每次对话都塞一大段背景说明这些 token 是要占窗口的。窗口就那么大背景占多了真正要处理的代码就没地方放了。其次是一致性差。今天你记得写用 pnpm明天忘了AI 就给你 npm install你还得改。最后是无法沉淀。你写的提示词只存在于这次对话里换个会话、换台机器就没了团队里其他人更用不上。我见过有人把提示词存成 txt 文件每次手动粘贴。这算是土办法里的最优解了但依然很笨——你得记得粘得找对文件还得祈祷内容没过时。2.2 skills 解决的三个核心问题skills 机制本质上是把提示词升级成了可管理的资产。它解决的核心问题有三个按需加载不浪费上下文。skills 平时不占用对话窗口只有当 AI 判断当前任务和某个 skill 相关时才会把它的内容读进来。这就像你电脑里的软件不用的时候不占内存点了才启动。版本化、可共享。skills 是文件可以放进 Git 仓库可以 review可以迭代。团队里一个人写好其他人 clone 下来就能用。这比在群里发记得让 AI 用 xxx靠谱一万倍。结构化能带脚本。一个 skill 不只是一段文字说明它还可以包含可执行脚本、模板文件、参考文档。AI 需要跑个命令时直接调用 skill 里的脚本比它自己现编要稳得多。提示skills 不是万能的。它擅长的是流程性、重复性、有明确规范的任务。如果你的需求每次都不一样、高度依赖临场判断那写 skill 的收益不大老老实实对话就行。2.3 一个类比skills 就像给新同事的入职手册我习惯用这个类比跟团队解释AI 助手是个能力很强但完全不了解你公司的新同事。你不给它手册它就只能按通用最佳实践干活经常和你们的实际情况对不上。skills 就是那本入职手册——里面写着我们代码怎么组织提交怎么做遇到某类问题找谁。区别在于这本手册是活的。新同事AI会在遇到具体问题时自动翻到对应的那一页而不是从头读到尾。这就是按需加载的价值。理解了这层逻辑后面讲怎么装、怎么写、怎么用就都是水到渠成的事了。3. 环境准备Claude Code 与 Codex 的安装路径差异3.1 Claude Code 的安装与验证Claude Code 的安装方式这几年变过几次现在主流是通过 npm 全局安装。前提是你机器上有 Node.js版本建议 18 以上。npm install -g anthropic-ai/claude-code装完之后在终端敲claude应该能进交互界面。第一次用会走登录流程按提示操作即可。Windows 用户注意官方对 Windows 的原生支持是逐步完善的如果你在 Windows 上遇到路径或权限问题可以考虑在 WSL 里跑体验会顺很多。验证安装是否成功除了能进界面还可以看版本claude --version我踩过的一个坑是全局装完之后在某些 shell 配置里claude命令找不到。这通常是 PATH 没刷新重开终端或者手动 source 一下配置文件就好。别急着重装先排查 PATH。3.2 Codex 的安装与常见报错Codex 这边情况稍微复杂点因为它有多个化身——有 OpenAI 官方的 CLI 工具也有社区基于 API 做的各种封装。热搜词里出现的codex安装教程codex安装包codex官网下载说明很多人卡在第一步。官方 CLI 一般也是 npm 或 pip 安装。装完之后常见的报错有两类一类是认证相关。比如提示组织设置问题、订阅访问被禁用之类。这类基本是账号权限或配置没弄对检查你的 API key、组织配置确认账号有对应权限。另一类是网络请求失败。热搜里那个 cc switch local proxy failed while handling codex endpoint /responses 就是典型。这种报错通常出现在你配置了某种本地转发或代理设置、但配置本身有问题的时候。排查思路是先确认你的网络配置是否必要如果不需要就走直连如果确实需要检查端口、地址、协议是否匹配。注意涉及网络配置的部分我建议优先用官方推荐的方式不要随意套用网上来路不明的配置。配置错了轻则报错重则把简单问题搞复杂。3.3 编辑器集成VS Code 与 IDEA很多人不满足于终端想把 AI 助手接进编辑器。VS Code 这边Claude Code 有对应的扩展装完之后可以在编辑器内直接调用。IDEA 用户则更多是通过插件市场找相关插件。这里有个高频坑插件仓库地址配置。热搜里idea设置plugin中插件仓库地址就是这个。如果你在公司内网默认的插件市场可能访问不了需要配内部镜像地址。配置位置在 Settings 里的 Plugins 相关选项具体路径各版本略有差异找不到就搜plugin repository。VS Code 配置 Claude Code 时另一个常见需求是接本地模型。热搜里claude code 调用lmstudio的本地模型就是这个场景。思路是把 Claude Code 的请求指向本地 LM Studio 暴露的接口。这需要改配置里的 base URL 和模型名。本地模型的好处是数据不出机器、不花钱代价是能力通常不如云端大模型复杂任务上差距明显。4. skills 的目录结构与加载机制4.1 一个 skill 长什么样Claude Code 的 skills 通常放在特定目录下每个 skill 一个文件夹里面至少有一个描述文件一般是 markdown 格式带 frontmatter 元数据还可以带脚本、模板、参考文档。一个典型的 skill 目录大概是这样my-skill/ SKILL.md # 主描述文件含元数据和指令 scripts/ helper.sh # 可执行脚本 templates/ commit.txt # 模板文件 reference.md # 补充参考SKILL.md开头的 frontmatter 一般包含 name、description 这类字段。description 特别关键——AI 就是靠它判断当前任务要不要加载这个 skill。写得太模糊AI 该用的时候不用写得太宽泛不该用的时候乱用。4.2 加载是怎么触发的这是很多人搞不清的地方。skills 不是全部一次性读进上下文的那样窗口早爆了。它的机制是AI 先看到所有 skills 的 name 和 description这部分很轻量然后根据当前对话内容判断哪些相关再把相关的 skill 完整内容读进来。所以 description 的写法直接决定了 skill 的命中率。我的经验是description 里要包含触发场景的关键词。比如一个处理数据库迁移的 skilldescription 里就该出现migrationschema change数据库变更这类词这样用户一提到相关任务AI 就能对上号。4.3 全局 skills 与项目 skillsskills 一般分两个层级全局的和项目级的。全局的放在用户目录下所有项目都能用项目级的放在项目仓库里只对这个项目生效。怎么选我的原则是通用规范放全局项目特有逻辑放项目级。比如提交信息格式这种全公司统一的放全局这个项目的 API 网关怎么调这种只对本项目有意义的放项目级。项目级 skills 跟着代码走好处是新人 clone 下来就自带不用额外配置。这也是我推荐团队把 skills 纳入版本管理的原因。5. 手写第一个 skill从需求到落地5.1 选一个值得做成 skill 的场景别一上来就搞复杂的。选场景的标准是重复出现、有明确规范、你每次都要交代。我第一个 skill 做的是提交信息规范因为团队要求 Conventional Commits而我每次让 AI 提交都要提醒一遍。判断一个场景值不值得做成 skill问自己三个问题这事我一周要交代几次交代的内容是不是基本固定做错了会不会有实际影响三个都是是那就值得。5.2 写 description 的门道前面说了 description 决定命中率。具体怎么写我的模板是当用户需要做 X 时使用本 skill本 skill 会按 Y 规范完成 Z。举个例子提交信息 skill 的 description 可以写成当用户需要提交代码、生成 commit message 或执行 git commit 时使用。本 skill 会按 Conventional Commits 规范生成提交信息包含 type、scope、description 三部分。这样写用户一说帮我提交AI 就能匹配上。如果只写提交相关太模糊可能匹配不上也可能乱匹配。5.3 正文指令的写法description 之后是正文也就是 AI 加载 skill 后要遵循的具体指令。这部分要写得具体、可执行、有例子。还是拿提交信息举例正文里我会写清楚type 有哪些可选值feat、fix、docs、refactor 等scope 怎么填description 用什么语气正文和 footer 什么情况下需要。最好再给两三个正例和反例。反例特别有用。AI 看到不要写成这样的具体例子比看十条抽象规则都管用。我一般会放一个错误示范和一个正确示范对照。5.4 给 skill 加脚本纯文字指令能解决大部分问题但有些任务需要确定性——比如格式化、校验、生成文件。这时候给 skill 配脚本就很有价值。脚本可以是 shell、Python、Node看你的技术栈。关键是脚本要幂等、有清晰输出、出错有提示。AI 调用脚本后会根据输出决定下一步。如果脚本静默失败AI 就懵了。我有个 skill 里放了个校验脚本检查提交信息格式。AI 生成信息后先跑脚本不通过就自己改改到通过为止。这比让 AI自己检查可靠多了。6. 实测中那些文档没写的坑6.1 description 写太宽skill 被乱触发我早期有个 skill 的 description 写得太泛结果 AI 在很多不相关的任务里都把它加载进来白白占上下文还偶尔干扰判断。后来把 description 收窄明确写清仅在 X 场景下使用问题就解决了。教训是宁可窄一点也不要宽。窄了顶多是该用的时候没自动用你手动提一句就行宽了是到处乱用反而添乱。6.2 脚本路径用相对路径换机器就挂skill 里的脚本如果用了绝对路径换台机器、换个用户目录就找不到。一定要用相对于 skill 目录的路径或者用环境变量。这个坑我踩过一次本地好好的同事拉下来直接报错排查半天才发现是路径写死了。6.3 中文内容在部分环境下的编码问题如果你的 skill 里有中文在某些终端或编辑器里可能出现乱码。稳妥做法是确保文件用 UTF-8 编码保存脚本里处理文本时显式指定编码。这个不是 skills 特有的问题但确实容易在跨平台协作时冒出来。6.4 更新 skill 后没生效改完 skill 文件有时候 AI 还是按老版本干活。这通常是缓存问题。多数工具会在新会话里重新读取所以改完 skill 后开个新会话试试。如果还不行检查是不是改错了文件位置——全局和项目级目录容易搞混。6.5 别把 skill 当垃圾桶见过有人把所有零碎要求都塞进一个 skill结果这个 skill 又大又杂加载慢、命中率还低。skill 应该单一职责一个 skill 干好一件事。需要多个能力时拆成多个 skill让 AI 按需组合。7. 进阶玩法skills 与 agents 的配合7.1 agent 和 skill 的分工热搜里 agents 出现频率很高。简单说agent 是干活的角色skill 是干活的方法。一个 agent 可以调用多个 skill就像一个人会多种技能。比如你有个代码审查 agent它可能调用安全审查 skill风格检查 skill测试覆盖检查 skill。每个 skill 专注一件事agent 负责编排。7.2 用 skills 给 agent 补能力原生 agent 的能力是固定的但通过挂载 skills你可以给它扩展。这有点像给游戏角色装装备。同一个 agent装了不同的 skills就能适应不同项目。我现在的做法是维护一套通用 skills然后针对不同项目组合出不同的 agent 配置。新项目来了挑几个 skill 一挂agent 就懂这个项目了。7.3 团队协作中的 skills 管理团队用 skills最大的挑战不是技术是维护。谁负责更新什么时候 review版本怎么管我的建议是把 skills 当代码管。放 Git 仓库走 PR 流程有变更记录。指定一两个人做 maintainer负责合并和发布。定期清理过时的 skill别让仓库变成垃圾场。另外skills 的文档要跟上。每个 skill 除了给 AI 看的指令最好还有给人看的说明——这个 skill 干什么、怎么用、有什么限制。不然新人看到一堆 skill 文件夹完全不知道从哪下手。8. 我个人的几条实操心得用了一段时间 skills有几个体会想分享。先手动跑通再固化成 skill。别一上来就写 skill先手动把流程走几遍确认稳定了、规范清晰了再写成 skill。不然你固化的是一个还没想清楚的流程后面改起来更麻烦。skill 要短小精悍。我见过写了几千字的 skillAI 加载后反而抓不住重点。好的 skill 应该像好的函数——短、职责单一、意图明确。细节可以放参考文档里让 AI 需要时再读。定期回顾命中率。用一阵子后回头看看哪些 skill 经常被触发、哪些几乎没用过。没用的要么删掉要么说明 description 写得不对。这个回顾很重要不然 skills 越堆越多实际有效的没几个。别追求一步到位。skills 是迭代出来的。第一版能跑就行用着用着发现哪里不顺再改。我现在的几个核心 skill 都改过七八版了每版都是被实际问题逼出来的。跨工具的思路可以迁移。Claude Code 的 skills 玩明白了Codex 那边的 plugin、agent 配置理解起来就快。核心都是把可复用能力模块化、按需加载具体 API 和目录结构不同而已。所以别纠结学哪个先把一个吃透。最后说个我最近在试的方向把 skills 和项目的 CI 流程结合。比如提交前自动跑 skill 里的校验脚本不通过就拦住。这样 skills 不只是给 AI 看的还成了给流程用的价值又大了一层。这个还在摸索等跑顺了再细说。