1. 从 agent-skills 说起为什么“技能包”正在成为 AI 编码代理的分水岭第一次看到agent-skills这个项目名的时候我脑子里蹦出来的不是某个具体工具而是一个很朴素的问题我们给 AI 编码代理AI coding agents喂了那么多上下文、规则文件、提示词模板为什么它还是经常“会写代码但不会干活”答案其实藏在“技能”这两个字里。模型本身的能力是通用的、泛化的它知道 Python 怎么写、测试怎么跑、Git 怎么提交但它不知道你这个团队在什么场景下该调用哪套流程、按什么顺序执行、遇到什么信号该停下来。agent-skills这类项目要解决的就是把“通用能力”封装成“可复用、可组合、可被代理自动调用的技能单元”让 AI coding agents 从“会聊天的代码生成器”变成“能按流程干活的执行体”。我接触这套东西的契机很实际团队里用 Claude Code 做日常开发已经有一段时间了test-driven-development这种工作流我们反复在提示词里手写写到最后发现每个人写的版本都不一样新人接手完全靠口口相传。后来看到agent-skills配合skills CLI的思路才意识到问题的本质不是提示词写得好不好而是技能没有被工程化。这篇文章适合三类人看一是已经在用 Claude Code、Cursor 这类 AI coding agents但总觉得“差点意思”的开发者二是想给团队建立统一 AI 工作流的技术负责人三是刚入门、想搞清楚skills CLI到底解决什么问题的新手。我会从设计思路讲到实操落地把踩过的坑和能直接抄的配置都摊开说。2. agent-skills 的整体设计与思路拆解2.1 技能到底是什么把提示词从“一次性消耗品”变成“可安装资产”传统做法里我们给 AI 编码代理的指令基本是“一次性”的写在对话里、写在CLAUDE.md里、写在某个.cursorrules里。问题是这些东西要么太散要么太死。散的时候每次都要重复交代死的时候改一处要动全身。agent-skills的核心抽象是一个技能 一段有明确触发条件、明确输入输出、明确执行步骤的能力封装。它把“怎么做 TDD”“怎么发一个版本”“怎么排查一个线上 bug”这类流程从散落的提示词里抽出来变成一个独立目录、一份描述文件、若干可执行脚本。代理在需要的时候按需加载不需要的时候完全不占用上下文。这个设计的关键价值在于三点。第一是上下文经济AI 代理的上下文窗口是稀缺资源把所有技能一股脑塞进去是浪费按需加载才是正解。第二是可组合性一个“写测试”的技能可以和一个“重构”的技能串起来形成更复杂的工作流。第三是可版本化技能是文件文件能进 Git能 review能回滚这就把 AI 工作流纳入了正常的工程管理。我个人的判断是这套思路真正的分水岭意义在于它承认了“提示词工程”正在向“技能工程”演进。前者靠个人手感后者靠团队协作。2.2 为什么是 CLIskills CLI 在整条链路里的位置很多人第一次听说skills CLI会疑惑我直接手动建目录、写文件不行吗为什么还要一个命令行工具能但会很痛苦。手动管理技能目录的问题在于安装、更新、卸载、依赖解析、跨项目复用这些事一旦超过三五个技能就会失控。skills CLI承担的角色本质上和npm、pip是一样的——它是技能的包管理器。具体来说它解决了几件事安装与分发一条命令把某个技能装到当前项目或全局环境不用手动复制粘贴。版本管理技能可以带版本号团队可以锁定某个版本避免“昨天还好好的今天就不对了”。发现与列举skills list这类命令让你清楚当前环境里有哪些技能可用避免重复造轮子。与代理集成CLI 负责把技能放到代理能识别的路径下代理负责在合适的时机调用。提示CLI 本身不“执行”技能它只负责管理。真正执行技能的是 AI coding agent。把这两者的职责分清楚后面排查问题会轻松很多。2.3 和 Claude Code 的关系技能是代理的“外挂大脑”Claude Code 这类 AI coding agent 的强项是理解自然语言、操作终端、读写文件。但它的短板也很明显它不知道你的项目约定不知道你团队的测试规范不知道你发布流程里的那些“潜规则”。agent-skills补的正是这块。你可以把它理解成给代理装了一套“外挂大脑”当代理识别到当前任务是“写一个新功能”时它去加载test-driven-development技能按技能里定义的“先写失败测试 → 再写实现 → 再重构”的顺序执行而不是凭感觉乱写。这里有个容易被忽略的点技能不是让代理变聪明而是让代理变稳定。聪明是模型的事稳定是工程的事。agent-skills做的是后者。3. 核心细节解析与实操要点3.1 一个技能目录里到底有什么虽然不同实现细节会有差异但一个典型的技能目录结构大致是这样的skills/ test-driven-development/ SKILL.md # 技能描述何时触发、做什么、怎么做 scripts/ # 可执行脚本 run-tests.sh templates/ # 模板文件 test-template.py references/ # 参考资料 tdd-notes.mdSKILL.md是整个技能的灵魂。它通常包含几块内容触发条件什么情况下该用这个技能、执行步骤一步步做什么、注意事项哪些坑不能踩、示例输入输出长什么样。我踩过的一个坑是一开始把SKILL.md写成了长篇大论的教程结果代理加载后反而抓不住重点。后来改成“短描述 明确步骤 少量示例”的结构效果立刻好了很多。技能描述不是给人读的文档是给代理读的指令简洁和明确比详尽更重要。3.2 触发条件怎么写才靠谱触发条件是技能设计里最微妙的部分。写得太宽代理动不动就加载浪费上下文写得太窄该用的时候用不上。我的经验是触发条件要围绕任务意图而不是关键词来写。比如test-driven-development的触发条件与其写“当用户提到测试时”不如写“当任务是新增功能或修改现有行为且需要保证可验证性时”。前者会被“帮我看看这个测试为什么失败”这种排查类任务误触发后者则更精准。另一个技巧是给触发条件加反例。明确写出“以下情况不要使用本技能”能显著降低误触发率。这一点在团队协作里尤其重要因为不同人对同一个技能的理解偏差往往就体现在边界情况上。3.3 技能之间的依赖与组合单个技能能解决的问题有限真正的威力在于组合。比如一个完整的“开发一个新功能”流程可能是requirement-clarification先把需求问清楚test-driven-development按 TDD 写测试和实现code-review自查代码质量commit-convention按规范提交这些技能之间有先后依赖也有数据传递。agent-skills的设计里技能可以通过约定好的文件路径或输出格式来传递信息。比如 TDD 技能产出的测试文件会被 code-review 技能读取。注意技能组合不要贪多。我见过有人把十几个技能串成一条链结果代理在中途就“迷路”了。三到五个技能的链路是比较舒服的区间超过这个数量建议拆成多个阶段中间让人工介入确认。3.4 与 test-driven-development 的深度结合test-driven-development是热词里出现频率很高的一个也是最适合做成技能的流程之一。原因很简单TDD 的步骤极其明确红-绿-重构三步走天然适合被封装。把它做成技能后代理的行为会变得可预测先写一个会失败的测试运行确认它失败再写最小实现让它通过最后重构。每一步都有明确的“完成信号”代理不会跳步。我实测下来TDD 技能最大的价值不是让代理写出更好的测试而是强制代理慢下来。没有技能约束时代理倾向于一口气写完所有代码再补测试这时候测试往往是“为了通过而写”的。有了技能约束测试先行代码质量明显不一样。4. 实操过程与核心环节实现4.1 环境准备从零把 skills CLI 跑起来假设你已经在用 Claude Code环境准备大致分几步。这里以常见的类 Unix 环境为例Windows 用户建议在 WSL 里操作避免路径和权限的坑。第一步确认基础环境。Node.js 版本建议 18 以上很多 skills CLI 的实现依赖较新的运行时特性。node -v npm -v第二步安装 skills CLI。具体包名以你使用的实现为准常见形式是全局安装npm install -g skills-cli第三步验证安装skills --version skills --help如果--help能正常列出子命令说明 CLI 本身没问题。接下来就是把它和你的 AI coding agent 对接。4.2 初始化项目级技能目录我强烈建议项目级技能优先于全局技能。原因很实际不同项目的技术栈、规范、流程都不一样全局技能容易“水土不服”。在项目根目录执行初始化skills init这通常会创建一个skills/目录和一个配置文件比如skills.json或.skillsrc。配置文件里记录当前项目安装了哪些技能、版本是多少。然后安装第一个技能以 TDD 为例skills install test-driven-development安装完成后检查目录结构确认SKILL.md和脚本都在位。这一步别偷懒我遇到过安装“成功”但文件没落盘的情况多半是权限或路径问题。4.3 让 Claude Code 识别并调用技能CLI 装好了不代表代理会用。关键一步是让代理知道技能的存在和调用方式。常见做法有两种一种是在项目的代理配置文件比如CLAUDE.md里加一段说明告诉代理“本项目使用 agent-skills 管理技能技能位于skills/目录执行任务前先检查是否有匹配的技能”。另一种是依赖 CLI 提供的集成命令自动把技能索引注入到代理能读取的位置。具体命令看实现常见的是skills sync我个人的偏好是两者结合用sync保证索引是最新的同时在CLAUDE.md里写清楚调用约定。这样即使索引出问题代理也能靠约定找到技能。4.4 一个完整的 TDD 技能执行现场假设现在要让代理实现一个“用户注册时校验邮箱格式”的功能。有了 TDD 技能后整个流程是这样的代理先识别任务意图判断这属于“新增功能”触发test-driven-development技能。然后它读取SKILL.md按步骤执行。第一步写失败测试。代理会创建一个测试文件内容大致是def test_register_rejects_invalid_email(): result register_user(not-an-email) assert result.success is False assert invalid email in result.message第二步运行测试确认失败。代理执行测试命令看到红色确认测试确实在测一个还不存在的功能。第三步写最小实现。代理只写让测试通过的最少代码不提前优化。第四步运行测试确认通过。绿色。第五步重构。代理检查代码有没有重复、命名是否清晰做小步调整每步都重跑测试。整个过程里代理的每一步都有明确的“完成信号”不会跳步也不会一口气写完再补测试。这就是技能带来的稳定性。4.5 参数与配置的取舍逻辑技能配置里有几个参数值得单独说。超时时间脚本类技能要设合理的超时太短会误杀太长会卡住整个流程。我的经验值是单个脚本步骤 60 到 120 秒测试类可以放宽到 300 秒。上下文预算技能加载会占用上下文要控制单个技能的描述长度。我一般把SKILL.md控制在 500 到 1500 字之间超过就拆成主描述加引用文件。失败重试不是所有步骤都适合重试。测试失败重试没意义但网络类操作重试有意义。这个要在技能里明确写清楚别让代理自己猜。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。排查顺序建议这样走先确认技能是否真的被代理“看到”了。检查索引文件或CLAUDE.md里的说明是否包含该技能。再看触发条件是不是写得太窄导致代理判断不匹配。最后看任务描述本身是不是太模糊代理根本没识别出意图。我遇到过一次很典型的情况技能装好了索引也对但就是不触发。最后发现是SKILL.md里的触发条件用了太多专业术语而我在对话里用的是大白话语义对不上。把触发条件改得更口语化后问题解决。5.2 技能触发了但执行到一半卡住多半是脚本问题。先手动跑一遍技能里的脚本看是不是脚本本身有 bug。如果脚本没问题再看是不是超时设置太短。还有一种情况是脚本依赖了某个环境变量或工具而代理执行时的环境和你的终端环境不一样。提示调试技能脚本时养成在脚本开头打印当前工作目录和环境关键变量的习惯。这个习惯帮我省了无数次排查时间。5.3 多个技能互相干扰技能多了之后冲突是难免的。典型表现是代理同时加载了两个技能步骤互相打架。解决办法有两个一是给技能加优先级高优先级的先执行二是在触发条件里写清楚互斥关系明确“使用本技能时不要使用 X 技能”。我倾向于第二种因为优先级是隐式的容易让人困惑而互斥关系写在技能描述里是显式的团队里谁看都明白。5.4 常见问题速查表问题现象可能原因排查方向解决建议技能完全不触发索引未同步 / 触发条件过窄检查索引文件与 SKILL.md重新 sync放宽触发条件触发后中途卡住脚本报错 / 超时过短手动跑脚本看日志修脚本调超时多技能冲突触发条件重叠检查各技能触发描述加互斥说明或优先级技能更新不生效缓存未刷新检查版本号与缓存目录重新安装或清缓存代理“假装”执行技能描述太抽象检查 SKILL.md 步骤是否可执行把步骤改写成具体动作5.5 几个只有踩过才知道的坑第一个坑技能描述里不要写“尽量”“酌情”这类模糊词。代理会把它理解成“可以不做”。要写就写“必须”“如果 X 则 Y”。第二个坑脚本的退出码要规范。成功返回 0失败返回非 0代理靠这个判断步骤是否完成。我见过脚本失败也返回 0 的结果代理以为成功了继续往下走最后产出全是错的。第三个坑别把密钥写进技能文件。技能会进 Git会分享密钥写进去就是事故。用环境变量在技能描述里说明需要哪些变量。第四个坑技能要写测试。听起来有点绕但技能本身也是代码也会坏。给关键技能写个简单的冒烟测试改完之后跑一下能省很多事。6. 把技能工程化之后我的真实体会用agent-skills这套思路管理 AI coding agents 一段时间后最大的变化不是效率提升了多少而是团队里关于“AI 该怎么用”的争论变少了。以前每个人都有自己的提示词习惯谁也说服不了谁。现在技能是文件是代码可以 review可以讨论可以迭代。争论从“我觉得应该这样”变成了“这个技能的触发条件是不是该改改”性质完全不一样。另一个体会是技能不是越多越好。我一开始很兴奋装了十几个技能结果代理经常在加载技能上浪费上下文反而变慢。后来砍到五六个核心技能每个都打磨得比较扎实整体体验反而更好。技能的价值在于质量不在于数量。如果你刚开始接触我的建议是从一个技能做起就选test-driven-development。它步骤明确、收益直观、容易验证。跑通一个之后你对整套机制的理解会清晰很多再扩展就顺理成章了。