1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套把 AI coding agent 的能力拆成可复用模块的工程化尝试。关键词里同时出现了skills CLI、Claude Code、test-driven-development这三者放在一起指向一个很具体的场景——把让 AI 写代码这件事从每次靠嘴描述需求升级成给 agent 装上一套标准化的技能包。说白了大多数人用 AI 编程工具的方式还停留在对话式打开终端或者编辑器插件敲一段需求等它吐代码不满意就再补一句。这种方式在写一个函数、改一个 bug 的时候够用但一旦项目变大、需求变复杂问题就暴露了——agent 不知道你的代码规范、不知道你的测试习惯、不知道你项目里那些约定俗成的目录结构每次都要重新解释一遍效率极低。agent-skills想解决的就是这个重复解释的问题。它把常见的开发任务抽象成一个个 skill技能每个 skill 是一份结构化的说明文档告诉 agent 在特定场景下应该遵循什么流程、产出什么格式、注意哪些边界。配合skills CLI这样的命令行工具你可以把这些技能安装到 Claude Code 这类 agent 环境里让它在你需要的时候自动加载对应的能力。这篇文章适合三类人看一是已经在用 Claude Code 或者类似 AI coding agent、但觉得它总是不按我的套路来的开发者二是想给自己的团队建立一套 AI 辅助开发规范的技术负责人三是对 agent 工程化感兴趣、想搞清楚skills 到底是个什么东西的探索者。我会从概念拆解讲到实操落地把我在配置和使用过程中踩过的坑一并说清楚。2. agent-skills 到底解决了什么问题2.1 传统 AI 编程的上下文失忆困境用 AI coding agent 写代码最让人抓狂的不是它写不出来而是它写出来的东西不像你写的。你项目里用的是特定的错误处理模式、特定的日志格式、特定的测试框架配置但 agent 默认按它训练数据里最常见的写法来结果就是每次生成完你都要手动改一遍。这个问题的本质是上下文缺失。agent 每次启动都是失忆状态它不知道你的项目历史、不知道你的团队约定、不知道你上一次为什么否定了它的方案。你当然可以在对话里把这些都告诉它但这就变成了每次都要重新培训一个新员工。agent-skills的思路是把这些培训内容固化下来。一个 skill 本质上就是一份写给 agent 看的操作手册里面规定了这个任务什么时候触发、执行步骤是什么、产出物长什么样、有哪些禁忌。比如一个test-driven-development技能会明确告诉 agent先写测试、再写实现、最后重构这个循环而不是让它自由发挥。2.2 skills 与普通 prompt 模板的本质区别很多人会问这不就是 prompt 模板吗我存几个常用的提示词不就行了区别在于触发机制和结构化程度。普通 prompt 模板需要你手动复制粘贴而且是一坨文本agent 只能整体理解。而 skill 是结构化的通常包含元数据名称、描述、触发条件和正文具体指令skills CLI这类工具能根据当前任务自动匹配并加载对应的 skill。打个比方prompt 模板像是你桌上的一叠便签用的时候自己翻skill 像是给 agent 装的一个技能插件它在遇到相关任务时会自动调用。前者靠人后者靠系统。2.3 为什么是现在AI coding agent 的工程化拐点这个仓库出现的时机很有意思。2024 年到 2025 年AI coding agent 从玩具变成了生产力工具Claude Code、Cursor、各种 CLI agent 层出不穷。但工具能力上来了配套的使用规范却没跟上。大家都在摸索怎么让 agent 更听话agent-skills代表了一种方向不改变模型本身而是通过外挂知识库的方式让 agent 的行为可预测、可复用、可传承。这对团队协作尤其重要。一个资深工程师调教好的 agent 使用方式如果能沉淀成 skill新来的同事直接安装就能用不用从头摸索。这是把个人经验变成团队资产的过程。3. skills CLI 的安装与核心命令拆解3.1 环境准备Node 版本与包管理器选择skills CLI是个 Node 工具安装前先确认环境。我实测下来Node 18 以上比较稳Node 20 LTS 是最省心的选择。如果你用的是 macOS建议用nvm管理 Node 版本避免系统自带的旧版本捣乱。# 检查当前 Node 版本 node -v # 如果低于 18用 nvm 装一个 LTS nvm install 20 nvm use 20包管理器方面npm、pnpm、yarn 都能用但我个人偏好 pnpm原因是它装全局包的时候磁盘占用小、速度快。不过如果你只是偶尔用一下npm 也完全够没必要为了这个专门换工具链。提示如果你在公司内网环境npm 源可能需要换成内部镜像否则安装会卡住。这个具体怎么配得看你们公司的规范我不展开。3.2 全局安装与版本验证安装命令很直接# 用 npm npm install -g skills-cli # 或者用 pnpm pnpm add -g skills-cli装完之后验证一下skills --version如果提示command not found八成是全局 bin 目录没加到 PATH 里。npm 的话可以用npm config get prefix看看全局路径在哪然后手动加进环境变量。这个问题在 Ubuntu 上特别常见因为默认的 npm 全局路径有时候不在 PATH 里。3.3 常用子命令一览与使用场景skills CLI的命令设计得比较克制核心就几个命令作用典型场景skills list列出已安装的技能查看当前环境有哪些能力skills search 关键词搜索可用技能找特定领域的 skillskills install 技能名安装技能把技能加到本地skills remove 技能名卸载技能清理不用的skills info 技能名查看技能详情安装前了解它干什么我一般的工作流是先search找到想要的再info看一眼具体内容确认符合预期最后install。别小看info这一步有些 skill 的触发条件写得很宽泛装多了会互相干扰提前看清楚能省不少事。3.4 技能安装目录与项目级 vs 全局级这里有个容易踩的坑skill 装在哪一级。skills CLI通常支持全局安装对所有项目生效和项目级安装只对当前项目生效。全局的适合那些通用技能比如代码审查、提交信息生成项目级的适合跟具体技术栈绑定的比如某个框架的特定写法。项目级安装一般会在项目根目录生成一个配置目录类似.skills/这种记得把它加进版本控制这样团队其他人拉下来就能用同一套技能。全局的则存在用户目录下换机器要重新装。注意如果你在多个项目间切换全局装了一堆技能可能会出现这个项目的 agent 突然按另一个项目的规范写代码的诡异情况。我的建议是通用技能全局装专用技能一律项目级。4. 把 skills 接入 Claude Code 的完整流程4.1 Claude Code 的安装方式选择在讲接入之前先说说 Claude Code 本身怎么装。目前主流有几种方式官方 CLI、VS Code 插件、桌面版。我三种都用过说下各自的适用场景。官方 CLI 最灵活适合习惯终端操作的人能直接执行终端命令跟 skills 的配合也最顺。VS Code 插件的好处是跟编辑器集成改代码的时候不用切窗口。桌面版适合不想碰命令行的用户但灵活性差一些。安装 CLI 的话macOS 和 Ubuntu 的步骤略有不同。macOS 上一般用官方提供的安装脚本或者包管理器Ubuntu 上要注意权限问题可能需要sudo或者配置用户级安装路径。装完之后用claude --version验证。4.2 让 skills 被 agent 识别的配置要点装好 Claude Code 和 skills CLI 之后关键一步是让 agent 知道去哪找技能。这通常涉及一个配置文件告诉 Claude Code技能目录在哪。配置的核心逻辑是Claude Code 启动时会读取某个约定位置的技能定义把它们作为可用工具或者上下文注入。具体路径和格式取决于版本但思路是一样的——你得让 agent 在启动时看到这些技能。我踩过的一个坑是技能装了但 agent 不认。排查下来发现是配置文件里的路径写的是相对路径而 agent 的工作目录跟我预期的不一样。改成绝对路径就解决了。所以配置路径的时候能用绝对路径就别用相对的。4.3 验证技能是否生效的三种方法装完配置完怎么确认真的生效了我总结了三个办法直接问 agent在对话里问你现在有哪些可用技能看它列出来的清单里有没有你刚装的。触发测试故意做一个应该触发该技能的任务观察 agent 的行为是否符合技能定义。比如装了 TDD 技能就让它写个新功能看它是不是先写测试。看日志Claude Code 一般有调试模式能看到它加载了哪些上下文。这个最准确但需要你会看日志。三种方法我建议结合用尤其是第二种因为技能被加载和技能被正确执行是两回事。4.4 多模型环境下的技能兼容性现在很多人不只用 Claude 官方模型还会通过第三方 API 接入其他模型。这里要注意skills 本质上是提示词工程不同模型对同一份技能说明的理解能力不一样。有些技能在 Claude 上跑得很好换到别的模型可能就理解偏了。我的经验是技能说明写得越具体、越结构化跨模型的兼容性越好。那些依赖模型悟性的模糊描述换个模型就废了。所以如果你打算多模型混用skill 的写法要偏指令式而不是引导式。5. 用 test-driven-development 技能跑通第一个闭环5.1 为什么选 TDD 作为入门技能test-driven-development是关键词里明确提到的技能也是最适合拿来验证 skills 机制的一个。原因很简单TDD 有明确的、可观察的行为特征——先写测试、测试失败、写实现、测试通过、重构。这五个步骤如果 agent 真的按技能执行了你一眼就能看出来。相比之下像代码审查这种技能产出质量好坏比较主观不容易判断技能到底有没有起作用。TDD 是天然的验证场景。5.2 技能触发后的实际行为观察我拿一个真实的小需求测试给一个已有的工具函数加参数校验。装了 TDD 技能之后agent 的行为明显变了。没装技能时它会直接改函数体加上 if 判断然后告诉你改好了。装了技能后它先问我要不要写测试然后生成一个测试文件里面是针对参数校验的测试用例跑一遍确认失败再改实现最后再跑一遍确认通过。这个行为差异非常明显。它不再是给我结果而是走流程。这就是 skill 的价值——把方法论固化进 agent 的行为模式。5.3 测试用例生成质量的调优不过默认的 TDD 技能生成的测试用例质量参差不齐。常见问题是只测正常路径不测边界条件断言写得太宽松测了等于没测。我的调优办法是在技能基础上再加一层项目级的补充说明明确要求每个函数至少覆盖正常值、边界值、异常输入三类用例。这个补充可以写在项目的技能配置里也可以直接在对话里强调。实测下来加了这条约束之后测试覆盖率明显提升。5.4 从能跑到好用的迭代思路第一个闭环跑通只是开始。真正让 skills 产生价值需要持续迭代。我的做法是每次 agent 的行为不符合预期就回头改 skill 的定义而不是每次在对话里临时纠正。改完 skill下次它就记住了。这个过程有点像带新人——你不能指望说一次他就永远记住但你可以把要求写进 SOP让他照着做。skill 就是 agent 的 SOP。6. 技能编写与自定义的实战经验6.1 一个 skill 的最小结构自己写 skill 其实不难最小结构就三部分元数据、触发条件、执行指令。元数据包括名称和描述触发条件说明什么情况下该用这个技能执行指令是具体的步骤。--- name: my-custom-skill description: 当需要处理 XXX 任务时使用 --- ## 执行步骤 1. 第一步做什么 2. 第二步做什么 3. 产出物格式要求关键在触发条件要写得精准。写太宽技能到处触发干扰正常流程写太窄该触发的时候不触发等于没装。6.2 触发条件怎么写才精准我的经验是用任务特征而不是关键词来定义触发条件。比如不要写当用户提到测试时触发而要写当任务涉及新增功能或修改现有逻辑且项目配置了测试框架时触发。前者太泛后者有明确的场景边界。另外多个技能之间的触发条件要避免重叠。如果两个技能都声称处理代码质量agent 就不知道该用哪个。这时候要么合并要么把边界划清楚。6.3 把团队规范翻译成技能描述这是我觉得 skills 最有价值的地方。每个团队都有自己的规范提交信息格式、分支命名规则、代码审查清单。这些以前靠文档和口头传承现在可以写成 skill。翻译的时候要注意规范文档是写给人看的skill 是写给 agent 看的。人能从上下文推断的东西agent 不一定能。所以 skill 要写得更笨一点把隐含的前提都显式说出来。比如提交信息用祈使句这种要补充例子否则 agent 可能理解成各种样子。6.4 技能冲突与优先级处理装多了技能冲突是必然的。两个技能对同一件事有不同要求agent 就懵了。处理办法有两个一是合并冲突的技能二是明确优先级。优先级可以通过技能配置里的顺序或者显式的优先级字段来控制。我的建议是尽量合并因为优先级机制依赖 agent 正确理解不如直接消除冲突来得可靠。7. 踩坑记录那些文档里不会写的问题7.1 技能装了但 agent 视而不见这是最常见的坑。原因通常有三个路径配置错误、技能格式不符合规范、agent 版本不支持该技能机制。排查顺序建议从路径开始因为最容易错也最容易改。我遇到过一次是技能文件的 frontmatter 格式有问题YAML 里多了个空格导致解析失败但 CLI 不报错agent 也不提示就是静默不加载。后来用skills info才发现元数据没读出来。所以装完技能一定要用info确认元数据解析正常。7.2 多项目环境下技能串味前面提过全局技能和项目技能混用会导致串味。具体表现是在 A 项目里 agent 按 B 项目的规范写代码。这个问题的根源是技能加载顺序和覆盖规则不清晰。我的解决方案是全局只装跟技术栈无关的通用技能比如提交信息规范所有跟具体项目相关的技能一律项目级安装并且在项目配置里显式声明只加载本项目技能。这样虽然每个项目要单独配但避免了串味。7.3 技能更新后的缓存问题技能更新了但 agent 还在用旧版本。这是缓存导致的。skills CLI一般有缓存机制更新技能后需要手动刷新或者重启 agent。我养成的习惯是每次更新技能后先skills list确认版本变了再重启 Claude Code。别嫌麻烦不然你会对着为什么改了没生效困惑半天。7.4 与第三方 API 模型配合时的注意事项用第三方 API 接入其他模型时skills 的效果会打折扣。原因是这些模型对结构化指令的遵循能力不如官方模型。我的应对策略是把技能说明写得更短、更直接减少需要理解的部分增加照做的部分。另外第三方 API 的上下文窗口可能更小技能装太多会挤占正常对话的空间。这种情况下要精简技能只留最核心的几个。8. 关于 agent-skills 的一些个人判断用了一段时间下来我对agent-skills这类工具的判断是它代表了 AI 辅助开发从个人技巧走向工程规范的方向但现在还处于早期。技能生态不够丰富编写规范也没统一不同工具之间的技能还不能互通。但方向是对的。当 AI coding agent 越来越强瓶颈就从模型能力转移到了如何让模型按我的方式工作。skills 就是解决这个瓶颈的一种尝试。它不一定是最优解但至少提供了一条可操作的路径。我现在的做法是把团队里反复出现的、有明确流程的开发任务逐步沉淀成 skill。不追求一次写完美而是用一次改一次。这个过程本身也是在梳理团队的开发规范一举两得。如果你刚开始接触建议从test-driven-development这种行为特征明显的技能入手先跑通一个闭环建立对 skills 机制的直观理解再考虑自己写。别一上来就搞一堆自定义技能那样只会把自己绕进去。