1. 从agent-skills说起为什么AI编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是把提示词工程给工程化了吗但真正把仓库拉下来、跑通 skills CLI、在 Claude Code 里挂上几个技能包之后我才意识到这东西解决的是一个更底层的问题——AI coding agents 的能力复用问题。先说清楚它是什么。agent-skills本质上是一套面向 AI 编码代理AI coding agents的技能封装规范与配套工具链。你可以把它理解成给 Claude Code 这类代理准备的插件市场 标准接口每个 skill 是一个独立目录里面用一份声明式配置描述这个技能能干什么、什么时候触发、需要哪些工具、执行什么逻辑然后通过 skills CLI 安装、注册、分发。代理在干活的时候会根据当前任务上下文自动匹配并加载对应技能而不是每次都靠你在对话里手打一大段提示词。它能解决的问题很具体。我平时用 Claude Code 写代码最烦的就是重复交代同一件事比如改完代码必须跑测试提交前检查 lint生成 commit message 要遵循 Conventional Commits。这些规则每次开新会话都得重新说一遍说漏了它就放飞自我。agent-skills把这些规则沉淀成可复用的技能包一次写好处处生效。再比如 test-driven-development 这种有固定流程的方法论——先写失败测试、再写最小实现、最后重构——完全可以固化成一个 skill让代理按步骤走而不是靠它自由发挥。适合谁来参考三类人。第一类是重度使用 Claude Code、Cursor 这类 AI coding agents 的开发者想把自己的工作流标准化第二类是团队技术负责人想让整个团队的 AI 辅助编码行为保持一致第三类是对 agent 架构感兴趣、想自己造轮子的工程师agent-skills的目录结构和加载机制是很好的参考范本。哪怕你只是刚装完 Claude Code 的新手理解这套东西也能让你少走很多弯路——毕竟热词里那一堆claude code 入门教程claude code 使用背后真正的痛点从来不是装不上而是装上之后不知道怎么让它稳定干活。下面我按自己的实操路径把设计思路、核心机制、落地步骤和踩过的坑完整拆一遍。2. 整体设计思路为什么是技能包而不是大提示词2.1 核心矛盾代理能力无法沉淀用 AI coding agents 的人迟早会撞上同一堵墙会话是易失的能力却需要累积。你在 A 项目里调教好的一套规则换到 B 项目就得重来今天跟代理磨合出的最佳实践明天开个新窗口就归零。传统做法是把这些规则塞进一个巨大的系统提示词或者CLAUDE.md文件里但很快就会发现两个问题一是文件越写越长代理的注意力被稀释关键规则反而被忽略二是不同任务需要的规则完全不同全量加载既浪费上下文窗口又容易互相干扰。agent-skills的设计思路就是冲着这个矛盾去的。它把能力从提示词里抽出来做成按需加载的独立单元。每个 skill 有自己的触发条件只有当任务匹配时才被激活。这就像你电脑里的软件不会开机就把所有程序全跑一遍而是用到哪个开哪个。上下文窗口是稀缺资源按需加载是唯一可持续的方案。2.2 方案选型声明式配置 CLI 分发我研究过几种可能的实现路径最后理解agent-skills为什么选现在这套方案。第一种是纯提示词模板把技能写成 markdown 片段手动复制粘贴。优点是零依赖缺点是没法版本管理、没法自动触发、没法共享本质上还是原始的手工劳动。第二种是写成一个 MCPModel Context Protocol服务器把技能作为工具暴露给代理。这个方案能力强但门槛高——你得会写服务端代码还得处理进程管理、端口、鉴权一堆事。对于我就想固化几条编码规则这种需求属于杀鸡用牛刀。第三种就是agent-skills走的路声明式配置 CLI 分发。技能用接近自然语言的配置描述CLI 负责安装、注册、更新。开发者不需要写复杂代码只要会写 YAML 或 JSON 就能定义技能分发靠 CLI一条命令搞定安装。这个平衡点选得很准——既保留了工程化的可管理性又把使用门槛压到了最低。提示选型时不要一上来就追求最强能力。技能体系的价值在于复用频率一个每天用十次的简单技能远比一个每月用一次的复杂技能有价值。2.3 与 Claude Code 的契合点agent-skills和 Claude Code 的配合是这套方案能落地的关键。Claude Code 本身提供了工具调用、文件读写、终端命令执行这些底层能力agent-skills则在这些能力之上定义什么时候、按什么顺序、用什么约束去调用它们。打个比方Claude Code 是发动机和变速箱agent-skills是驾驶手册和路线规划——前者提供动力后者决定怎么开才不翻车。具体到 test-driven-development 这个技能它做的事情是当代理检测到你要新增功能时强制它先写测试文件、运行测试确认失败、再写实现、再运行测试确认通过。这一串动作 Claude Code 单独也能做但没有技能约束时它经常偷懒跳过确认失败这一步直接写实现然后补测试这就违背了 TDD 的核心。技能的价值就在于把必须确认失败这种容易被忽略的细节固化成硬性流程。3. 核心机制拆解一个 skill 到底由什么组成3.1 目录结构与元数据一个标准的 skill 目录我实测下来大致是这么组织的my-skill/ ├── skill.yaml # 技能声明名称、描述、触发条件 ├── instructions.md # 给代理的具体指令 ├── scripts/ # 可选辅助脚本 │ └── check.sh └── resources/ # 可选模板、配置片段 └── template.txtskill.yaml是整个技能的大脑它决定了这个技能叫什么、什么时候被唤醒、需要什么权限。我见过很多人一上来就猛写instructions.md结果技能死活不触发问题全出在skill.yaml的触发条件写得太窄或者太模糊。这个文件里最关键的几个字段是名称、描述和触发关键词——描述要写得让代理能判断当前任务是否属于我的管辖范围这直接决定了技能的命中率。3.2 触发机制代理怎么知道该用哪个技能这是整套体系里最容易被低估的部分。技能不是装了就自动生效代理需要在运行时判断现在该不该加载这个技能。判断依据主要来自技能的描述文本和当前对话上下文做语义匹配。我踩过的坑是这样的一开始我把某个技能的描述写成帮助处理代码相关任务结果它几乎从不触发——因为代码相关任务太宽泛代理觉得任何编码任务都沾边反而不敢确定。后来改成当用户要求新增函数或修改现有函数逻辑时触发用于强制执行测试先行流程命中率立刻上来了。描述要具体到什么场景下用而不是这个技能是干嘛的这是两个完全不同的表述角度。3.3 指令层把方法论翻译成可执行步骤instructions.md是技能的实际执行逻辑。这里有个反直觉的经验指令不是越详细越好而是要结构化 留白。结构化是指用清晰的步骤、条件分支、检查点来组织留白是指不要把每种情况都写死给代理留出根据实际代码判断的空间。以 TDD 技能为例我写的指令大致是这样的结构识别本次任务要新增或修改的功能点在对应测试文件中编写一个会失败的测试用例运行测试确认它确实失败这一步不能跳过编写最小实现让测试通过运行全部测试确认没有破坏其他功能在保持测试通过的前提下重构每一步都给了明确的动作和验证标准但没有规定测试文件必须叫什么名字用什么测试框架——这些交给代理根据项目实际情况判断。这种流程固定、细节灵活的写法实测下来比全写死或者全放开都稳。3.4 skills CLI安装与生命周期管理skills CLI 是操作入口我常用的几条命令# 查看已安装的技能 skills list # 从本地目录安装技能 skills install ./my-skill # 从远程仓库安装 skills install skill-name # 更新技能 skills update skill-name # 卸载 skills remove skill-nameCLI 的设计很克制没有花哨的功能就是围绕装、查、更、删四个动作。这种克制是对的——技能管理本身不该成为负担。我唯一想吐槽的是早期版本对技能依赖的处理不够清晰如果一个技能依赖另一个技能安装顺序错了会报错但提示信息很含糊。后来我养成的习惯是装之前先看技能的 README把依赖关系理清楚再动手。4. 实操落地从零搭一个 TDD 技能4.1 环境准备与前置检查动手之前先把环境理清楚。我用的是 Ubuntu 环境Claude Code 已经装好并能正常跑起来。如果你还没装热词里那些claude code 安装ubuntu 配置 claude code的教程够用了核心就是确认 Node 环境版本够、CLI 能正常调用。这里不展开安装细节重点说技能体系的前置条件。需要确认三件事第一Claude Code 能正常执行终端命令因为技能里很多步骤依赖跑测试第二skills CLI 已经装好skills --version能输出版本号第三你的项目里有可用的测试框架Python 用 pytest、JS 用 jest 都行技能本身不绑定框架但得有东西可跑。注意如果你的 Claude Code 是通过第三方 API 接入其他模型的热词里提到的那些场景技能触发效果可能会有差异。不同模型对技能描述的语义理解能力不一样实测下来能力越强的模型技能命中越准。这一点在选型时要心里有数。4.2 编写 skill.yaml触发条件怎么定我以 TDD 技能为例把skill.yaml的关键部分写出来name: test-driven-development description: 当用户要求新增函数、修改现有函数逻辑、或修复 bug 时触发。 用于强制执行测试先行流程确保每次代码变更都有对应测试覆盖。 version: 1.0.0 triggers: - 新增功能 - 修改函数 - 修复bug - 重构 permissions: - file:read - file:write - terminal:execute这里description的写法是重点。我特意把触发场景写成了新增函数、修改函数逻辑、修复 bug这种具体动作而不是代码开发。triggers列表是辅助匹配用的关键词和 description 形成互补——description 负责语义理解triggers 负责关键词兜底。permissions字段很多人会忽略但它很重要。TDD 技能需要读写文件和执行终端命令如果不声明这些权限代理在执行到运行测试这一步时会卡住。权限声明遵循最小必要原则别图省事全开。4.3 编写 instructions.md把 TDD 流程固化指令文件我反复改过好几版最终稳定下来的结构是这样的## 执行流程 ### 第一步识别变更点 分析用户需求明确本次要新增或修改的具体功能单元。 如果需求模糊先向用户确认不要自行假设。 ### 第二步编写失败测试 在项目现有测试目录下为变更点编写测试用例。 测试必须能在当前代码状态下失败。 ### 第三步验证失败 运行测试命令确认新测试确实失败。 如果测试直接通过说明测试写错了或功能已存在回到第二步。 ### 第四步最小实现 编写刚好能让测试通过的最少代码。 不要提前实现未来可能需要的功能。 ### 第五步验证通过 再次运行测试确认新测试通过且旧测试未被破坏。 ### 第六步重构 在测试全绿的前提下优化代码结构。 每次重构后重新运行测试。这个结构的关键在于每一步都有明确的完成判据。第三步的确认失败和第五步的确认通过是两个硬性检查点缺了任何一个TDD 就退化成先写代码后补测试。我在实际使用中发现代理最容易偷懒的就是第三步——它会觉得我知道这个测试肯定会失败跳过验证直接写实现吧。所以指令里我特意加了一句如果测试直接通过说明测试写错了用逻辑闭环堵住这个漏洞。4.4 安装与验证确认技能真的生效写完配置和指令安装并验证skills install ./test-driven-development skills listskills list里能看到技能名称和状态就说明装上了。但装上不等于生效得实际跑一次验证。我的验证方法是给 Claude Code 一个明确的新增功能需求观察它的行为序列。如果它先创建测试文件、跑测试、再写实现说明技能触发了如果它直接开始写实现代码说明触发条件没匹配上得回去调skill.yaml的 description。这个验证环节我建议至少跑三次不同类型的任务新增功能、修改现有逻辑、修 bug。三种场景都能正确触发技能才算真正可用。只测一种场景就上线很容易在别的场景下翻车。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法完全不触发description 太宽泛或太窄检查描述是否具体到动作场景偶尔触发triggers 关键词覆盖不足补充常见同义表达触发但行为不对instructions 步骤有歧义检查每步是否有明确完成判据装了但 list 里没有安装路径或权限问题重新 install 并检查目录权限我遇到最多的是第一种。很多人写 description 时习惯从这个技能是什么的角度写比如一个用于测试驱动开发的技能。这种写法对代理来说信息量太低——它需要知道的是什么时候该用你而不是你是什么。改成当用户要求新增或修改代码逻辑时触发之后命中率通常会有明显提升。5.2 技能之间互相干扰装多了技能之后会出现两个技能同时被触发、指令打架的情况。比如你装了一个快速原型技能鼓励先写实现和一个 TDD 技能强制先写测试代理就懵了。解决办法有两个。一是在 description 里明确边界比如快速原型技能写明仅用于探索性验证不适用于正式功能开发TDD 技能写明适用于所有正式代码变更。二是控制同时激活的技能数量我个人的经验是单个项目里常驻技能不超过五个超过之后干扰概率明显上升。技能不是越多越好装一堆用不上的技能只会稀释代理的注意力。5.3 指令被代理选择性执行这个坑很隐蔽。代理有时候会执行技能的前几步到后面就跳过了。原因通常是后面的步骤描述得不够硬。比如我早期写的建议在重构后运行测试建议两个字让代理觉得这是可选项它就跳过了。改成重构后必须重新运行测试测试未通过则回滚重构之后执行率立刻上来了。指令里的动词要强硬用必须禁止确认这类词少用建议可以尽量。代理对语气词的敏感度比人高措辞的松紧直接决定执行力度。5.4 跨项目复用时的路径问题技能里如果写死了绝对路径换项目就废了。我现在的做法是所有路径都用相对于项目根目录的写法并且在指令开头加一句所有路径均相对于当前项目根目录。另外测试命令也不要写死用项目现有的测试命令这种表述让代理自己去项目配置里找。这样同一个 TDD 技能在 Python 项目和 JS 项目里都能用。提示技能的可移植性取决于它有多不依赖具体项目。写技能时多问自己一句换个项目这条指令还成立吗6. 技能体系的扩展玩法与个人体会6.1 把团队规范做成技能agent-skills最有价值的扩展方向是把团队约定固化成技能。比如代码提交规范、分支命名规则、PR 描述模板这些以前靠文档和口头传达的东西现在可以做成技能让代理自动执行。我们团队把 commit message 规范做成了一个技能代理在生成提交信息时会自动遵循 Conventional Commits 格式省掉了大量 review 时的来回拉扯。具体做法是把规范写成instructions.md触发条件设为当用户要求提交代码或生成 commit message 时。这个技能装一次团队所有人共享规范执行的一致性比靠人自觉高得多。6.2 技能的组合与编排单个技能能力有限但技能可以组合。我现在的做法是让几个技能形成流水线TDD 技能负责写代码代码审查技能负责检查质量提交规范技能负责生成 commit。代理在处理一个完整任务时会依次触发这几个技能形成一条自动化流水线。这里的关键是技能之间的衔接要顺。TDD 技能结束时应该留下测试全绿的状态代码审查技能才能在此基础上做检查。如果前一个技能留下半成品后一个技能就会误判。所以设计技能时要有输入输出意识想清楚这个技能结束时应该给下一个技能留下什么状态。6.3 我踩过的几个真实坑第一个坑是过度设计。我一开始想做一个万能开发技能把需求分析、设计、编码、测试、文档全塞进去。结果这个技能又长又杂触发不稳定执行也经常半途而废。后来拆成五个小技能每个只干一件事反而都好用了。技能要小而专这是血的教训。第二个坑是忽视版本管理。技能改了之后没记录改了什么结果某天发现行为变了完全想不起来是哪次改动导致的。现在我的每个技能目录都纳入 git 管理每次改动写清楚 commit message出问题能快速定位。第三个坑是指令里的隐含假设。我写过一个技能假设项目用 pytest结果在一个用 unittest 的项目里直接报错。后来所有涉及具体工具的指令我都改成使用项目现有的测试框架这种表述让代理自己适配。技能要尽量少做假设多做探测。6.4 后续可以怎么扩展这套体系往上走有几个方向值得试。一是技能的市场化分发把好用的技能打包分享出去形成社区生态二是技能的动态组合根据任务复杂度自动决定加载哪几个技能三是技能的效果度量记录每个技能的触发次数和执行成功率用数据指导优化。我个人最看好的方向是技能的效果度量。现在判断一个技能好不好用全靠主观感受缺乏量化依据。如果能记录这个技能触发了多少次、每次是否完整执行、执行后任务成功率如何优化就有了明确方向。这个方向实现起来不难关键是设计好埋点。最后分享一个我用了很久的小技巧新技能先在小项目里试别直接上主力项目。技能的行为需要观察和调优在主力项目里试错成本太高。找个练手项目把技能的触发、执行、边界情况都跑一遍确认稳定了再迁移过去。这个习惯帮我避免了好几次技能在关键时刻掉链子的尴尬。