1. 从agent-skills说起为什么这个方向值得认真对待第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是终于有人把技能这件事从提示词里拎出来当成一个正经的工程对象来管理了。过去大半年我一直在用各种 AI coding agent 干活从最早的补全插件到后来的命令行智能体踩过的坑基本能写一本小册子。最核心的痛点从来不是模型不够聪明而是同一个任务每次都要重新交代一遍上下文——项目用什么测试框架、提交信息怎么写、目录结构有什么约定、哪些文件绝对不能碰。这些东西散落在各种CLAUDE.md、.cursorrules、系统提示词里改一处忘一处团队里每个人还各写各的。agent-skills想解决的就是这个问题。它把技能抽象成一个可复用、可版本化、可组合的单元通过一个skillsCLI 来安装、管理和分发。你可以把它理解成 AI coding agent 的技能包管理器——类似 npm 之于 JavaScript或者 Homebrew 之于 macOS。一个 skill 可以是一段测试驱动开发的规范、一套代码审查清单、一个特定框架的迁移流程甚至是一组终端命令的执行约定。它不绑定某一个具体的 agentClaude Code 能用其他支持技能加载的 agent 也能用。这篇文章适合三类人看一是已经在用 Claude Code 或其他 AI coding agent、但每次都要重复喂规矩的开发者二是想给团队统一 AI 编码规范、又不想靠人肉记忆的技术负责人三是单纯对 agent 工程化感兴趣、想看看技能这层抽象到底怎么落地的人。我会从设计思路讲到实操细节把安装、配置、编写自定义 skill、排查问题这一整条链路都走一遍尽量让你看完就能上手抄作业。需要先说明一点agent-skills本身是一个相对轻量的工具层它的价值高度依赖你往里塞的内容质量。工具再好技能写得稀烂也没用。所以我会花不少篇幅讲怎么写一个好 skill这部分才是真正拉开差距的地方。2. 核心设计思路拆解为什么是技能而不是提示词2.1 提示词管理的三个死结在agent-skills这类工具出现之前大家管理 agent 行为基本靠三种方式每一种都有明显的天花板。第一种是项目根目录的约定文件比如CLAUDE.md、AGENTS.md、.cursorrules。优点是简单扔一个文件进去就行。缺点是它是一坨扁平的文本随着项目变大这个文件会膨胀到几百行模型读起来注意力被稀释人维护起来也痛苦。更要命的是它没法按需加载——你写了一个数据库迁移的规范但当前任务只是改个 CSS模型还是得把这整段读进去浪费上下文窗口。第二种是系统提示词硬编码。有些团队直接改 agent 的启动配置把规范塞进 system prompt。这种方式最稳定但完全不可移植换个 agent 就得重写而且改一次要重启迭代成本极高。第三种是临时粘贴。每次开新会话手动把规范贴进去。这基本等于没有管理纯靠人肉记忆团队协作时灾难现场。这三个死结的共同点是规范和任务没有解耦。规范是长期稳定的任务是短期多变的把两者混在一起必然导致要么规范被稀释要么上下文被浪费。2.2 技能作为独立单元的三个好处agent-skills的核心洞察是把规范拆成独立的、有明确触发条件的技能单元。这个设计带来三个直接好处。按需加载节省上下文。每个 skill 有自己的描述和触发条件agent 在执行任务时先看任务匹配哪个 skill只加载相关的那几个。你写十个 skill一次任务可能只用到两个上下文窗口留给真正重要的代码和推理。这一点在长会话里尤其明显我实测过一个中型项目用 skill 管理后单次任务的 token 消耗能降三成左右。可版本化、可分发。skill 是文件文件就能进 git就能打 tag就能通过 CLI 安装。团队里谁改了规范走正常的代码审查流程历史可追溯。新人入职不用听老人念叨我们这儿提交信息要怎么写装一下 skill 包就行。跨 agent 复用。这是我觉得最有远见的一点。今天你用 Claude Code明天可能换别的 agent但你的 skill 库不用重写。只要目标 agent 支持技能加载协议同一套 skill 就能迁移过去。这相当于给你的团队规范资产上了一层保险不被单一工具绑架。2.3 和 test-driven-development 的关系热搜词里出现了test-driven-development这不是偶然。TDD 是最典型的流程型技能——它规定的不是某段代码怎么写而是先写测试、再写实现、最后重构这个动作序列。这种流程恰恰是 agent 最容易跑偏的地方模型天生倾向于直接给你一坨能跑的代码跳过测试。你把 TDD 写成一个 skill明确告诉 agent在这个项目里任何新功能都必须先产出失败的测试它才会老老实实按流程走。我在实际项目里把 TDD skill 和普通 skill 分开管理因为它的触发频率极高几乎每个功能开发任务都要加载。这种高频 skill 值得单独打磨措辞把什么算一个合格的失败测试这种细节写清楚否则 agent 会写出assert True True这种糊弄人的测试。3. 环境准备与 skills CLI 安装实操3.1 前置条件确认在动手之前先把环境理清楚。agent-skills的 CLI 通常依赖 Node.js 运行时我建议用 LTS 版本18 或 20 都行。检查一下node -v npm -v如果版本太老先升级。macOS 上我习惯用nvm管理 Node 版本Ubuntu 上也是同一套跨平台一致省得记两套命令。# 安装 nvm如果还没有 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置后 nvm install 20 nvm use 20注意不要用系统自带的 Node很多发行版自带的版本太旧装 CLI 时会出现各种诡异的依赖报错。用 nvm 隔离出来的环境最干净。3.2 安装 skills CLI安装命令本身很简单但有几个细节值得说。npm install -g agent-skills # 或者用 pnpm如果你偏好更快的包管理器 pnpm add -g agent-skills装完之后验证skills --version skills --help如果skills命令找不到八成是全局 bin 目录没进 PATH。用npm config get prefix看一下全局安装路径然后把这个路径下的bin加进你的 shell 配置。macOS 的 zsh 用户改~/.zshrcUbuntu 的 bash 用户改~/.bashrc。export PATH$(npm config get prefix)/bin:$PATH改完记得source一下配置文件或者干脆重开一个终端。3.3 初始化项目级技能目录CLI 装好后进到你的项目根目录跑初始化cd your-project skills init这一步会在项目里创建一个技能目录通常是.agent-skills/或者类似的隐藏目录里面放一个清单文件和若干 skill 定义。具体结构取决于版本但核心逻辑是一致的清单文件记录装了哪些 skill、版本是多少skill 目录里放具体内容。我建议把.agent-skills/里的清单文件提交到 git但把缓存或临时生成的文件加进.gitignore。这样团队共享的是装了哪些技能这个事实而不是每个人本地的缓存副本。.agent-skills/cache/ .agent-skills/*.log3.4 安装第一个技能包从社区或官方仓库装一个现成的 skill 试试水skills install tdd-workflow skills listskills list会列出当前项目已安装的所有技能包括名称、版本、触发条件。这一步很关键装完一定要 list 一下确认我遇到过网络问题导致安装看起来成功但实际清单没写入的情况。提示安装第三方 skill 前先skills info name看一下它的描述和权限要求。有些 skill 会声明需要执行终端命令的权限这种要格外谨慎确认来源可信再装。4. 编写自定义 skill从结构到措辞的完整方法4.1 一个 skill 的最小结构现成的 skill 好用但真正体现价值的是你自己写的。一个 skill 文件通常包含几个部分元信息名称、描述、触发条件、正文内容具体规范、可选的示例和反例。--- name: api-error-handling description: 统一后端 API 的错误处理规范适用于所有新增接口 triggers: - 新增 API 接口 - 修改错误处理逻辑 - 编写接口测试 --- # API 错误处理规范 ## 必须遵守 - 所有错误响应使用统一结构{ code, message, details } - code 使用业务错误码不使用 HTTP 状态码代替 - 禁止把内部异常堆栈直接返回给客户端 ## 示例 ...元信息里的triggers是最需要动脑筋的地方。写得太宽skill 会被频繁误加载浪费上下文写得太窄该用的时候用不上。我的经验是用任务动词而不是名词来描述触发条件。新增 API 接口比API好修改错误处理逻辑比错误处理好。因为 agent 判断是否加载 skill靠的是当前任务和触发条件的语义匹配动词能提供更强的信号。4.2 措辞的三个原则写 skill 正文我总结了三条原则都是踩坑踩出来的。第一用祈使句不用描述句。所有错误响应使用统一结构是祈使句agent 会当成指令执行。我们的项目通常使用统一结构是描述句agent 可能理解成这是背景信息可以参考也可以不参考。规范类内容必须用祈使句把必须禁止应该这些词用足。第二给反例不只给正例。模型对不要做什么的遵循度往往比对要做什么更高。你写提交信息用祈使句它可能还是写Added feature。但你补一句禁止使用 Added、Fixed 这类过去式开头它立刻就收敛了。反例是约束力的放大器。第三控制长度一个 skill 只讲一件事。我见过有人把一个 skill 写成两千字的项目开发大全结果 agent 加载后注意力全散了。skill 应该像函数一样职责单一。测试规范一个 skill提交规范一个 skill目录结构一个 skill。需要组合时让 agent 同时加载多个而不是塞进一个巨型 skill。4.3 用 skills CLI 创建和测试skills create api-error-handlingCLI 会生成一个模板文件你往里填内容。填完保存然后测试加载skills test api-error-handling这个命令会模拟一次任务匹配看你的 skill 会不会被正确触发。我强烈建议每写完一个 skill 都跑一下 test尤其是触发条件光靠肉眼判断很容易想当然。如果 test 显示未匹配先检查 triggers 的措辞再检查 description 是否足够具体。有时候问题出在 skill 名称太抽象agent 从名字里提取不到有效信号。5. 与 Claude Code 的集成配置详解5.1 让 Claude Code 识别技能目录agent-skills装好的技能要让 Claude Code 用上需要在 Claude Code 的配置里指向技能目录。具体做法取决于你用的是命令行版还是 VS Code 插件版但核心都是告诉 agent 去哪里找 skill 清单。命令行版通常在项目根目录的配置文件里加一段{ skills: { enabled: true, path: .agent-skills, autoLoad: true } }VS Code 插件版则在插件的设置里找到对应项把技能目录路径填进去。我实测下来autoLoad打开后体验最顺——agent 每次任务开始自动扫描技能清单按需加载不用手动干预。注意不同版本的 Claude Code 配置项名称可能有差异以你本地claude --help或插件设置页显示的实际字段为准。别照抄网上的配置版本对不上会静默失效。5.2 验证集成是否生效配置完别急着干活先验证。开一个 Claude Code 会话给它一个明确匹配某个 skill 触发条件的任务比如帮我新增一个用户查询接口。然后观察它的行为如果它主动提到了你的 API 错误处理规范说明 skill 加载成功。如果没反应按这个顺序排查技能目录路径对不对skills list在项目根目录能不能正常输出Claude Code 的配置有没有语法错误JSON 少个逗号就会整个失效触发条件是不是写得太窄换个更直白的任务描述再试Claude Code 版本是否支持技能加载太老的版本可能没这个能力我踩过最坑的一次是配置文件路径写成了绝对路径换台机器就失效。后来统一改成相对项目根目录的路径跨机器就没问题了。5.3 和其他模型的配合热搜里提到用第三方 API 接入其他模型这块我的建议是技能层和模型层尽量解耦。agent-skills管理的是规范模型负责的是执行两者通过技能加载协议连接。只要目标 agent 支持读取技能目录用哪个模型都能受益。实际操作中如果你通过某种方式把 Claude Code 接到了别的模型上先确认这个链路是否还保留技能加载能力。有些接入方式只是替换了推理后端技能加载逻辑还在那就能用有些则把整个 agent 框架换掉了技能目录就失效了。这个要具体链路具体测没有通用答案。6. 常见问题与排查技巧实录6.1 技能不生效的排查速查表现象可能原因排查方法agent 完全不提规范技能目录路径错误项目根目录跑skills list确认偶尔生效偶尔不生效触发条件太窄放宽 triggers用更通用的任务动词加载了但 agent 不遵守正文用了描述句改成祈使句补反例上下文消耗异常高单个 skill 太长拆分 skill一个只讲一件事换机器后失效配置用了绝对路径改成相对项目根目录的路径安装成功但 list 没有清单文件未写入重装检查目录写权限6.2 三个我踩过的坑坑一skill 名称和触发条件打架。我写过一个叫clean-code的 skill触发条件写的是重构代码。结果 agent 在写新功能时也频繁加载它因为写代码和重构代码在语义上太近。后来把名称改成refactor-checklist触发条件收紧到重构已有代码、消除重复逻辑误触发就没了。名称要具体别用大词。坑二把 skill 当文档写。早期我往 skill 里塞了大量背景说明、设计理由、历史沿革写得像一篇技术文档。结果 agent 加载后真正该执行的规范被淹没在叙述里。后来我定了个规矩skill 正文里背景说明不超过三行其余全是可执行的指令和示例。想写设计理由写到项目 wiki 里去别放 skill。坑三忽略 skill 之间的冲突。有两个 skill 分别规定提交信息用中文和提交信息用英文同时加载时 agent 就懵了。这种冲突在 skill 数量少的时候不明显一旦超过十个就容易撞车。我的做法是定期跑一遍skills list人工审一遍所有触发条件看有没有语义重叠的。重叠的要么合并要么明确优先级。6.3 关于权限的实操心得有些 skill 会声明需要执行终端命令的权限比如自动跑测试、自动格式化代码。这类 skill 威力大风险也大。我的原则是只给来源可信、逻辑透明的 skill 开命令执行权限。自己写的 skill 可以放心开第三方 skill 先读一遍它的内容确认没有奇怪的命令再开。另外命令执行权限最好配合项目级的沙箱或容器使用。我在一个容器化的开发环境里跑这类 skill即使 skill 里有问题影响范围也可控。裸机环境上跑带命令权限的第三方 skill我是不太敢的。7. 把技能库当成团队资产来经营用了一段时间之后我对agent-skills这类工具的看法变了。它表面上是个 CLI实际上是在帮你沉淀团队的编码共识。以前这些共识散在每个人的脑子里、聊天记录里、零散的文档里现在它们变成了可版本化、可审查、可分发的文件。我现在维护技能库的方式是这样的每个 skill 一个文件进 git改动走 PR。新人入职第一件事是skills install装团队技能包第二件事是读一遍所有 skill这比听老人讲两小时规矩高效得多。技能库的更新也有节奏每当团队在 code review 里反复指出同一个问题就说明该把它写成一个 skill 了。有个细节值得单独提定期清理过时的 skill。项目技术栈变了旧的规范 skill 就成了噪音。我每个季度会过一遍技能库把不再适用的删掉或归档。技能库和代码库一样需要持续维护不是装完就一劳永逸的。最后分享一个我最近在试的用法把 skill 和项目的测试套件绑定。TDD skill 里明确要求每次实现前先跑一遍现有测试确认基线是绿的这样 agent 在动手前会先执行测试命令等于强制它了解当前项目状态。这个用法还在打磨但初步效果不错agent 写出破坏性改动的概率明显下降了。