1. 从“agent-skills”说起为什么我们需要给AI编码代理装上一套技能系统第一次看到agent-skills这个项目名的时候我脑子里蹦出来的不是某个具体工具而是一个很朴素的问题我们天天在说 AI coding agents说 Claude Code、说各种 CLI 代理可这些代理真正落地到项目里靠的到底是什么是模型本身够聪明吗显然不是。模型再强如果每次都要从零开始理解你的项目结构、你的测试规范、你的代码风格那它充其量就是个高级一点的自动补全。agent-skills解决的正是这个断层。它本质上是一套给 AI 编码代理使用的“技能包”或者说“能力模块”的集合配合一个 skills CLI 来管理这些技能。你可以把它理解成给代理准备的工具箱里面装着测试驱动开发test-driven-development的流程、代码审查的检查清单、特定框架的脚手架生成规则等等。代理在执行任务时不再是凭空发挥而是按需加载对应的技能照着既定的套路走。这套东西适合谁如果你只是偶尔用 Claude Code 写个脚本可能感受不深。但如果你在团队里推动 AI 辅助开发或者你自己就是一个重度依赖 AI coding agents 的独立开发者那agent-skills这种思路就非常关键了。它把“代理该怎么干活”这件事从提示词工程里抽离出来变成可版本化、可复用、可组合的资产。说白了就是让代理的行为从“即兴表演”变成“按剧本演出”。我之所以对这个方向特别有感触是因为踩过太多坑。早期用 Claude Code 的时候我总在对话里反复强调“先写测试再写实现”“不要动我没让你动的文件”但每次新开一个会话这些约束就全丢了。后来我把这些要求写进项目根目录的配置文件里情况好了一些但仍然不够灵活——不同任务需要不同的技能组合一个全局配置根本覆盖不了。agent-skills加上 skills CLI 的组合恰好补上了这块拼图。2. 拆解 agent-skills 的核心设计技能如何被定义、加载与执行2.1 技能的本质一份带元数据的结构化指令集要理解agent-skills先得搞清楚它里面所谓的“skill”到底长什么样。根据我对这类项目的观察和实际使用经验一个 skill 通常不是一个可执行二进制而是一份结构化的描述文件里面包含几个关键部分技能名称与标识、适用场景说明、具体的操作指令或步骤、以及可选的辅助资源比如模板文件、检查清单、示例代码。这种设计的好处在于它把“知识”和“执行”分开了。代理本身负责执行而 skill 负责提供知识。举个例子一个名为tdd-workflow的技能它的内容可能是这样的当用户要求实现一个新功能时先写一个失败的测试然后运行测试确认它失败接着写最少的代码让测试通过最后重构。每一步都有明确的指令甚至包括运行测试的命令模板。代理加载这个技能后就会按照这个流程去操作而不是上来就噼里啪啦写一堆实现代码。我特别欣赏这种“指令即资产”的思路。因为它意味着你可以像管理代码一样管理代理的行为。技能文件可以提交到 Git 仓库可以 code review可以打标签发布版本。团队里谁发现了一个好的工作流就把它写成 skill 共享出来其他人通过 skills CLI 一键安装。这比在聊天窗口里口口相传“你要这样提示它”要靠谱得多。2.2 skills CLI 的角色技能的包管理器与运行时调度器光有技能文件还不够得有东西来管理它们。skills CLI就是这个角色。从我实际使用的体感来说它至少承担了三件事安装与卸载技能、列出当前可用的技能、以及在代理运行时把选中的技能注入到上下文里。安装这块很好理解类似npm install或者pip install你指定一个技能名或者一个仓库地址CLI 就把对应的技能文件拉到本地某个目录下。列出技能也很直观就是看看当前环境里有哪些技能可用。真正有意思的是第三件事——运行时注入。当你在 Claude Code 里发起一个任务时skills CLI 可以根据任务类型或者你的显式指定把相关的技能内容拼接到给模型的提示词里。这样模型在生成回复时就已经“知道”了这套流程。这里有个细节值得注意技能注入不是越多越好。我试过一次性加载五六个技能结果模型的注意力被分散反而容易忽略关键约束。后来我养成的习惯是一个会话只加载一到两个最相关的技能。比如做新功能开发就只加载 TDD 技能做代码审查就只加载审查清单技能。skills CLI 如果支持按任务类型自动推荐技能那就更省心了。2.3 与 Claude Code 等代理的集成方式agent-skills并不是要取代 Claude Code而是增强它。集成的层面主要有两个一个是通过项目配置文件一个是通过 CLI 的动态调用。项目配置文件的方式比较静态。你可以在项目根目录放一个代理配置文件里面声明这个项目默认启用哪些技能。这样每次在这个项目里启动 Claude Code它都会自动带上这些技能。适合那种长期稳定的项目规范比如“所有新代码必须有测试”“提交前必须跑 lint”。动态调用的方式更灵活。你可以在对话中直接让代理去调用 skills CLI 来加载某个技能或者由 CLI 根据当前对话内容自动判断。我比较常用的是混合模式项目配置里放一两个基础技能保底具体任务需要特殊技能时再手动加载。这样既不会让上下文太臃肿又不会漏掉关键约束。注意不同版本的 Claude Code 对上下文注入的支持程度不一样。有些版本对系统提示词的修改比较敏感注入技能内容时要注意格式尽量用清晰的分隔符把技能指令和用户对话区分开否则模型可能会把技能内容当成用户输入的一部分来处理。3. 实操从零搭建一套可用的 agent-skills 工作流3.1 环境准备与 skills CLI 安装假设你已经在用 Claude Code不管是 VS Code 插件还是终端版本第一步是确认你的 Node.js 环境。skills CLI 这类工具通常是 Node 生态的所以先跑一下node -v确保版本在 18 以上。我实测下来Node 20 LTS 最稳18 也能用但偶尔会有依赖警告。安装 skills CLI 本身通常就是一条全局安装命令。具体包名可能因项目而异但思路是一样的通过包管理器把它装到全局路径下这样在任何项目目录里都能调用。安装完之后跑一下skills --help或者类似的帮助命令确认安装成功并且看看有哪些子命令可用。这里有个小坑如果你之前装过旧版本最好先卸载再装新的。我有一次直接覆盖安装结果 CLI 的缓存目录里还留着旧版本的技能索引导致列出技能时出现重复项。后来养成习惯升级前先清一下缓存目录通常是在用户主目录下的某个隐藏文件夹里。3.2 编写你的第一个 skill以 test-driven-development 为例光用别人写的技能还不够真正体现agent-skills价值的是你自己写技能。我拿 test-driven-development 来举例因为这是最通用、最容易看到效果的一个。一个 TDD 技能文件我一般会包含这几个部分。开头是元信息用 YAML front matter 或者类似的格式写明技能名称、版本、适用场景。然后是正文用自然语言描述流程但要比普通的提示词更结构化。我会分成几个阶段红、绿、重构。每个阶段下面列出具体动作和检查点。比如“红”阶段我会写在写任何实现代码之前先创建一个测试文件测试内容要覆盖新功能的核心行为运行测试命令确认测试失败并且失败原因是功能未实现而不是语法错误。这些细节看起来啰嗦但正是这些约束让代理不会偷懒跳过测试。写完之后用 skills CLI 把它注册到本地技能库。注册的方式可能是把文件放到指定目录也可能是通过 CLI 的 add 命令。注册成功后在 Claude Code 里加载这个技能然后给它一个简单的任务比如“实现一个函数判断字符串是否为回文”。观察它的行为它是不是先写了测试测试是不是先失败了实现是不是足够简单如果它跳过了某一步就回去修改技能文件把那条约束写得更明确。3.3 在 Claude Code 中加载并验证技能效果加载技能的方式取决于你的集成方式。如果是项目配置就在配置文件里加上技能名然后重启 Claude Code 会话。如果是动态加载就在对话里明确说“加载 tdd-workflow 技能”或者用 CLI 命令触发。验证效果的时候我建议用一个你非常熟悉的小任务。这样你心里有标准答案能准确判断代理的行为是否符合预期。我常用的测试任务是“写一个函数把罗马数字转换成整数”。这个任务不大不小有明确的测试用例可以写实现也有多种思路很适合观察代理是否遵循 TDD 流程。观察的重点有几个它有没有在写实现之前先写测试测试文件的位置和命名是否符合项目规范运行测试的命令是不是项目里实际使用的命令如果这些都对说明技能加载成功且生效了。如果有一项不对就针对性地调整技能文件。我自己的经验是通常要迭代两三轮才能让一个技能稳定工作。提示技能文件里的命令模板最好用占位符而不是硬编码。比如测试命令写成{test_runner} {test_file}然后在项目配置里定义test_runner是pytest还是jest。这样同一个技能可以在不同技术栈的项目里复用。4. 常见问题与排查我在使用 agent-skills 时踩过的坑4.1 技能不生效或部分生效的排查思路最常见的问题就是技能加载了但代理不按套路走。我遇到过的原因大概有这么几类。第一类是技能内容太长模型在长上下文里丢失了关键指令。解决办法是精简技能文件把最重要的约束放在最前面并且用加粗或者特殊标记突出。第二类是技能指令和用户当前请求冲突。比如技能要求先写测试但用户说“别写测试了直接实现”模型就会纠结。这时候要么明确告诉代理忽略技能要么调整技能让它更灵活。第三类是 CLI 注入失败。有时候是路径问题技能文件没被正确读取有时候是格式问题CLI 解析技能文件时出错了但没报错。排查这种问题我会先手动查看 CLI 的日志输出通常加一个--verbose或者--debug参数就能看到详细信息。如果日志里显示技能已加载但代理行为不对那就是内容层面的问题回去改技能文件。4.2 技能之间的冲突与优先级处理当你同时加载多个技能时冲突几乎不可避免。比如一个技能说“所有函数都要写文档字符串”另一个技能说“保持代码简洁避免冗余注释”。代理面对这种矛盾指令时行为会变得不可预测。我的处理原则是一个会话里只加载一个主技能其他技能作为补充但明确标注优先级。如果确实需要多个技能协同我会在技能文件里写明依赖关系和优先级。比如 TDD 技能是主流程代码风格技能是辅助当两者冲突时以 TDD 流程为准。skills CLI 如果支持技能组合和优先级配置那就更好了但目前我还没见到特别成熟的方案更多还是靠人工管理。4.3 性能与上下文窗口的平衡每加载一个技能就占用一部分上下文窗口。Claude Code 的上下文窗口虽然不小但也经不起无节制地塞技能。我做过一个粗略的估算一个中等复杂度的技能文件大概 500 到 1000 个 token加载三个就是 3000 token 左右。如果再加上项目文件内容、对话历史很容易就把窗口填满了。我的做法是分层管理。基础技能比如代码风格、提交规范放在项目配置里长期加载但保持精简。任务型技能比如 TDD、重构流程按需加载任务完成后就卸载。另外技能文件里尽量用引用而不是内联。比如需要一段模板代码就写“使用 templates/component.tsx 作为模板”而不是把整个模板贴进技能文件。这样技能文件本身很小需要时再去读模板文件。常见问题可能原因排查方法解决建议技能完全不生效CLI 未正确加载或代理未读取查看 CLI 日志确认技能已注册检查技能文件路径和格式重新注册技能部分生效上下文过长导致指令丢失精简技能文件观察是否改善把关键约束前置减少技能数量多个技能冲突指令矛盾逐个禁用技能定位冲突源明确主技能和辅助技能的优先级代理行为不稳定技能指令模糊用固定测试任务反复验证把模糊描述改成具体可执行的动作上下文窗口不足加载技能过多估算 token 占用分层管理按需加载用引用代替内联5. 把 agent-skills 用出复利团队协作与持续迭代5.1 技能库的版本管理与团队共享一个人用agent-skills和一群人用完全是两个概念。一个人用技能文件放本地就行改坏了也无所谓。团队用就必须考虑版本管理和共享机制。我的建议是把技能库当成代码库来管理。建一个专门的 Git 仓库里面按类别存放技能文件。每个技能文件有版本号有变更记录。团队里任何人想修改技能都走 pull request 流程。这样做的目的是让技能的演进有迹可循避免某个人悄悄改了一条约束导致其他人的工作流突然失效。共享的方式可以很简单把技能仓库作为 Git submodule 挂到各个项目里或者用 skills CLI 直接从远程仓库安装。我比较倾向于后者因为 CLI 可以处理依赖和版本锁定。比如在项目配置里写skills: tdd-workflow1.2.0, code-review0.9.1这样每个人拿到的技能版本都是一致的。5.2 根据项目反馈迭代技能内容技能不是写完就完了得根据实际使用反馈持续迭代。我一般会关注几个信号代理在哪些步骤上反复出错哪些约束被忽略了哪些约束过于严格导致代理无法完成任务举个例子我最初写的 TDD 技能要求“每个函数都必须有对应的测试”。后来发现对于一些纯配置函数或者简单的 getter/setter代理会花大量时间写无意义的测试。于是我修改了技能加上一条“对于不包含逻辑分支的简单函数可以跳过测试但需要在提交信息中说明”。这样既保持了 TDD 的核心精神又避免了机械执行。迭代的频率不用太高我一般是每两周回顾一次技能的使用情况。如果某个技能在两周内没有触发任何问题就保持不动。如果有问题就记录下来集中修改。修改后要用之前的测试任务重新验证确保没有引入新的问题。5.3 从单点技能到技能组合的演进当你积累了一定数量的技能后自然会想到把它们组合起来。比如一个“新功能开发”的组合技能可能包含需求分析、TDD 流程、代码审查、提交规范。代理加载这个组合技能后就能从头到尾走完一个完整的开发流程。组合技能的实现方式我见过两种。一种是物理组合就是把多个技能文件的内容合并成一个大文件。这种方式简单直接但灵活性差改一个地方要动整个大文件。另一种是逻辑组合用一个组合技能文件列出依赖的子技能和它们的执行顺序CLI 在加载时动态拼接。这种方式更灵活但需要 CLI 支持。我目前用的是逻辑组合的思路虽然 CLI 支持有限但可以通过在组合技能文件里写清楚“先加载 A再加载 B冲突时以 A 为准”来实现。效果还不错代理能理解这种顺序关系。未来如果 skills CLI 原生支持组合技能那就更省事了。注意组合技能不要贪多。我试过一个组合技能包含七个步骤结果代理在执行到第四步时就忘了第一步的约束。后来我把组合技能控制在三到四个步骤以内每个步骤的约束都足够具体效果就好多了。6. 我对 agent-skills 这套思路的个人体会用了一段时间agent-skills之后我最大的感受是AI 编码代理的上限不取决于模型有多强而取决于你给它搭的脚手架有多好。模型本身在进步但如果你只是把它当聊天机器人用那它的输出就永远停留在“看起来还行”的水平。只有当你把项目规范、工作流程、质量约束这些东西变成代理可以加载和执行的技能时它才能真正融入你的开发流程。另一个体会是写技能这件事本身就是对团队知识的一次梳理。很多时候那些“只可意会不可言传”的开发习惯在写成技能文件的过程中被迫显式化了。比如“提交前要跑哪些检查”“新功能要先写测试”这些以前靠口口相传的东西现在变成了可执行的指令。这对团队来说价值可能比代理本身还大。最后分享一个小技巧如果你刚开始接触agent-skills不要一上来就写复杂的技能。从最简单的开始比如一个“提交信息规范”技能要求代理在生成提交信息时遵循 Conventional Commits 格式。这个技能很短容易验证而且立刻能看到效果。等你对技能的编写和加载流程熟悉了再去挑战 TDD 这种复杂的流程技能。循序渐进比一口气吃成胖子要靠谱得多。