1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛而谈的能力清单或者一份简历模板。但结合热搜词里高频出现的 Claude Code、Codex、agents、plugin 这些词基本可以确定这里说的 skills 是智能体技能体系——也就是给 AI 编程助手agent挂载的一批可复用、可组合的能力模块。你可以把它理解成给一个刚入职的实习生配的“工具包”光有脑子不够还得有螺丝刀、扳手、说明书才能把活干利索。我接触这套东西的起点很朴素用 Claude Code 写代码时发现它每次都要我重复交代同样的规矩比如“提交前跑一遍 lint”“改完文件顺手更新 changelog”“别动 vendor 目录”。重复三次以上我就烦了于是开始琢磨怎么把这些固定动作固化下来。skills 就是干这个的——它把“怎么做某件事”的经验从一次性的对话里抽出来变成 agent 随时能调用的技能。这套体系解决的核心问题有三个。第一是一致性团队里五个人用五个 agent如果没有统一的 skills产出的代码风格、提交规范、测试覆盖会五花八门。第二是可复用一个调优好的“数据库迁移”技能可以在十个项目里反复用不用每次重新教。第三是可组合单个技能像乐高积木agent 根据任务自动拼装比如“读需求→写代码→跑测试→提 PR”这条链路可以由四个技能串起来。适合读这篇的人分三类。刚上手 Claude Code 或 Codex 的新手能搞清楚 skills 到底装在哪、怎么触发已经用了一阵但还在手动重复劳动的中级用户能学会把重复动作沉淀成技能带团队的技术负责人能想明白怎么用 skills 统一团队的 agent 行为。不管你是哪一类下面这些内容都是我在真实项目里踩过坑之后总结的不是照搬文档。2. 核心概念拆解skills、agents、plugin 到底怎么区分2.1 三个词经常被混用但职责完全不同热搜词里 skills、agents、plugin 总是绑在一起出现导致很多人以为它们是同义词。我一开始也糊涂后来在项目里被坑了一次才理清。用一句话概括agent 是干活的人skills 是这个人掌握的技能plugin 是把技能装进 agent 的插槽。打个比方。你开了一家修车铺agent 就是你雇的修车师傅他能思考、能动手。skills 是师傅会的具体手艺比如“换刹车片”“调四轮定位”“读故障码”。plugin 则是你给师傅配的工具箱接口师傅通过这个接口拿到对应的工具和操作手册。没有 plugin师傅空有一身本事却拿不到工具没有 skills师傅拿到工具也不知道该干嘛。具体到 Claude Code 和 Codex 这类工具里agent 是那个接收你指令、规划步骤、调用工具的执行主体。skills 通常以目录或配置文件的形式存在里面写清楚了“这个技能什么时候用、用哪些工具、按什么顺序执行、有什么禁忌”。plugin 则是宿主环境提供的加载机制负责在启动时把 skills 扫描进来、注册到 agent 的能力列表里。2.2 为什么要有 skills 这一层抽象有人会问我直接在对话里把要求说清楚不就行了为什么要多一层 skills这个问题我认真想过答案在于对话是易失的技能是持久的。你在一次对话里说“改完代码记得跑测试”agent 这次记住了下次开新会话它又忘了。而且对话里的指令是模糊的自然语言agent 每次理解可能都有偏差。skills 把这些要求固化成结构化的描述包含触发条件、执行步骤、输入输出约定agent 每次调用都走同一套逻辑结果稳定得多。另一个原因是上下文窗口有限。你把二十条规矩全塞进系统提示词会挤占宝贵的上下文空间而且 agent 容易顾此失彼。skills 是按需加载的只有当任务匹配到某个技能的触发条件时才把它的详细内容拉进来。这就像你不会把整本维修手册背下来而是遇到具体故障时翻到对应那一页。2.3 skills 的典型结构长什么样虽然不同工具的实现细节有差异但一个成熟的 skill 通常包含这几块内容。我用一个“安全提交”技能举例说明。元信息技能名称、版本、作者、适用场景的一句话描述。这部分让 agent 能快速判断“这个技能跟我当前任务有没有关系”。触发条件什么情况下该用这个技能。比如“当用户要求提交代码”或“当检测到 git 仓库有未提交变更”。执行步骤按顺序列出要做的事。安全提交技能里可能是先跑 lint再跑单元测试检查是否有敏感文件被误加最后生成符合规范的 commit message。工具依赖这个技能需要哪些底层工具。比如需要 shell 执行权限、需要读取 git 状态、需要访问测试框架。约束与禁忌明确不能做什么。比如“禁止在测试失败时强行提交”“禁止跳过 pre-commit hook”。示例给出一两个输入输出样例帮助 agent 理解预期行为。这套结构看起来繁琐但写顺了之后一个技能从构思到落地也就十几分钟。关键是第一次写的时候要把边界想清楚不然后面 agent 调用时会出现各种意外行为。3. 环境准备把 skills 跑起来的前置条件3.1 工具链的安装与版本确认在折腾 skills 之前得先把宿主工具装好。热搜词里 claude code 安装、codex 安装、codex 安装教程 出现频率极高说明很多人卡在第一步。我梳理一下我实际用过的路径。Claude Code 的安装官方推荐的方式是通过包管理器。以 macOS 为例如果你有 Homebrew一条命令就能搞定。Windows 用户可以用 WSL或者在 PowerShell 里走对应的安装脚本。安装完之后第一件事是确认版本因为 skills 的加载机制在不同版本间有过调整老版本可能根本不支持。# 确认 Claude Code 版本 claude --version # 确认 Codex 版本 codex --version版本确认这一步千万别跳过。我有一次在旧版本上折腾了半天 skills 目录结构结果发现那个版本压根没有技能加载功能白忙一场。一般来说建议用最近三个月内发布的版本太老的版本不仅缺功能还可能有不兼容的配置格式。3.2 目录结构与配置文件的约定skills 放哪里这是新手最容易懵的地方。不同工具的默认路径不一样但逻辑是相通的有一个全局的技能目录还有一个项目级的技能目录。全局的对所有项目生效项目级的只对当前仓库生效。以我常用的布局为例全局技能放在用户主目录下的配置文件夹里项目级技能放在仓库根目录的一个隐藏文件夹里。加载时工具会先扫全局再扫项目级同名的项目级技能会覆盖全局的。这个覆盖机制很有用比如全局有个通用的“代码审查”技能某个项目有特殊规范就在项目级放一个同名技能覆盖掉。配置文件通常是 JSON 或 YAML 格式里面声明技能目录的位置、加载顺序、是否启用自动触发等。我建议新手先用默认配置跑通一个技能确认能触发之后再改配置不然配置错了很难定位是技能本身的问题还是加载的问题。3.3 国内网络环境下的注意事项热搜词里 claude 国内安装 skills 官方市场、codex 国内能用吗 这类问题很多说明网络环境确实是个现实障碍。我的经验是优先考虑离线安装和本地技能包。具体做法是把技能包提前下载到本地通过本地路径加载而不是依赖在线市场。很多工具支持从本地目录读取技能你只要把技能文件夹放到指定位置重启工具就能识别。这样既绕开了网络问题也让技能版本可控不会因为市场更新导致行为突变。另外如果你用的是第三方 API 接入方式要注意 skills 的触发可能依赖特定的模型能力。有些轻量模型对结构化指令的理解不够好技能触发率会明显下降。这种情况下要么换能力更强的模型要么把技能的触发条件写得更直白一些。4. 从零写一个 skill完整实操流程4.1 选一个值得固化的场景不是所有操作都值得写成 skill。我的判断标准是这个动作是否重复出现、是否有固定套路、是否容易出错。三个都满足才值得投入时间。拿我最近写的一个“依赖升级检查”技能举例。我们项目每周都要升级一批依赖手动做的话要查 changelog、跑兼容性测试、更新锁文件、改版本号步骤多且容易漏。这个场景重复频率高、步骤固定、漏一步就出问题非常适合做成技能。反过来一次性的架构决策、需要大量人工判断的代码重构就不适合。技能擅长的是确定性高的流程不是替代人的思考。4.2 把操作步骤拆解成原子动作选定场景后下一步是拆步骤。拆的时候要细到“agent 能直接执行”的程度不能有模糊表述。我拆“依赖升级检查”时是这么做的。第一步读取当前依赖清单识别出哪些包有新版本可用。第二步对每个待升级的包拉取它的更新日志提取破坏性变更。第三步在隔离环境里安装新版本跑测试套件。第四步如果测试通过更新锁文件和版本号如果不通过记录失败原因并回滚。第五步生成一份升级报告列出成功和失败的包。每一步都要明确输入是什么、输出是什么、失败怎么办。比如第三步的输入是包名和目标版本输出是测试结果失败时要保留现场日志供排查。这些细节写清楚了agent 执行时才不会卡壳。4.3 编写技能描述文件技能描述文件是整个 skill 的核心。我习惯用 Markdown 加 YAML 前置元信息的格式可读性好工具解析也方便。--- name: dependency-upgrade-check version: 1.0.0 description: 检查并安全升级项目依赖自动跑兼容性测试 triggers: - 升级依赖 - 检查依赖更新 - dependency upgrade tools: - shell - file-read - file-write constraints: - 测试未通过时禁止提交变更 - 禁止跳过锁文件更新 ---元信息下面是正文用自然语言描述执行逻辑。这里有个技巧用祈使句不用陈述句。写“读取依赖清单”而不是“依赖清单会被读取”。祈使句对 agent 的指令性更强触发更稳定。正文里还要包含异常处理。比如“如果拉取更新日志失败重试两次仍失败则跳过该包并记录”。这些边界情况不写agent 遇到时可能就卡住或者做出意外操作。4.4 本地测试与迭代技能写完不能直接上生产得先测。我的测试方法是准备三个场景正常场景、边界场景、异常场景。正常场景就是一切顺利的情况验证技能能跑通。边界场景比如依赖清单为空、所有包都是最新版看技能会不会出错。异常场景比如测试故意失败、网络中断看技能能不能正确回滚和记录。测试时我会盯着 agent 的每一步输出看它有没有理解偏差。经常出现的情况是我写的步骤在人类看来很清楚但 agent 理解成了另一个意思。这时候就要回去改描述把歧义消掉。一般迭代两三轮技能就稳定了。5. 技能组合与工作流编排5.1 单个技能的天花板单个技能能解决的问题有限。真正体现威力的是把多个技能串成工作流。比如“接收需求→写代码→自测→提交→通知”这条链路可以拆成五个技能agent 根据当前进度自动切换到下一个。我做过一个实验把代码提交前的检查拆成三个独立技能语法检查、测试执行、提交信息生成。单独用的时候每个技能各干各的。串起来之后agent 会在语法检查通过后自动触发测试测试通过后自动生成提交信息整个流程一气呵成我只需要在最后确认一下。5.2 技能之间的数据传递组合技能时最大的坑是数据传递。技能 A 的输出怎么变成技能 B 的输入这个衔接如果没设计好agent 会在中间卡住。我的做法是约定统一的中间格式。比如所有技能的输出都写成 JSON包含 status、data、error 三个字段。status 表示成功失败data 放具体结果error 放错误信息。下一个技能读取上一个技能的 JSON从 data 里取自己需要的东西。这样解耦之后技能可以自由替换只要遵守同样的输出格式就行。5.3 用 plugin 机制管理技能集当技能数量多起来之后手动管理目录会很乱。这时候 plugin 机制就派上用场了。plugin 可以理解成一个技能包把相关的技能打包在一起统一版本、统一加载。比如我把所有跟“代码质量”相关的技能打成一个 plugin包含 lint 检查、测试执行、覆盖率分析、安全扫描。项目里只需要引入这一个 plugin就能获得全套代码质量能力。升级的时候也是整体升级不用担心某个技能版本对不上。plugin 的配置文件里可以声明依赖关系比如“代码质量 plugin 依赖基础工具 plugin”。加载时工具会自动解析依赖按顺序加载。这个机制在团队协作里特别有用新人拉下代码配置好 plugin 列表所有技能自动就位。6. 常见问题与排查技巧实录6.1 技能不触发怎么办这是最高频的问题。agent 该用技能的时候没用或者用了错的技能。排查思路按顺序来。先看触发条件写得够不够明确。如果触发词太泛比如只写“检查”agent 可能在任何检查场景都触发它。如果太窄又可能匹配不上。我的经验是触发词要覆盖用户可能的多种表述同时加上场景限定。再看技能是否被正确加载。有些工具启动时只加载全局技能项目级技能需要显式启用。检查配置文件里的加载路径对不对技能目录的权限对不对。最后看模型能力。前面提过轻量模型对结构化指令的理解有限可能识别不出触发条件。换个能力强的模型试试如果换了就好那就是模型的问题。6.2 技能执行到一半失败技能执行中途失败通常是某个步骤的输入不符合预期。这时候要看 agent 的中间输出定位是哪一步出的问题。我遇到过一次技能在“读取配置文件”这步失败原因是配置文件路径写的是相对路径而 agent 的工作目录跟我想的不一样。改成绝对路径就好了。这个坑很典型凡是涉及文件路径的地方尽量用绝对路径或者基于项目根目录的路径别依赖当前工作目录。还有一种情况是工具权限不足。技能需要执行 shell 命令但 agent 没有拿到 shell 权限执行到那一步就卡住。检查工具的权限配置确保技能声明的工具依赖都能满足。6.3 技能之间互相干扰多个技能同时启用时可能出现互相干扰。比如技能 A 改了某个文件技能 B 又去读那个文件读到的就是改过的版本导致行为异常。解决办法是明确技能的副作用。如果一个技能会修改文件就在描述里写清楚“本技能会修改 X 文件”让 agent 在调度时知道要串行执行而不是并行。另外尽量让技能保持幂等同一个技能执行多次和执行一次结果一样这样即使重复触发也不会出问题。6.4 常见问题速查表问题现象可能原因排查方向解决方式技能完全不触发触发条件不匹配检查触发词和场景描述放宽或收紧触发条件技能加载失败路径或权限问题检查配置文件和目录权限修正路径补足权限执行中途卡住输入不符合预期查看中间输出定位步骤修正输入格式或路径多技能冲突副作用未声明检查技能是否修改共享资源声明副作用改为串行触发率低模型理解能力不足换模型对比测试换强模型或简化描述7. 团队协作中的 skills 管理经验7.1 技能版本控制团队里多人维护技能时版本控制是必须的。我把技能目录纳入 git 管理每次修改都走正常的代码审查流程。技能描述文件的改动也要 review因为一个措辞变化可能影响 agent 的行为。版本号我遵循语义化版本规范。触发条件或执行逻辑有破坏性变更时升主版本新增功能升次版本修 bug 升补丁版本。这样团队成员升级技能时能清楚知道有没有破坏性变更。7.2 技能文档与新人上手技能写多了之后得有文档说明每个技能干嘛用的、怎么触发、有什么坑。我在项目里维护一个技能索引文件列出所有可用技能及其一句话说明。新人来了先看这个索引知道有哪些能力可用再深入看具体技能。另外我会给每个技能配一个最小可运行示例新人可以照着示例跑一遍直观感受技能的效果。这比看描述文件快得多也更容易建立信心。7.3 技能评审的检查点团队评审技能时我关注这几个点。触发条件是否清晰无歧义执行步骤是否完整覆盖正常和异常路径副作用是否声明是否有测试用例文档是否齐全。这几个点都过了技能才能合并进主分支。评审时特别容易忽略的是异常路径。大家写技能时都想着顺利情况但实际运行中异常才是常态。一个没有异常处理的技能在生产环境里就是个定时炸弹。8. 我踩过的几个典型坑第一个坑是技能写得太大。我一开始想把整个“发布流程”写成一个技能结果这个技能有二十多个步骤agent 执行到后面经常忘记前面的上下文行为变得不可预测。后来拆成五个小技能每个只干一件事稳定性立刻上来了。技能粒度宁可小不要大这是血泪教训。第二个坑是依赖隐式的环境状态。有个技能假设当前目录一定是项目根目录结果在子目录里触发时就找不到文件。后来所有技能都改成基于环境变量或配置读取项目根目录不再假设工作目录。凡是依赖外部状态的地方都要显式获取不能想当然。第三个坑是忽略技能的加载顺序。有些技能之间有依赖A 技能必须在 B 技能之前加载。我一开始没注意顺序导致 B 技能引用了 A 技能还没注册的工具直接报错。后来在配置里显式声明加载顺序问题就解决了。第四个坑是测试覆盖不足。我有个技能在本地测试都通过上了 CI 就失败原因是 CI 环境的 shell 版本跟本地不一样某个命令的参数不兼容。从那以后技能测试必须覆盖目标运行环境不能只在本地跑通就完事。9. 技能体系的扩展方向技能体系跑顺之后可以往几个方向扩展。一个是技能市场团队内部建一个共享的技能仓库大家把自己写的技能贡献上去互相复用。我们团队现在有三十多个技能覆盖了从代码生成到部署的各个环节新人来了直接挑现成的用。另一个方向是技能与 CI/CD 集成。把技能挂到流水线上代码提交时自动触发相关技能做检查。这样技能不只是 agent 的辅助而是整个研发流程的一部分。我们现在的流水线里就嵌了几个技能提交前自动跑不通过就拦住。还有一个方向是技能的效果度量。记录每个技能的触发次数、成功率、平均耗时用数据判断哪些技能有价值、哪些需要优化。这个度量做起来不难但能帮团队把精力花在刀刃上。我个人在实际操作中的体会是skills 这套东西的价值不在于技术多高深而在于它强迫你把模糊的经验变成明确的流程。写技能的过程其实就是梳理自己工作方法的过程。很多平时没意识到的坏习惯在写技能描述时会被暴露出来。所以哪怕你暂时不用 agent单纯把日常工作拆成技能描述也能帮你理清思路。最后分享一个小技巧写技能时先别管格式用大白话把步骤口述一遍录下来再整理成结构化描述这样写出来的技能最贴近真实操作agent 执行起来也最顺。