1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术群还是各种开发者社区“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到skills、claude code、codex、plugin、agents、find skills、skills推荐、codex skills、claude agent skills……这些词几乎绑在一起出现。很多人第一次看到“skills”会以为是某种新编程语言或者框架其实不是。它更像是一套给AI编码助手用的“能力包”或者“技能插件”让原本只会聊天的模型变成能真正动手干活的开发助手。我最早接触这个概念是在折腾 Claude Code 的时候。当时我装好了命令行工具也能正常对话但总觉得它“差点意思”——比如我想让它帮我按团队规范生成一个 React 组件它每次给的风格都不一样我想让它跑一遍项目的 lint 和测试它得我一步步教。后来才明白问题不在模型本身而在于我没有给它装对应的 skills。装上之后同一个模型的表现完全是两个档次。所以这篇内容我想聊的就是围绕skills这个核心把 Claude Code、Codex、plugin、agents 这一整套东西讲透。包括它是什么、为什么需要、怎么装、怎么选、怎么自己写、踩过哪些坑。适合两类人看一类是刚听说 Claude Code 或者 Codex想上手但不知道从哪开始的另一类是已经在用但只会基础对话想让 AI 真正融入自己开发流程的。我会尽量用大白话把每个关键选择背后的逻辑讲清楚而不是只丢一堆命令让你抄。先给一个最直白的类比。你可以把 Claude Code 或者 Codex 想象成一个刚招进来的实习生脑子很聪明但对你公司的代码规范、项目结构、常用工具一无所知。skills就是你给这个实习生写的入职手册加工具箱手册告诉他遇到什么情况该怎么做工具箱给他现成的脚本和模板。plugin则是把这些手册和工具打包成一个可以分发的安装包。agents是让这个实习生能同时扮演多个角色比如一个负责写代码一个负责审查一个负责跑测试。理解了这层关系后面所有的操作都会顺很多。2. 核心概念拆解skills、plugin、agents 到底谁是谁2.1 skills 的本质给模型的结构化指令集很多人以为 skills 是什么高深的技术其实拆开看非常朴素。一个 skill 本质上就是一段结构化的说明文档加上可选的脚本和资源文件。它通常包含几个部分这个 skill 叫什么、什么时候触发、触发后模型应该按什么步骤操作、需要调用哪些工具、输出格式是什么。我拿一个真实场景举例。假设你团队规定所有新组件必须用 TypeScript、必须带单元测试、必须遵循特定的目录结构。你可以写一个叫new-component的 skill里面写清楚当用户说“新建一个组件”时先询问组件名和用途然后在src/components/下创建目录生成index.tsx、index.test.tsx、styles.module.css三个文件测试文件里预置一个渲染测试。这样每次你只要说一句“新建一个 Button 组件”模型就会自动按这套流程走不用你反复交代。这就是 skills 的核心价值把重复的、有规范要求的操作从“每次口头描述”变成“一次定义、反复调用”。它解决的是模型“记性差”和“风格飘”的问题。没有 skills 的时候你每次都得把上下文重新喂一遍有了 skills规范被固化下来输出稳定性提升非常明显。2.2 pluginskills 的分发和装载机制光有 skill 文件还不够你得让工具能发现它、加载它。这就是 plugin 的作用。plugin 可以理解为一个容器里面可以装一个或多个 skills还可以装命令、agent 定义、配置文件。它的存在是为了解决分发问题——你写好一套 skills打包成 plugin团队里其他人一条命令就能装上不用手动复制文件到某个神秘目录。热搜词里有个dsh plugin --profile web add dshmarket这就是典型的 plugin 管理命令。不同工具的 plugin 机制不太一样但思路是共通的有一个插件市场或者仓库地址你通过命令把插件拉下来工具启动时自动扫描并加载。这里有个容易踩的坑plugin 的加载顺序和优先级。如果你装了两个功能重叠的 plugin比如都定义了“代码审查”这个 skill那到底哪个生效通常后装的或者显式指定的会覆盖前面的但不同工具行为不一致最好避免功能重叠。2.3 agents让 skills 组合成工作流单个 skill 解决单点问题agents 解决的是多步骤、多角色的协作问题。一个 agent 可以理解为一个“有特定职责的 AI 角色”它有自己的系统提示词、可以调用的 skills 集合、以及和其他 agent 的协作方式。举个例子你可以定义一个revieweragent它的职责是审查代码只能调用 lint 相关的 skills再定义一个fixeragent职责是根据审查意见修改代码。当你提交一个 PR 时reviewer 先跑一遍输出问题列表fixer 再根据列表逐条修复。这套东西在 LangChain 的 deep agents 或者 Claude 的 agent skills 体系里都有对应实现。热搜里有个词叫agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这个值得单独提一句。它讲的是 agent 的安全问题——如果 agent 的记忆或者知识库被污染它可能做出危险操作。这提醒我们给 agent 开放文件写入、命令执行权限时一定要谨慎尤其是从不可信来源安装的 skills 和 plugin里面可能藏着你没注意到的危险指令。概念本质解决的问题典型载体skill结构化指令集规范输出、固化流程Markdown 文件 脚本plugin分发容器安装、加载、版本管理插件包 市场agent角色化工作流多步骤协作、职责分离配置 skills 组合3. 环境准备Claude Code 和 Codex 的安装与配置3.1 Claude Code 安装不同系统的实操路径Claude Code 的安装方式取决于你的操作系统。热搜里claude code安装、claude code windows、ubuntu配置claude code、claude code下载这些词说明很多人卡在第一步。我把自己在 Windows 和 Ubuntu 上的安装过程整理一下。在 Ubuntu 或者 macOS 上最省事的方式是通过包管理器。以 Ubuntu 为例先确保 Node.js 版本在 18 以上然后用 npm 全局安装node -v npm install -g anthropic-ai/claude-code claude --version装完之后第一次运行claude会引导你登录。这里有个细节登录方式和你所在的环境有关如果命令行里登录流程走不通可以试试在 VS Code 里装对应的扩展通过编辑器界面完成认证。热搜里claude code for vs code、vscode配置claude code就是干这个的。Windows 上稍微麻烦一点。原生 Windows 对命令行工具的支持一直是个痛点我试过直接在 PowerShell 里跑能跑但偶尔有路径和编码问题。后来我改用 WSL2把 Claude Code 装在 WSL 的 Ubuntu 环境里稳定很多。如果你坚持用原生 Windows记得把终端编码设成 UTF-8否则中文输出可能乱码。注意安装过程中如果遇到权限报错不要无脑加 sudo。npm 全局安装的权限问题更推荐用 nvm 管理 Node 版本从根上避免权限冲突。3.2 Codex 安装从下载到接入本地模型Codex 这边的热搜词更杂codex安装、codex安装教程、codex安装包、codex下载、codex官网下载、codex安装 csdn、codex登录、codex接入deepseek、codex无法加载组织设置。看得出来安装和登录是两大拦路虎。Codex 的安装同样依赖 Node 环境基本流程和 Claude Code 类似。但 Codex 有一个很吸引人的点它可以接入本地模型或者第三方模型服务。热搜里claude code 调用lmstudio的本地模型和codex接入deepseek说的就是这类需求。接入本地模型的好处是数据不出本机适合对隐私敏感的场景代价是本地模型的推理能力通常不如云端大模型复杂任务上差距明显。配置本地模型时核心是改配置文件里的 endpoint 和 model 字段。以接入 LM Studio 为例先在 LM Studio 里启动本地服务记下端口默认 1234然后在 Codex 配置里把 base URL 指向http://localhost:1234/v1model 填你在 LM Studio 里加载的模型名。这里有个坑不同模型对 function calling 的支持程度不一样如果模型不支持工具调用skills 里依赖工具的部分就会失效。选本地模型时优先挑明确支持 function calling 的。3.3 常见安装报错速查安装阶段的问题五花八门我整理了几个高频的报错关键词可能原因处理思路cc switch local proxy failed本地代理配置冲突检查是否有其他工具占用了同一端口关掉冲突进程you must install the j2se plugin versionJava 环境缺失或版本不对装对应版本的 JDK配置 JAVA_HOMEqt.qpa.plugin: could not find the qt platform pluginQt 平台插件路径问题设置 QT_QPA_PLATFORM_PLUGIN_PATH 环境变量your organization has disabled claude subscription access组织策略限制换个人账号或联系管理员这个自己改不了codex无法加载组织设置配置文件格式或权限问题检查配置目录读写权限确认 JSON 格式合法这些报错看着吓人其实大部分是环境问题跟工具本身没关系。我的经验是遇到报错先看最后一行命令行工具的报错信息通常最后一行才是真正原因前面一堆是调用栈。4. skills 的获取、筛选与安装实战4.1 去哪里找 skills官方市场和社区仓库装好工具之后下一步就是找 skills。热搜里find skills、skills推荐、claude 国内安装skills 官方市场、codex好用的skills都是这个需求。目前主要的来源有几个官方维护的 skills 市场、社区贡献的仓库、以及团队内部自建的私有仓库。官方市场的 skills 质量相对有保障但数量有限覆盖的场景偏通用。社区仓库就丰富了从“生成 commit message”到“自动写周报”应有尽有但质量参差不齐。我的建议是优先用官方和知名团队维护的 skills社区来源的装之前先读一遍内容。因为 skill 里可能包含脚本脚本是会真实执行的来源不明的东西直接装风险不小。团队内部自建仓库是最有价值的。因为只有你自己团队才知道自己的规范是什么。我现在的做法是维护一个内部 plugin 仓库把常用的 skills 都放进去新人入职一条命令装好省去大量口头培训。4.2 安装 skills 的三种方式安装方式取决于你用的工具和 skill 的分发形式。常见的有三种第一种是通过 plugin 市场安装。比如dsh plugin --profile web add dshmarket这种命令指定 profile 和仓库地址工具自动拉取。这种方式最省心适合官方或团队维护的 plugin。第二种是手动放置文件。把 skill 的 Markdown 文件和资源目录复制到工具的 skills 目录下。不同工具目录位置不同Claude Code 通常在用户配置目录下的skills/文件夹。这种方式适合调试和临时使用。第三种是通过配置文件声明。有些工具支持在配置文件里列出 skill 的来源路径启动时自动加载。这种方式适合需要精确控制加载顺序的场景。提示不管用哪种方式装完之后一定要验证。最简单的验证方法是问模型“你现在有哪些 skills”看它列出来的清单对不对。如果没加载上检查文件路径和权限。4.3 筛选 skills 的四个标准skills 装多了会互相干扰所以筛选很重要。我用四个标准来判断一个 skill 值不值得装触发频率这个操作你一周做几次低于一周一次的手动做就行不值得为它装 skill。规范强度这个操作有没有必须遵守的规范有规范才需要固化没规范的随意操作不需要 skill。维护状态最后一次更新是什么时候依赖的工具版本和你的环境是否匹配长期不更新的 skill 可能已经失效。安全风险skill 里有没有执行外部命令、读写敏感文件、访问网络有的话要格外小心。按这四个标准筛一遍能砍掉一大半。我自己的 skills 清单常年保持在十个以内每个都是高频且强规范的。5. 自己动手写一个 skill从需求到落地5.1 确定 skill 的边界和触发条件写 skill 的第一步不是写内容而是想清楚边界。一个好的 skill 应该只做一件事并且把这件事做透。我见过有人写一个“万能开发 skill”里面塞了几十种场景结果模型根本不知道该在什么时候用哪部分效果很差。确定边界之后定义触发条件。触发条件要具体不能太宽泛。比如“当用户提到组件”就太宽模型可能在你只是讨论组件设计时就触发创建流程。更好的写法是“当用户明确要求新建一个组件且提供了组件名时触发”。5.2 skill 文件的结构与写法一个典型的 skill 文件包含元信息和正文两部分。元信息声明名称、描述、触发条件正文写具体步骤。下面是一个简化示例--- name: new-component description: 按团队规范新建 React 组件 trigger: 用户要求新建组件并提供组件名 --- ## 步骤 1. 确认组件名使用 PascalCase 2. 在 src/components/ 下创建同名目录 3. 生成 index.tsx使用函数式组件 TypeScript 4. 生成 index.test.tsx包含一个基础渲染测试 5. 生成 styles.module.css预置空样式 6. 更新 src/components/index.ts 导出新组件写法上有几个要点。步骤要可执行每一步都是明确的动作不要写“合理处理”这种模糊表述。输出格式要固定比如文件命名、目录结构都写死避免模型自由发挥。异常情况要覆盖比如组件已存在时怎么办要提前写清楚。5.3 测试和迭代 skill 的方法skill 写完不是终点要测试。我的测试方法是用三个不同复杂度的任务跑一遍看模型是否按预期触发、步骤是否完整、输出是否符合规范。第一个任务用最简单的场景验证基本流程第二个任务加一点变化比如组件名带特殊字符看异常处理第三个任务故意给模糊指令看模型会不会误触发。测试中发现问题就改 skill 文件改完重新加载再测。这个迭代过程通常要来回三四次才能稳定。别指望一次写好skill 的打磨和写代码一样是迭代出来的。6. 把 skills 用进真实开发流程6.1 代码生成与规范落地skills 最直接的价值就是代码生成。以前你用 AI 生成代码得反复强调“用 TypeScript”“加测试”“按这个目录结构”现在这些规范都固化在 skill 里一句话就能得到符合团队标准的代码。我实测下来用了 skill 之后生成代码的返工率下降非常明显尤其是新人用的时候产出质量直接拉到及格线以上。这里有个经验把 lint 规则和 skill 结合起来。skill 生成代码后自动跑一遍 lint有问题让模型自己修。这样出来的代码基本能直接过 CI省去大量手动调整。6.2 代码审查与问题排查审查场景也很适合用 skills。你可以写一个reviewskill定义审查清单有没有硬编码密钥、有没有未处理的异常、测试覆盖是否足够、命名是否规范。模型按清单逐条检查输出结构化的审查报告。比人肉审查快而且不会漏项。排查问题也可以用 skill。比如定义一个debugskill规定排查步骤先看日志、再复现、再定位、再验证修复。模型按这个流程走比漫无目的地问“哪里出错了”高效得多。6.3 多 agent 协作的编排思路当 skills 多起来之后可以考虑用 agents 编排。比如一个典型的开发流程可以拆成planner负责拆解需求、coder负责写代码、reviewer负责审查、tester负责跑测试。每个 agent 只加载自己需要的 skills职责清晰互不干扰。编排的关键是定义好 agent 之间的接口。planner 输出的任务描述格式要固定coder 才能准确理解reviewer 输出的问题列表格式要固定fixer 才能逐条处理。接口不稳定整个流程就会乱。7. 常见问题与避坑经验实录7.1 skills 不生效的排查思路skills 装了但不生效是最常见的问题。排查顺序我一般是这样的先确认文件放对了目录再确认工具启动时有没有报加载错误再确认触发条件是否匹配。很多时候不是 skill 有问题而是你说的那句话没命中触发条件。可以试着用 skill 描述里的关键词来触发看能不能生效。还有一个隐蔽的坑skill 之间的优先级冲突。如果两个 skill 的触发条件重叠模型可能选了你不想要的那个。解决办法是让触发条件尽量互斥或者在 skill 里显式声明优先级。7.2 模型不按 skill 步骤执行的应对有时候模型加载了 skill但不完全按步骤走跳步或者自由发挥。这通常是因为 skill 写得不够强制。可以在 skill 里加一句“必须严格按以下步骤执行不得跳过或合并步骤”。另外步骤数量不要太多超过十步模型容易漏。如果流程确实长拆成多个 skill 串联。7.3 安全与权限的边界控制这是我最想强调的一点。skills 和 agents 能执行命令、读写文件权限给大了很危险。我的原则是最小权限。只读的 skill 不给写权限只处理特定目录的 skill 不开放全盘访问需要执行命令的 skill 把命令白名单列出来。热搜里那个 agent 投毒的话题不是危言耸听从不可信来源装的 skill 真的可能干坏事。问题现象排查方向解决手段skill 完全不触发目录、加载、触发词逐项检查用关键词测试触发但跳步skill 强制力不足加强制语句拆分长流程多个 skill 冲突触发条件重叠互斥化触发条件声明优先级执行报权限错误权限配置过严或过松按最小权限原则调整输出格式不稳定输出格式未写死在 skill 里固定输出模板8. 我个人的一些使用体会折腾这套东西大半年最大的感受是skills 的价值不在于让 AI 更聪明而在于让 AI 更可控。模型本身的能力已经够强了真正拖后腿的是它不了解你的上下文、不遵守你的规范。skills 就是补上这一环的。另一个体会是不要贪多。我一开始装了一堆 skills结果互相干扰反而不好用。后来精简到十个以内每个都打磨到位效率反而上去了。写 skill 也是与其写十个半成品不如写一个能稳定跑的。最后分享一个小技巧把 skill 当成代码来管理。用 Git 版本控制写变更记录定期 review。这样团队协作的时候谁改了什么、为什么改都清清楚楚。skill 不是一次性写完就扔的东西它需要和维护代码一样的投入。