1. 从“agent-skills”说起为什么我们需要给AI编码代理装上技能包第一次看到“agent-skills”这个词很多人会以为它又是一个新的AI模型或者某个大厂的新产品。其实不是。它更像是一套“技能说明书”或者“能力插件集合”专门用来给AI编码代理AI coding agents补充它们原本不具备或者不够熟练的操作能力。你可以把它理解成给一个刚入职的实习生发了一本《公司内部工具使用手册》——实习生本身聪明但不知道你们公司用什么命令跑测试、用什么格式提交代码、遇到冲突怎么处理这本手册就是解决这个问题的。我最早接触这个概念是在折腾Claude Code的时候。Claude Code本身已经很强了能读代码、能改文件、能执行终端命令但它在某些特定场景下会“犯傻”。比如你让它跑一个测试它可能直接敲npm test但你的项目用的是pnpm而且测试前需要先启动一个本地数据库容器。这时候它就会卡住或者给你一个错误的执行结果。agent-skills要解决的就是这类问题把“在这个项目里应该怎么做某件事”的知识以结构化的方式喂给AI代理让它从“通用聪明”变成“项目内行”。这套东西适合谁三类人最应该关注。第一类是已经在用Claude Code、Cursor、Windsurf这类AI编码工具的开发者你肯定遇到过“它明明能改代码但就是跑不对命令”的情况。第二类是团队里的技术负责人你们想让AI代理遵守团队的代码规范、测试流程和部署步骤而不是每个人各自调教。第三类是对AI代理底层机制好奇的玩家你想知道这些工具到底是怎么被“扩展”的能不能自己写一套技能包。热搜词里出现了“test-driven-development”这其实点出了agent-skills最核心的应用场景之一。TDD测试驱动开发的流程非常固定先写一个失败的测试然后写最少的代码让它通过最后重构。这个流程对人类开发者来说是肌肉记忆但对AI代理来说它需要被明确告知“现在处于哪个阶段”“下一步该做什么”“什么情况下算完成”。agent-skills就是把这些阶段性的指令和检查点固化下来让AI代理能够真正按照TDD的节奏工作而不是一口气把代码和测试全写完然后告诉你“都通过了”。还有一个热搜词是“skills CLI”这说明已经有人在做命令行工具来管理这些技能包了。你可以用类似skills install、skills list这样的命令来给当前项目安装、查看、更新技能。这个思路很合理因为AI代理本身就是在终端里工作的用CLI来管理它的能力扩展是最自然的交互方式。后面我会详细讲这套CLI大概长什么样、怎么用。2. agent-skills到底长什么样核心结构与设计逻辑2.1 一个技能包的基本组成我拆过几个开源的agent-skills实现也自己写过几个基本结构大同小异。一个技能包通常包含以下几个部分元数据文件一般叫skill.json或者SKILL.md里面写清楚这个技能叫什么、版本号、作者、依赖什么环境、适用于哪些文件类型。这个文件的作用是让AI代理在加载技能之前就知道“这个技能是干什么的”避免加载一堆用不上的东西。指令模板这是核心。它是一段结构化的文本告诉AI代理在特定场景下应该执行什么命令、按照什么顺序执行、遇到什么情况应该停下来询问。比如一个“运行测试”的技能指令模板会写“首先检查项目根目录是否存在pnpm-lock.yaml如果存在则使用pnpm test否则使用npm test。如果测试失败不要自动修复先输出失败用例的完整堆栈信息。”脚本或工具定义有些技能需要调用外部脚本比如一个“生成数据库迁移”的技能可能会附带一个generate-migration.sh脚本。AI代理在执行到这个技能时会直接调用这个脚本而不是自己从头拼命令。示例与反例好的技能包会包含“正确示例”和“错误示例”。正确示例告诉AI代理“这样做是对的”错误示例告诉它“这样做会出问题”。这比单纯写“不要做X”要有效得多因为AI代理对具体例子的理解能力远强于对抽象规则的理解能力。2.2 为什么是“技能”而不是“插件”这里有一个关键的设计选择为什么叫“skills”而不是“plugins”或者“extensions”我个人的理解是插件通常意味着代码级的扩展你需要写JavaScript或者Python来注册钩子、修改行为。而技能更偏向于“知识注入”它不改变AI代理的底层运行逻辑只是给它补充上下文和操作指南。这个区别很重要。插件式的扩展往往需要你理解AI代理的内部API门槛高而且一旦代理升级插件可能就失效了。技能式的扩展则相对稳定因为它本质上就是一段文本AI代理读懂了就能用。即使代理的底层模型换了只要它还能理解自然语言指令技能包就还能工作。这也是为什么agent-skills这个概念在Claude Code社区里特别流行——Claude Code本身就非常擅长理解和执行自然语言指令给它喂技能包是最高效的扩展方式。2.3 技能包的加载时机与优先级另一个需要想清楚的问题是技能包什么时候被加载是在会话开始时全部加载还是按需加载我实测下来按需加载是更合理的方案。原因很简单如果你给AI代理一次性加载了20个技能它的上下文窗口会被大量无关指令占据反而容易混淆。按需加载的意思是AI代理先读取项目的技能索引文件知道有哪些技能可用然后在遇到具体任务时再去读取对应的技能详情。优先级方面通常遵循“项目级技能 用户级技能 全局技能”的规则。项目级技能放在项目根目录的.agent-skills/文件夹下只对当前项目生效。用户级技能放在用户主目录的.agent-skills/下对所有项目生效。全局技能则是工具自带的默认技能。这个优先级设计很符合直觉项目特有的规则应该覆盖通用规则。3. 手把手搭建一个agent-skills工作流3.1 环境准备与目录结构假设你已经在用Claude Code并且项目是一个Node.js的TypeScript项目。我们要搭建一个最小可用的agent-skills工作流。首先在项目根目录创建以下结构.agent-skills/ ├── index.json ├── run-tests/ │ ├── SKILL.md │ └── scripts/ │ └── check-db.sh ├── commit-code/ │ └── SKILL.md └── tdd-workflow/ └── SKILL.mdindex.json是技能索引内容大概长这样{ skills: [ { name: run-tests, description: 在当前项目中运行测试自动检测包管理器并处理数据库依赖, triggers: [运行测试, 跑测试, test, run tests] }, { name: commit-code, description: 按照团队规范提交代码包括格式化、lint检查和提交信息模板, triggers: [提交代码, commit, git commit] }, { name: tdd-workflow, description: 按照测试驱动开发的流程引导AI代理逐步完成功能开发, triggers: [TDD, 测试驱动, 先写测试] } ] }这个索引文件的作用是让AI代理在会话开始时快速了解“这个项目里有哪些技能可用”。注意triggers字段它定义了哪些用户输入会触发这个技能。当用户说“帮我跑一下测试”时AI代理会匹配到run-tests技能然后去读取对应的SKILL.md。3.2 编写第一个技能run-testsrun-tests/SKILL.md的内容是整个工作流的核心。我写一个实际可用的版本# 运行测试技能 ## 适用场景 当用户要求运行测试、检查代码是否正确、验证功能是否正常时使用本技能。 ## 执行步骤 1. 首先检测项目使用的包管理器 - 如果存在 pnpm-lock.yaml使用 pnpm - 如果存在 yarn.lock使用 yarn - 如果存在 package-lock.json使用 npm - 如果都不存在询问用户使用什么包管理器 2. 检查测试是否需要数据库 - 读取 package.json 中的 scripts.test 字段 - 如果测试命令包含 db 或 database 关键字先执行 scripts/check-db.sh 确认数据库容器是否运行 - 如果数据库未运行执行 docker compose up -d db 启动数据库等待5秒后再继续 3. 执行测试命令 - 使用检测到的包管理器运行 test 脚本 - 例如pnpm test 或 npm test 4. 处理测试结果 - 如果所有测试通过输出“所有测试通过”并附上测试用例数量 - 如果有测试失败不要自动修复代码而是输出失败用例的名称、错误信息和完整堆栈 - 如果测试命令本身报错如找不到命令输出错误信息并建议用户检查环境 ## 注意事项 - 不要跳过数据库检查步骤否则测试会以奇怪的方式失败 - 如果测试运行超过120秒输出当前进度并询问用户是否继续等待 - 不要自动修改测试文件来让测试通过这是作弊行为这个技能文件写得很具体每一步都有明确的判断条件和执行动作。AI代理读到这个文件后就知道“跑测试”不是简单地敲一个命令而是一个包含环境检测、依赖启动、结果处理的完整流程。3.3 编写TDD工作流技能TDD工作流技能稍微复杂一些因为它涉及多个阶段的切换。tdd-workflow/SKILL.md的核心内容是# TDD工作流技能 ## 适用场景 当用户要求按照测试驱动开发的方式实现一个新功能时使用本技能。 ## 阶段划分 ### 阶段一写一个失败的测试 - 询问用户要实现的函数名、输入和预期输出 - 在对应的测试文件中添加一个测试用例 - 运行测试确认这个测试失败这是关键必须确认失败 - 如果测试意外通过说明功能已经存在或者测试写错了停下来询问用户 ### 阶段二写最少的代码让测试通过 - 只修改必要的源文件不要添加任何测试没有覆盖的功能 - 运行测试确认新测试通过 - 同时确认之前的测试没有被破坏 ### 阶段三重构 - 检查代码是否有重复、命名是否清晰、结构是否合理 - 如果进行了重构再次运行所有测试确认没有破坏功能 - 询问用户是否继续下一个功能点 ## 关键规则 - 绝对不允许跳过阶段一直接写实现代码 - 每个阶段结束后必须运行测试并输出结果 - 如果用户说“别这么麻烦直接写实现”回复“TDD流程需要先有失败的测试这是为了确保测试真的在验证行为。如果你确定要跳过请明确告诉我。”这个技能包把TDD的纪律性带给了AI代理。我实测下来没有这个技能的时候Claude Code经常一口气把测试和实现都写完然后告诉你“测试通过了”。但你仔细看它写的测试可能根本没有验证到关键逻辑只是走个形式。有了TDD技能之后它会老老实实先写一个失败的测试运行给你看然后再写实现。这个流程虽然慢一点但代码质量明显更高。3.4 技能包的安装与更新热搜词里提到了“skills CLI”我猜未来会出现这样的工具。目前我是手动管理这些文件的但可以想象一个CLI工具的工作方式# 安装一个技能包 skills install run-tests # 查看当前项目已安装的技能 skills list # 更新所有技能到最新版本 skills update # 移除某个技能 skills remove commit-code这个CLI的背后逻辑很简单从某个技能仓库下载技能文件放到.agent-skills/目录下然后更新index.json。如果团队内部有私有的技能仓库也可以配置CLI从内部源拉取。这样团队里每个人都能用同一套技能包保证AI代理的行为一致性。4. 实操中踩过的坑与排查技巧4.1 技能冲突与优先级混乱我遇到的最常见问题是技能冲突。比如我同时安装了“run-tests”和“tdd-workflow”两个技能当我说“跑一下测试”时AI代理有时候会触发TDD工作流开始问我“你要实现什么功能”。这是因为两个技能的触发词有重叠“测试”这个词同时出现在两个技能的triggers里。解决办法是在index.json里给每个技能设置更精确的触发词并且加上优先级字段。比如{ name: run-tests, triggers: [运行测试, 跑测试, 执行测试], priority: 10 }, { name: tdd-workflow, triggers: [TDD, 测试驱动, 先写测试再实现], priority: 5 }优先级高的技能先匹配。同时触发词要尽量具体“跑测试”和“先写测试再实现”虽然都包含“测试”但语义完全不同AI代理更容易区分。4.2 技能文件太长导致上下文溢出另一个坑是技能文件写得太长。我一开始把run-tests/SKILL.md写了快2000字结果AI代理读取这个文件后上下文里塞满了测试相关的指令导致它在处理其他任务时也会受到干扰。后来我把技能文件控制在500字以内只保留最关键的步骤和规则细节放到单独的脚本里。提示技能文件不是文档不需要面面俱到。它更像是一张“操作卡片”只写AI代理在执行这个任务时最容易出错的地方。4.3 AI代理不遵守技能指令有时候AI代理会“忘记”技能里的规则。比如TDD技能明确说了“阶段一必须确认测试失败”但它有时候会跳过这个确认步骤。我分析下来原因是技能文件里的规则不够“显眼”。AI代理在长上下文里容易忽略中间部分的指令。解决办法是把最关键的规则放在技能文件的开头和结尾并且用加粗、列表等格式突出。另外可以在index.json的description字段里也重复一遍核心规则因为AI代理在匹配技能时会先读这个字段。4.4 技能包与项目实际环境不匹配我写过一个“部署到测试环境”的技能里面写死了kubectl apply -f k8s/test/。结果换了一个项目那个项目用的是Docker Compose技能就完全失效了。后来我学乖了技能文件里不写死具体命令而是写“检测项目使用的部署工具如果是Kubernetes则执行X如果是Docker Compose则执行Y”。这个思路和前面run-tests技能里的包管理器检测是一样的让技能具备一定的环境自适应能力而不是假设所有项目都一样。4.5 常见问题速查表问题现象可能原因排查方法解决方式AI代理不触发技能触发词不匹配检查用户输入是否包含triggers中的词增加触发词或改用更具体的表达技能执行到一半卡住缺少依赖或权限查看AI代理输出的最后一条命令补充依赖安装步骤或权限说明技能规则被忽略技能文件太长或规则不显眼检查技能文件长度和格式精简文件关键规则加粗并前置多个技能同时触发触发词重叠查看index.json中的triggers调整触发词设置优先级技能在不同项目表现不一致技能写死了环境相关命令检查技能文件中的硬编码路径改为环境检测条件分支5. 技能包设计的心法从“能跑”到“好用”5.1 把“判断逻辑”写进技能而不是留给AI很多人写技能包的时候只写“执行什么命令”不写“什么情况下执行什么命令”。比如只写“运行pnpm test”但没写“如果pnpm不存在怎么办”。AI代理遇到这种情况时会自己发挥而它的发挥往往不符合你的预期。好的技能包应该把判断逻辑写清楚。我总结了一个模板如果 [条件A]则 [动作X] 如果 [条件B]则 [动作Y] 如果以上都不满足则 [询问用户/输出错误]这个模板看起来很简单但它能覆盖90%的异常情况。AI代理不需要“猜”你的意图它只需要按照条件分支执行就行。5.2 用“反例”约束AI代理的行为前面提到过好的技能包会包含错误示例。我举一个实际的例子。在“commit-code”技能里我写了这样一段## 错误示例 - 不要使用 git commit -m fix 这种无意义的提交信息 - 不要在提交前跳过lint检查即使代码看起来没问题 - 不要一次性提交多个不相关的修改应该拆分成多个提交 ## 正确示例 - git commit -m fix(auth): 修复登录token过期后未正确刷新 - 提交前先运行 pnpm lint 和 pnpm format - 如果修改了多个文件但属于同一功能可以一起提交反例的作用是给AI代理划定边界。它可能不知道“什么样的提交信息算好”但它能理解“fix这种太短的不行”。通过具体例子AI代理的行为会更接近你的预期。5.3 技能包的版本管理与团队协作当团队里有多个人在维护技能包时版本管理就很重要。我的做法是给每个技能包加一个version字段并且在SKILL.md的末尾写一个变更日志。比如## 变更日志 - v1.2 (2025-01-15): 增加数据库容器检测步骤 - v1.1 (2025-01-10): 支持pnpm和yarn - v1.0 (2025-01-05): 初始版本仅支持npm这样当AI代理的行为发生变化时你能快速定位是哪个版本的技能包导致的。如果团队用Git管理项目.agent-skills/目录也应该提交到仓库里这样每个人拉取代码后都能获得相同的技能配置。5.4 技能包的测试与验证技能包本身也需要测试。我的做法是写一个简单的验证脚本模拟AI代理读取技能文件并执行关键步骤。比如对于run-tests技能验证脚本会创建一个临时目录放入pnpm-lock.yaml和package.json模拟AI代理读取SKILL.md检查AI代理是否选择了pnpm而不是npm检查是否执行了数据库检测步骤这个验证脚本不需要真的调用AI代理只需要用正则表达式检查技能文件里是否包含了必要的判断逻辑。虽然简单但能防止明显的错误。6. 从agent-skills看AI编码代理的演进方向折腾了这几个月的技能包之后我有一个明显的感受AI编码代理的竞争力正在从“模型有多聪明”转向“生态有多丰富”。Claude Code的底层模型确实强但如果没有一套好的技能包体系它在具体项目里的表现可能还不如一个配置了完善技能包的普通代理。这个趋势对开发者来说是个好消息。你不需要等待模型升级来解决所有问题你可以通过写技能包来“教”AI代理怎么做你项目里的事。这就像给一个聪明的助手写SOP标准作业程序写得好他就能帮你干很多活写得不好他就只能干瞪眼。热搜词里还有“claude code harness可以不登录用其他模型吗”这样的问题这说明大家在探索AI编码代理的灵活配置。agent-skills这套思路其实和模型选择是正交的无论你用哪个模型技能包都能帮它更好地适应你的项目。模型决定“它有多聪明”技能包决定“它有多懂你”。我个人的体会是花一个小时写一个高质量的技能包比花一个小时反复给AI代理解释“你应该这样做”要划算得多。技能包是一次性投入长期复用而口头解释每次都要重复而且AI代理还不一定记得住。如果你也在用AI编码代理强烈建议从今天开始把你最常重复的那几条指令写成技能包。