1. 从 agent-skills 说起为什么我们需要给 AI 编程助手装上“技能包”第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是把 AI coding agent 从“什么都懂一点、什么都不精”的通才往“按需加载专业技能”的方向推吗事实也确实如此。agent-skills本质上是一套面向 AI 编程代理的技能组织方案它通过一个叫skills CLI的命令行工具把可复用的技能模块skills注入到 Claude Code 这类 AI coding agent 的工作流里让代理在特定任务上表现得像一个有经验的专项工程师而不是一个泛泛而谈的聊天机器人。如果你最近在折腾 Claude Code不管是claude code 安装、vscode配置claude code还是ubuntu配置claude code、mac安装claude code你大概率已经体会过一件事默认状态下的 AI 代理写个简单函数还行一旦涉及多步骤、有约束、需要遵循特定规范的工程任务它就开始“自由发挥”了。agent-skills想解决的就是这个问题——把“怎么做才对”这件事从每次对话里临时交代变成可沉淀、可复用、可版本管理的技能资产。这篇文章适合三类人看第一类是把 Claude Code 当日常开发工具、想让它更听话的工程师第二类是在研究 AI coding agents 架构、想知道技能注入这套机制怎么落地的人第三类是刚接触skills CLI、想找一个能直接抄作业的实操参考的新手。我会从设计思路讲到具体操作再到踩坑记录尽量把每个“为什么这么设计”都讲清楚。2. agent-skills 的整体设计与思路拆解2.1 核心问题AI 代理的“知识”和“技能”是两回事很多人把 AI 代理的能力笼统地理解成“模型强不强”。但实际用下来你会发现模型知识储备和任务执行技能是两个维度。模型可能知道 TDDtest-driven-development的全部理论但让它在一个具体项目里按 TDD 流程走它未必会主动先写测试、再写实现、最后重构。它知道的东西和它在特定上下文里稳定执行的动作中间隔着一道鸿沟。agent-skills的设计出发点就是填这道鸿沟。它把“技能”定义成一种结构化的、可被代理加载的指令集合通常包含触发条件、执行步骤、约束规则和验证方式。代理在遇到匹配的任务时加载对应技能按照技能里定义的流程走而不是凭模型的“直觉”走。这个思路和人类团队里的 SOP标准作业程序非常像——新人不一定懂为什么但照着 SOP 走产出质量的下限是有保证的。2.2 为什么用 CLI 而不是插件或纯配置文件skills CLI选择命令行作为主要交互方式这个决策我觉得挺务实。原因有几个一是 CLI 天然适合做技能的安装、卸载、列出、更新这类操作和包管理器的心智模型一致二是 CLI 可以跨编辑器、跨终端环境工作不管你是claude code for vs code还是纯终端里跑claude code使用技能管理逻辑是统一的三是 CLI 容易做版本控制和脚本化方便把技能集纳入 CI 或者团队共享流程。相比之下如果做成编辑器插件就会被绑定在特定 IDE 上如果做成纯配置文件又缺少动态管理和发现能力。CLI 是个折中点既保持了轻量又有足够的操作能力。这一点在claude code vscode插件配置解释这类场景里尤其明显——插件负责交互CLI 负责能力供给职责分离。2.3 技能的组织粒度为什么不是一个大而全的提示词一个常见的误区是把所有指令塞进一个巨大的系统提示词里。agent-skills没有这么做而是把技能拆成独立模块。这样做的好处是按需加载减少上下文污染每个技能可以独立迭代不会牵一发动全身技能之间可以组合形成针对复杂任务的技能链。打个比方这就像做菜。你不会把川菜、粤菜、烘焙的所有菜谱一次性背下来再进厨房而是根据今天要做什么菜翻对应的菜谱。agent-skills就是那个菜谱架skills CLI就是帮你把菜谱抽出来、放回去的管理员。这个类比虽然糙但能帮你快速理解它的定位。3. 核心细节解析与实操要点3.1 技能模块的典型结构虽然不同技能的细节不一样但一个合格的技能模块通常包含这几块内容元信息技能名、版本、适用场景、触发条件什么任务该加载它、执行流程分步骤的指令、约束与禁忌不能做什么、验证标准怎么判断做完了、做对了。这五块缺一不可尤其是约束和验证很多人在写技能时容易忽略结果技能加载了但代理还是跑偏。我个人的经验是执行流程要写得足够“笨”笨到像给一个刚入职的实习生看。不要写“优化代码结构”这种模糊指令要写“检查函数是否超过 50 行如果超过按职责拆分为子函数每个子函数只做一件事”。代理对模糊指令的解读空间很大你越具体它越稳定。3.2 skills CLI 的常用操作与参数skills CLI的核心操作围绕技能的发现、安装、启用、禁用展开。下面这张表是我整理的高频操作对照方便你快速上手操作类型典型命令形态使用场景注意事项列出可用技能skills list查看当前环境有哪些技能注意区分全局技能和项目级技能安装技能skills install name引入新技能确认来源可信避免引入冲突技能启用技能skills enable name让代理在任务中加载该技能启用过多会稀释上下文禁用技能skills disable name临时关闭某技能排查问题时先禁用可疑技能查看技能详情skills info name了解技能内容和依赖安装前必看提示技能不是越多越好。我实测下来同时启用超过 8 个技能代理的指令遵循度会明显下降因为上下文里塞了太多互相竞争的规则。按任务类型分组启用是更稳的做法。3.3 技能与模型选择的关系这里要提一个很多人关心的问题claude code harness可以不登录用其他模型吗以及使用cc switch 接入 deepseek v4, qwen, glm等模型这类操作。技能层和模型层是解耦的agent-skills定义的是“怎么做”模型提供的是“谁来执行”。理论上只要模型能理解并遵循结构化指令技能就能生效。但实际体验上不同模型对技能指令的遵循度差异很大指令遵循能力强的模型技能效果更稳定。所以我的建议是技能设计要尽量降低对模型“悟性”的依赖把关键约束写成显式的、可检查的规则。这样即使换模型技能的下限也能保住。这也是为什么test-driven-development这类技能特别适合做成 agent-skills——TDD 的流程本身就是高度结构化的先写测试、跑测试看失败、写实现、跑测试看通过、重构每一步都有明确的验证点模型很难“糊弄”过去。4. 实操过程与核心环节实现4.1 环境准备从安装 Claude Code 到接入 skills CLI不管你是在ubuntu 安装claude code还是mac安装claude code前置步骤大同小异。先把 Claude Code 本身装好确认claude code使用正常再引入skills CLI。这里我不展开具体的安装命令细节因为不同平台和版本会有差异claude code官方文档链接里的说明是最权威的建议以官方为准。我要强调的是安装后的验证环节装完先跑一个最简单的任务确认代理能正常响应再动技能配置。很多人一上来就装一堆技能结果出问题了分不清是安装问题还是技能冲突。环境准备阶段有个容易被忽略的点claude code 注册账号和不注册有啥不同。简单说注册账号通常能获得更完整的功能和额度管理不注册可能在功能上有阉割。如果你只是本地测试技能效果不注册也能跑通基本流程如果要长期用、要团队协作注册是更稳妥的选择。这个判断依据是你的使用场景不是绝对的。4.2 编写第一个技能以 TDD 为例我拿test-driven-development来演示一个技能从设计到落地的完整过程。为什么选它因为 TDD 流程清晰、验证点明确是检验技能机制的好样本。第一步定义触发条件。这个技能应该在“用户要求实现新功能”或“用户要求修复 bug”时加载。触发条件要写得具体避免在纯咨询类对话里误触发。第二步写执行流程。我把它拆成五个阶段理解需求先用一句话复述要实现的功能确认理解无误。写失败测试编写一个测试用例描述期望行为此时测试应该失败。运行测试确认失败执行测试确认它确实失败且失败原因是功能未实现而不是测试本身写错。写最小实现编写刚好能让测试通过的代码不多写。运行测试确认通过然后重构测试通过后在测试保护下重构代码每次重构后重跑测试。第三步写约束。比如“禁止在测试通过前编写超出测试范围的代码”“禁止跳过运行测试的步骤”“重构阶段不得改变外部行为”。第四步写验证标准。所有测试通过、代码覆盖率不低于设定阈值、无新增 lint 警告。这个技能写完后用skills CLI安装并启用然后给代理一个真实的小任务测试。我实测下来加载了 TDD 技能的代理确实会先写测试而不是直接甩一大段实现代码。这个行为改变是肉眼可见的。4.3 技能组合处理复杂任务时的编排单个技能解决单点问题复杂任务需要技能组合。比如一个“新增 API 接口”的任务可能同时需要 TDD 技能、API 设计规范技能、错误处理技能。这时候就涉及技能编排哪些技能先加载哪些后加载冲突时以谁为准。我的做法是给技能定义优先级高优先级技能的约束覆盖低优先级。同时在任务开始时先加载“元技能”——一个负责协调其他技能加载顺序的技能。这听起来有点绕但实际效果是代理在复杂任务里的行为更有序不会一会儿按这个规范、一会儿按那个规范。注意技能组合不是简单叠加。两个技能如果对同一件事有相反要求代理会陷入困惑。安装新技能前用skills info看清楚它的约束范围和现有技能比对有冲突就先解决冲突再启用。5. 常见问题与排查技巧实录5.1 技能加载了但代理不遵守怎么办这是最高频的问题。排查思路按顺序来先确认技能是否真的启用了skills list看状态再确认任务的触发条件是否匹配技能可能没被触发然后检查技能指令是否过于模糊模糊指令代理会忽略最后看是不是启用的技能太多导致关键约束被淹没。我遇到过好几次都是最后一个原因禁用几个不相关的技能后行为立刻正常了。5.2 不同模型下技能表现不一致前面提过技能层和模型层解耦但模型能力差异客观存在。同一个 TDD 技能在指令遵循强的模型上执行得很规范在弱一些的模型上可能跳过验证步骤。解决办法不是改技能去迁就弱模型而是把关键验证点做成显式的、必须执行的检查项减少模型的自由裁量空间。如果某个模型实在遵循度差那就换模型别在技能上过度妥协。5.3 技能版本更新后行为突变技能也是代码会迭代。更新技能后行为变了先看更新日志确认是不是有意为之。如果是无意的回归回滚到上一个版本。这也是为什么我建议给技能集做版本锁定别总是用最新版生产环境用经过验证的版本更稳。下面这张速查表汇总了常见问题和对应处理问题现象可能原因处理方式代理完全不按技能走技能未启用或未触发检查启用状态和触发条件部分步骤被跳过指令模糊或技能过多细化指令精简启用技能换模型后行为异常模型指令遵循度差异强化显式约束或更换模型更新后行为突变技能版本回归查看日志必要时回滚技能之间互相打架约束冲突用优先级机制或拆分任务5.4 几个我踩过的坑第一个坑是技能命名太随意导致后来自己都分不清哪个是哪个。建议命名带场景前缀比如tdd-python、api-design-rest一看就懂。第二个坑是技能里写了太多“最好”“尽量”这类软性词代理基本当没看见后来全改成“必须”“禁止”才有效。第三个坑是忘了给技能写验证标准结果代理做完了但做没做对没法判断只能人工检查失去了自动化的意义。6. 技能资产的长期维护与扩展思路agent-skills真正的价值不在于装了几个技能而在于它让你可以把团队里那些“老司机才知道”的经验沉淀下来。一个项目做久了总有一些反复出现的任务模式把这些模式写成技能新人和 AI 代理都能受益。我现在的习惯是每次发现代理在某个任务上反复出错就停下来想这是不是该写成一个技能了如果是就把它固化下来下次就不用再口头交代了。技能库的扩展方向也很明确从单点技能到技能链从通用技能到领域技能从个人使用到团队共享。当你的技能库积累到一定规模你会发现 AI 代理的产出质量不再依赖你每次对话的“调教水平”而是依赖技能库本身的成熟度。这个转变是从“用 AI 工具”到“建 AI 能力”的分水岭。最后分享一个我自己的小习惯每隔一段时间我会把当前启用的技能全部禁用然后跑几个典型任务看看代理的“裸奔”表现。如果裸奔表现和加载技能后差距不大说明这些技能可能没起到实际作用该考虑精简或重写了。技能库和代码库一样需要定期清理不然会越来越臃肿最后拖慢的是你自己的效率。