1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术群还是各种开发者社区“skills”这个词出现的频率高得离谱。你如果只看字面意思可能会觉得这不就是“技能”吗有什么好聊的。但放在 Claude Code、Codex、agents 这套生态里skills 指的是一套非常具体的东西——它是给 AI 编程助手用的可复用能力包本质上是一组结构化的指令、脚本和资源文件让 agent 在特定任务上表现得像一个训练有素的专家而不是每次都要你从头解释一遍需求。我最早接触这个概念是在折腾 Claude Code 的时候。当时我的痛点很明确每次让 AI 帮我写一个符合团队规范的 React 组件都要把目录结构、命名规则、样式方案、测试要求重新说一遍说多了它还会漏。后来发现 skills 机制就是冲着这个场景来的——你把一套标准流程写成一个 skill之后 agent 遇到同类任务会自动加载这套规则输出质量立刻稳定下来。这个体验上的差别用过就回不去了。所以这篇内容我想聊的不是“skills 是什么”这种百科式定义而是从一个实际使用者的角度把 skills 的设计逻辑、安装配置、开发方法、常见坑全部拆开讲一遍。适合谁看如果你正在用 Claude Code 或者 Codex 写代码或者你在搭自己的 agent 工作流再或者你只是好奇“为什么别人用 AI 写代码比我顺那么多”那这篇应该能给你一些直接能抄的东西。我会尽量把每个操作背后的“为什么”讲清楚而不是只丢一堆命令让你照敲。需要先说明一点skills 这套东西目前还在快速演进不同工具Claude Code、Codex、各类 agent 框架对它的支持程度和实现细节不完全一样。我下面讲的内容以我实际跑通的路径为主遇到有差异的地方会明确标出来你根据自己的工具版本做调整。2. skills 的核心设计逻辑为什么是“包”而不是“提示词”2.1 从提示词工程到能力封装思路变了早两年大家玩 AI 编程核心动作是“写提示词”。你把需求描述得越细模型输出越好。但这个模式有个天花板提示词是一次性的换个会话就没了团队里也没法共享。你今天调好的一段完美提示词明天同事还得重新调一遍。这就像你每次做菜都要从零开始配调料而不是用一罐已经调好的酱。skills 的思路是把“调好的酱”固化下来。一个 skill 通常包含几个部分一个描述文件告诉 agent 这个 skill 是干什么的、什么时候该用、若干指令文件具体的规则和步骤、可选的脚本或模板资源。agent 在运行时根据任务类型匹配到对应的 skill然后把这套规则加载进上下文。这个机制的关键在于按需加载——不是把所有规则一股脑塞给模型而是用到哪个加载哪个既省 token 又避免规则互相干扰。我打个比方。以前的提示词工程像是你每次打电话给一个顾问都要把背景从头讲一遍。skills 像是你给这个顾问建了一套档案他接到任务先翻档案看到“哦这是前端组件任务”自动调出对应的规范手册。顾问还是那个顾问但有了档案之后他的表现稳定多了。2.2 一个 skill 的典型结构长什么样虽然不同工具的目录约定有差异但一个标准 skill 的骨架大同小异。以我实际用的结构为例my-skill/ ├── SKILL.md # 核心描述文件包含元信息和指令 ├── scripts/ # 可执行脚本比如代码生成、校验 ├── templates/ # 模板文件比如组件骨架 └── resources/ # 参考资料比如规范文档其中SKILL.md是最关键的。它通常有一个 frontmatter 区域用 YAML 格式写明这个 skill 的名称、描述、触发条件。下面才是正文指令。这个设计的好处是 agent 可以先只读 frontmatter 做匹配确认要用这个 skill 了再读正文节省上下文。注意frontmatter 里的 description 字段非常关键它决定了 agent 能不能在正确的时机匹配到这个 skill。写得太窄该触发的时候不触发写得太宽不该触发的时候乱触发。这个我后面会专门讲怎么写。2.3 为什么这套机制对 agent 特别重要agent 和普通聊天机器人的区别在于agent 要自主决策、多步执行。它自己判断该用什么工具、按什么顺序做。如果没有 skillsagent 每次都要靠通用能力硬扛遇到专业任务就容易翻车。有了 skills相当于给 agent 配了一套“专业工具箱”它知道遇到什么情况该掏哪个工具。这也是为什么 skills 和 agents 这两个词总是绑在一起出现。agents 是执行者skills 是它的能力库。你搭一个 agent 系统skills 的质量直接决定了这个 agent 的上限。我见过不少人抱怨“agent 不好用”拆开一看问题往往不在模型而在于没给它配好 skills让它赤手空拳干活。3. 环境准备Claude Code 与 Codex 的安装配置实操3.1 Claude Code 的安装路径与验证方法Claude Code 目前的安装方式主要有两种通过包管理器全局安装或者用官方提供的安装脚本。我推荐用包管理器因为升级和卸载都干净。以 npm 为例npm install -g anthropic-ai/claude-code装完之后不要急着用先验证一下版本和路径claude --version which claudewhich这一步很多人会跳过但它能帮你排查后面“命令找不到”的问题。如果which输出为空说明全局 bin 目录没在 PATH 里这时候你要么改 PATH要么用 npx 方式调用。Windows 用户要注意Claude Code 在 Windows 上的原生支持是后来才完善的。如果你在 Windows 上遇到路径分隔符或者权限相关的报错一个稳妥的做法是在 WSL 里跑环境更接近 Linux踩坑少。我自己的 Windows 机器就是 WSL Claude Code 的组合实测下来很稳。安装完成后第一次运行会引导你配置认证。这一步按提示走就行我不展开。配置信息一般存在用户目录下的配置文件夹里你可以通过claude config list之类的命令查看当前配置状态。3.2 Codex 的安装与常见报错处理Codex 的安装路径和 Claude Code 类似也是包管理器为主。但 Codex 在实际使用中我遇到过一个高频问题配置项拼写错误导致被忽略。报错信息大概是“ignoring 1 unrecognized configuration setting. check for typos”。这个问题的根源是配置文件里某个 key 写错了Codex 不会直接报错退出而是静默忽略然后你发现某个功能没生效排查半天。我的处理习惯是每次改完配置文件先用一个最小任务跑一遍确认配置被正确读取。配置文件建议用带 schema 校验的编辑器打开能实时提示拼写问题。另外 Codex 的配置项在不同版本间有过调整升级之后最好对照官方文档过一遍别直接沿用旧配置。还有一个常见问题是“无法加载组织设置”。这个通常和认证状态有关可能是 token 过期或者权限变更。排查顺序是先确认登录状态再确认组织权限最后看网络请求是否正常。这三步能覆盖大部分情况。3.3 让 Claude Code 调用本地模型的配置思路有些场景下你会想让 Claude Code 调用本地部署的模型比如用 LM Studio 跑一个本地模型。这个配置的核心是改 endpoint。Claude Code 默认连的是官方服务你要在配置里把 base URL 指向本地服务的地址同时确认本地服务暴露的是兼容的 API 格式。配置的时候有几个点容易翻车。第一是端口LM Studio 默认端口和你实际配置的要对上。第二是模型名称本地加载的模型名要和配置里写的一致差一个字符都连不上。第三是上下文长度本地模型如果上下文窗口小长任务容易截断这个要在模型加载参数里调。提示本地模型跑 agent 任务对显存要求不低尤其是需要长上下文的时候。如果你的机器配置一般建议先用短任务测试确认链路通了再上复杂任务。4. skills 的开发与使用从找到用再到自己写4.1 怎么找到好用的 skillsskills 的获取渠道目前主要有几个官方市场、社区分享、自己开发。官方市场里的 skills 质量相对有保障但覆盖面有限。社区分享的 skills 数量多但质量参差不齐用之前最好先读一遍它的 SKILL.md看看指令写得是否清晰、有没有明显的逻辑漏洞。我筛选 skills 有个习惯先看它的 description 写得是否具体。一个 description 如果只是“帮助写代码”这种泛泛而谈基本可以跳过。好的 description 会明确说清楚“在什么场景下、对什么类型的任务、提供什么具体帮助”。比如“为 React 函数组件生成符合 Airbnb 规范的代码骨架包含 PropTypes 和单元测试”这种一看就知道边界在哪。另外要注意 skills 的依赖。有些 skill 依赖特定的脚本运行环境或者外部工具你装之前要确认自己的环境满足条件。我踩过一次坑装了一个 skill 结果它依赖的 Python 包版本和我环境里的冲突折腾了半天。4.2 安装 skills 的正确姿势skills 的安装方式取决于你用的工具。Claude Code 和 Codex 都有自己的 skills 目录约定。一般来说你把 skill 文件夹放到指定的 skills 目录下agent 启动时会自动扫描。有些工具支持通过命令安装比如从市场直接拉取。安装后一定要验证是否被识别。方法是启动 agent问它“你现在有哪些可用的 skills”或者用工具提供的列表命令。如果装完没被识别排查顺序是目录位置对不对、SKILL.md 格式对不对、frontmatter 有没有语法错误。YAML 对缩进敏感一个 tab 和空格的混用就可能导致解析失败。我建议新手先从官方市场装一两个官方 skill 跑通流程确认整个链路没问题再去折腾社区 skill 和自己开发。这样出问题的时候你能快速定位是环境问题还是 skill 本身的问题。4.3 自己写一个 skill 的完整流程自己写 skill 其实没有想象中那么难难的是把指令写得清晰、无歧义、可执行。我的流程一般是这样的第一步明确这个 skill 要解决什么具体问题。不要写“帮助前端开发”这种大而全的要写“生成符合团队规范的 Vue3 组合式 API 组件”。范围越具体指令越好写效果越稳定。第二步写 SKILL.md 的 frontmatter。name 用简短的英文标识description 用一句话说清楚触发场景。这里有个技巧description 里可以包含一些关键词帮助 agent 做匹配。比如你的 skill 是处理数据库迁移的description 里就应该出现“migration”“schema”“database”这些词。第三步写正文指令。正文要分步骤每步说清楚输入、输出、注意事项。我习惯用有序列表因为 agent 对有序步骤的执行准确率更高。指令里要避免模糊词汇比如“适当地”“合理地”这些词 agent 没法执行。要写成“如果 X 则做 Y否则做 Z”这种确定性表述。第四步加模板和脚本。如果任务涉及固定格式的输出把模板放进去让 agent 直接填充而不是自由发挥。如果涉及重复性的计算或校验写成脚本让 agent 调用比让它自己算靠谱得多。第五步测试和迭代。写完之后用几个典型任务测一遍看输出是否符合预期。不符合的地方回去改指令而不是在对话里临时纠正。这个迭代过程可能要来回几次但改好之后就是一劳永逸。4.4 skills 开发中的几个关键原则写 skill 指令的时候有几个原则我总结下来特别有用。第一是单一职责一个 skill 只干一件事。我见过有人把“写代码 跑测试 提交 git”塞进一个 skill结果 agent 执行到一半就乱了。拆成三个 skill各管一段反而更稳。第二是显式优于隐式。你觉得“显而易见”的东西agent 不一定知道。比如你的项目用 pnpm 而不是 npm这个必须在指令里写明否则 agent 默认用 npm装出来的依赖结构就不对。第三是给例子。指令里附上一两个输入输出的例子agent 的模仿能力很强有例子比没例子准确率高一大截。这个在格式化输出类的 skill 里尤其明显。第四是控制长度。skill 的指令不是越长越好太长会占用大量上下文还可能让 agent 抓不住重点。我的经验是核心指令控制在几百字以内细节放到 resources 里按需引用。5. 实操中的常见问题与排查技巧5.1 skills 不触发或者乱触发怎么办这是最高频的问题。skill 不触发八成是 description 写得不够匹配。排查方法是把你实际的任务描述和 skill 的 description 放一起对比看关键词有没有对上。如果任务描述里说的是“组件”而 description 里写的是“模块”agent 可能就匹配不上。乱触发则是 description 写得太宽。比如你写“处理任何代码相关任务”那 agent 遇到啥都想用这个 skill。解决办法是加限定词把场景收窄。我一般会在 description 里明确写“仅用于 X 场景”给 agent 一个排除信号。还有一个隐藏原因是 skill 之间有冲突。两个 skill 的触发条件重叠agent 不知道该用哪个。这种情况要么合并要么把边界划清楚。我建议在 skill 的指令里加一句“如果任务同时满足 X 和 Y优先使用本 skill”给 agent 一个明确的优先级。5.2 配置类报错的速查表配置问题在 skills 和 agent 使用中占比很高我整理了一个速查表方便你对照排查报错现象可能原因排查动作配置项被忽略key 拼写错误或版本不兼容对照官方文档核对 key检查版本无法加载组织设置认证过期或权限变更重新登录确认组织权限命令找不到PATH 未配置或未全局安装检查 which 输出确认安装路径本地模型连不上endpoint 或模型名不匹配核对端口、base URL、模型名skill 未被识别目录位置或 SKILL.md 格式错误检查目录约定校验 YAML 语法任务执行中断上下文超限或脚本报错查看日志缩短任务或修脚本这张表覆盖了我遇到的大部分情况。实际排查时我习惯从最简单的可能性开始查——先确认路径和拼写再看权限和网络最后才怀疑版本兼容性。这个顺序能帮你少走弯路。5.3 我踩过的几个真实坑说几个具体的。有一次我写了一个代码生成的 skill测试的时候好好的团队里另一个人用就报错。查了半天发现是他的项目目录结构和我不同skill 里的路径是写死的相对路径换个目录就找不到模板了。后来我把路径改成基于 skill 自身位置的动态解析问题解决。这个教训是skill 里不要写死路径要用相对 skill 位置的引用。还有一次是 skill 的脚本在 Windows 上跑不了因为脚本里用了 Linux 特有的命令。跨平台的项目要注意脚本的可移植性能用跨平台工具就用跨平台的实在不行就准备两套脚本按系统切换。另外一个坑是关于 token 消耗的。我一开始把大量参考资料塞进 skill 的正文结果每次触发都吃掉大量上下文长任务跑到一半就没空间了。后来改成正文只放核心指令参考资料放 resources 目录agent 需要时再读。这个改动让我的长任务成功率提升明显。5.4 性能与稳定性的优化经验skills 用多了之后你会发现性能问题主要出在上下文管理上。agent 的上下文窗口是有限的skills 加载得越多留给实际任务的空间越少。所以我的原则是按需加载用完释放。不要让所有 skill 常驻而是让 agent 根据任务动态加载。另一个优化点是缓存。有些 skill 的脚本执行结果是可以缓存的比如依赖检查、环境探测这类。缓存之后重复执行就快了。但要注意缓存的失效策略环境变了缓存要能及时更新。稳定性方面我建议给关键 skill 加失败回退逻辑。比如一个 skill 依赖外部服务服务挂了怎么办指令里要写明回退方案让 agent 不至于卡死。这个在自动化流程里特别重要。6. skills 的进阶玩法与扩展方向6.1 把 skills 组合成工作流单个 skill 解决单点问题多个 skill 组合起来就能解决复杂问题。比如“生成组件 写测试 跑校验 生成文档”这一套可以拆成四个 skill然后用一个编排逻辑串起来。有些 agent 框架支持这种编排你可以定义一个工作流让 agent 按顺序调用各个 skill。组合的时候要注意 skill 之间的数据传递。前一个 skill 的输出要能作为后一个的输入格式要对齐。我一般会在 skill 的指令里明确写清楚“输出格式为 X”这样下游 skill 才能正确解析。6.2 针对特定领域的 skills 定制skills 最大的价值在于领域定制。通用 skill 谁都能用但真正提升效率的是那些针对你具体业务场景定制的 skill。比如你做的是电商可以写一个“生成商品详情页组件”的 skill把你们的商品数据结构、图片规格、文案规范全写进去。这种 skill 别人用不了但对你团队来说价值巨大。定制 skill 的关键是沉淀团队知识。把那些口口相传的规范、踩过的坑、约定俗成的做法全部写进 skill。这样新人来了agent 带着 skill 就能产出符合团队标准的代码省去大量沟通成本。6.3 skills 与 agent 生态的未来结合点从趋势看skills 正在从“单机能力包”往“可共享、可组合、可版本管理”的方向走。未来可能会出现 skills 的包管理生态像 npm 那样你可以 install 一个 skill也可以 publish 自己的 skill。版本管理、依赖解析这些工程化能力会逐步补齐。对个人开发者来说现在积累自己的 skill 库是个不错的时机。一方面能立刻提升自己的效率另一方面等生态成熟了你积累的这些 skill 就是资产。我自己的做法是把常用的 skill 用 git 管理起来每个 skill 一个仓库方便版本追踪和分享。提示如果你打算长期投入 skills 开发建议从一开始就建立命名规范和目录规范。skill 多了之后没有规范会乱成一锅粥找都找不到。6.4 关于 skills 测试的一点经验skills 写完必须测而且要用真实任务测不能用玩具任务。玩具任务太简单掩盖了很多问题。我一般会准备一组回归测试任务每次改完 skill 都跑一遍确认没有破坏已有功能。这个习惯帮我避免了好几次“改 A 坏 B”的事故。测试的时候要关注边界情况。比如输入为空、输入格式错误、依赖缺失这些情况skill 能不能优雅处理。好的 skill 应该有明确的错误提示而不是默默失败或者输出一堆乱码。7. 一些零散但实用的经验补充关于 skills 的命名我建议用动词开头比如generate-component、validate-schema、migrate-database。这样一眼就能看出这个 skill 是干什么的匹配的时候也更容易对上任务描述。关于 skill 的版本管理我习惯在 SKILL.md 的 frontmatter 里加一个 version 字段。每次改动都升版本号配合 git 的 commit 记录回溯问题的时候很方便。团队协作时这个版本号还能帮你确认大家用的是不是同一个版本。关于 skill 的分享如果你要把 skill 给同事用记得把依赖和前置条件写清楚。我见过太多“在我机器上能跑”的情况根源就是环境差异没说明。一个 README 或者 SKILL.md 里的“前置要求”章节能省掉大量沟通。关于调试agent 执行 skill 的过程如果出问题日志是你的第一手资料。大部分工具都会输出执行日志你要学会看日志定位问题。日志里通常会显示 agent 加载了哪个 skill、执行了哪一步、在哪一步失败。看不懂日志的时候把相关片段贴出来搜一下大概率有人遇到过同样的问题。最后说一个心态上的事。skills 这套东西还在早期文档不全、行为不稳定都是常态。遇到问题别急着怀疑自己很多时候是工具本身的坑。多逛社区、多看别人的分享能帮你快速跳过很多弯路。我刚开始折腾的时候一个配置问题卡了一整天后来在社区里发现是版本 bug升级就好了。这种时候信息比技术更重要。这个领域变化很快今天好用的方法明天可能就过时了。保持动手、保持记录、保持分享是我觉得最靠谱的应对方式。