1. 从 agent-skills 说起为什么它值得单独聊一聊第一次看到agent-skills这个项目名我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agents 装技能包的目录规范。你可以把它理解成以前我们写代码靠 IDE 的插件、靠 shell 脚本、靠 Makefile现在越来越多的活儿交给 Claude Code 这类终端里的 AI 编码代理去干那它凭什么知道这个项目该怎么构建、怎么测、怎么发版答案就是agent-skills这类约定。它解决的核心问题很朴素AI 代理不缺智商缺的是项目上下文和可复用的操作套路。你让一个刚 clone 完仓库的代理去改 bug它不知道测试怎么跑、lint 用哪套规则、提交前要过哪些检查只能瞎猜。agent-skills干的事就是把这些套路沉淀成结构化文件让代理按图索骥。这篇文章适合三类人看一是已经在用 Claude Code、Cursor 这类工具但总觉得它不够懂我项目的开发者二是想给团队搭一套 AI 协作规范的 tech lead三是纯粹好奇skills CLI、test-driven-development这些关键词到底指什么的新手。我会从设计思路讲到落地实操把踩过的坑一并倒出来。需要先说明一点agent-skills本身是一个偏约定 工具链的项目不同版本、不同团队的具体实现会有差异。下面涉及目录结构、CLI 命令的部分是基于这类项目常见实践做的合理还原你落地时以自己仓库里的实际文件为准。2. agent-skills 的整体设计与思路拆解2.1 它到底想解决什么问题传统上一个项目的知识散落在很多地方README 讲怎么装CONTRIBUTING 讲怎么提 PRCI 配置文件里藏着真实的构建命令.editorconfig管格式Makefile或package.json的 scripts 管常用任务。人读起来还行因为人能跳着看、能推断。但 AI 代理不行它需要明确、结构化、可被程序读取的指令。agent-skills的思路就是把这些散落的知识收敛成一个个技能skill。每个 skill 是一个自包含的单元描述在什么场景下、执行什么操作、期望什么结果。代理在需要的时候加载对应 skill而不是把整个仓库塞进上下文。这个设计背后有两个关键考量上下文预算大仓库动辄几万行全塞进去既贵又容易让模型分心。按需加载 skill等于给代理一个目录用到哪本翻哪本。可复用性一个跑测试的 skill理论上可以在多个项目间共享只要约定好接口。2.2 为什么是技能而不是配置这里有个容易混淆的点为什么不直接写个.agentrc配置文件把所有命令列进去就完事我一开始也这么想后来发现不够用。配置是静态的键值对而技能是带条件和流程的。举个例子跑测试这件事在不同情况下完全不一样只改了单个文件应该只跑相关测试快改了公共模块得跑全量测试挂了要先看是环境问题还是真 bug环境问题得先清缓存。这些判断逻辑配置文件表达不了但 skill 可以——它本质上是一段给代理看的操作手册里面可以有分支、有前置检查、有失败处理。这就是agent-skills比单纯配置高明的地方。2.3 和 test-driven-development 的关系热搜词里出现了test-driven-development这不是巧合。TDD 和 AI 代理是天然一对TDD 要求先写测试、再写实现、最后重构这个流程极其适合被固化成 skill。代理拿到一个需求先按 skill 生成失败测试再实现让它通过最后清理。整个过程有明确的红-绿-重构信号代理能自我验证不用人来反复确认。我在实际项目里试过把 TDD 流程写成 skill 之后代理产出的代码质量明显更稳——因为它有了一个客观的完成标准测试通过而不是靠我觉得写完了。这一点后面在实操部分会展开。2.4 方案选型的取舍落地agent-skills时你会面临几个选择我把常见的取舍列一下决策点选项 A选项 B我的建议技能存放位置仓库内.agent/skills/全局用户目录仓库内跟着代码走团队共享技能粒度一个技能干一件事一个大技能包办细粒度便于组合和复用触发方式代理自动判断手动显式调用两者都要自动为主手动兜底格式Markdown frontmatter纯 JSON/YAMLMarkdown人能读代理也能读选 Markdown 加 frontmatter 是我最推荐的原因很实在技能是给人看的也是给代理看的。纯 JSON 机器友好但人维护起来痛苦Markdown 则两边都照顾到了。frontmatter 里放元数据名字、描述、触发条件正文放具体步骤。3. 核心细节解析与实操要点3.1 一个 skill 文件长什么样先看结构再讲门道。一个典型的 skill 文件大概是这样--- name: run-tests description: 运行项目测试支持单文件与全量两种模式 triggers: - 跑测试 - run tests - 验证改动 --- ## 前置检查 1. 确认依赖已安装检查 node_modules 是否存在 2. 若不存在先执行 npm ci ## 执行步骤 - 若只改了单个文件npm test -- file - 若改了公共模块npm test - 若测试失败先执行 npm run clean 再重试一次 ## 成功标准 - 退出码为 0 - 输出中无 FAIL 字样frontmatter 里的triggers是关键它决定了代理什么时候会想起这个技能。写得太窄代理该用的时候想不起来写得太宽动不动就触发反而干扰。我的经验是用用户真实会说的话当 trigger而不是用技术术语。用户说跑一下测试你就别只写execute test suite。3.2 触发条件的写法有讲究很多人第一次写 skilltrigger 写得像 API 文档结果代理根本不触发。我踩过的坑是这样的我写了个 skill 叫deploytrigger 写的是deployment procedure结果我在对话里说发个版代理完全没反应。后来改成同时包含发版部署上线deployrelease这些口语词命中率立刻上来了。这里的原则是trigger 要覆盖同义词和口语表达。你可以把它想象成给一个新人写什么时候该找我的说明越贴近日常说话越好。另外trigger 之间是或的关系命中任意一个就触发所以别怕写多。3.3 技能之间的依赖与组合单个技能好写难的是技能之间怎么协作。比如提交代码这个技能理想情况下应该先调用跑测试技能测试过了再调用格式化技能最后才真正提交。这就涉及技能编排。常见的做法有两种一种是在技能正文里显式写先执行 run-tests 技能让代理自己去调另一种是用一个更高层的工作流文件把多个技能串起来。我倾向于前者因为显式引用更透明出问题时你能一眼看出是哪一步断了。后者虽然优雅但调试起来像黑盒。注意技能之间不要形成循环依赖。A 技能说先跑 BB 技能说先跑 A代理会卡死或者无限循环。写完一批技能后建议画个依赖图自查一遍。3.4 版本管理这件事别偷懒技能文件是代码的一部分就该跟代码一起进版本控制。我见过有团队把技能放在共享网盘里结果不同人本地版本不一致代理行为时好时坏排查了半天才发现是技能文件不同步。把.agent/skills/提交进仓库跟着分支走这是最省心的做法。另外技能变更最好也走 code review。一个 trigger 写错可能让代理在错误的时候触发错误操作后果比改错一行业务代码还严重。4. 实操过程与核心环节实现4.1 从零搭一个 skills 目录假设你有个 Node 项目想接入agent-skills。第一步是建目录结构mkdir -p .agent/skills touch .agent/skills/README.md.agent/skills/README.md不是给代理看的是给人看的写清楚这个目录放技能新增技能请参考模板。然后建第一个技能比如run-tests.md内容参考上一节的模板。接着是skills CLI的部分。这类项目通常会提供一个命令行工具来校验和列出技能常见用法类似# 列出当前项目所有技能 skills list # 校验技能文件格式是否正确 skills validate # 查看某个技能的详情 skills show run-testsskills validate这个命令我强烈建议加进 CI。技能文件格式错了比如 frontmatter 少了name代理加载时会静默失败你根本不知道。放进 CI 每次提交都校验一遍能省掉大量为什么代理不听话的困惑。4.2 用 TDD 技能跑一个真实需求光说不练假把式。我拿一个真实场景走一遍给一个工具函数加输入为空时抛错的逻辑。第一步代理加载test-driven-development技能按技能里的流程先写测试// utils/parse.test.js import { parse } from ./parse; test(空输入应抛出错误, () { expect(() parse()).toThrow(input cannot be empty); });第二步跑测试确认它是失败的红。这一步很多人会跳过觉得我知道它会失败。但 TDD 技能里明确要求必须看到失败因为如果测试一开始就通过说明你测的根本不是新逻辑。代理执行npm test -- parse.test.js看到失败继续。第三步写最小实现让它通过绿// utils/parse.js export function parse(input) { if (!input) throw new Error(input cannot be empty); // ...原有逻辑 }第四步再跑一次测试通过。第五步重构——这里其实没什么可重构的但技能会要求代理检查一遍命名、边界确认没有遗漏。整个过程代理是自驱动的我只在最后 review 了一下。这就是把 TDD 固化成 skill 的威力代理不需要我告诉它先写测试技能里已经写死了。4.3 参数与阈值的选择过程技能里经常要设一些阈值比如改动超过 N 个文件就跑全量测试。这个 N 怎么定我一开始拍脑袋定了个 5结果发现小项目里 5 个文件已经是大改了大项目里 5 个文件可能只是毛毛雨。后来改成按比例改动文件数超过项目总文件数的 10% 就跑全量。计算方式很简单技能里可以写一段伪逻辑total 统计 src 下文件数 changed git diff --name-only 的数量 if changed / total 0.1: 跑全量 else: 跑相关测试这个 10% 也不是拍脑袋是我观察了十几个 PR 之后总结的——低于这个比例相关测试基本能覆盖风险高于这个比例改动面太广相关测试容易漏。当然你可以按自己项目调关键是有个明确的、可解释的依据而不是随便填个数。4.4 把技能接进日常工作流技能搭好了怎么让它真正被用起来我的做法是三步走第一步手动跑通先自己手动触发几次技能确认代理理解正确、执行正确。这一步别省很多问题在手动阶段就能暴露。第二步写进团队文档在 CONTRIBUTING 里加一段本项目已配置 agent-skills常用技能有 X、Y、Z让新人和代理都知道。第三步观察并迭代用一两周记录哪些技能从没被触发可能 trigger 写错了哪些技能经常触发但结果不对可能步骤有问题然后针对性改。我自己的项目里第一版技能有 8 个两周后砍到 5 个、改了 3 个 trigger。技能不是写完就完事的它需要像代码一样持续维护。5. 常见问题与排查技巧实录5.1 代理不触发技能怎么办这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法完全没反应trigger 没命中检查对话里是否出现 trigger 关键词偶尔触发trigger 太窄补充同义词、口语表达触发了但没执行技能正文格式错跑skills validate执行了但结果错步骤描述有歧义手动按技能步骤走一遍看哪步对不上我遇到最多的是第一种。有次我写了个技能 trigger 是数据库迁移结果同事说改下表结构代理毫无反应。加上改表加字段migration之后就好了。trigger 要站在使用者角度写不是站在开发者角度写。5.2 技能太多导致代理选择困难技能不是越多越好。我一度攒了 20 多个技能结果代理经常在几个相似技能之间犹豫或者触发了不相关的技能。后来做了两件事合并相似技能把跑单元测试跑集成测试跑 e2e合并成一个跑测试技能内部用参数区分。加优先级frontmatter 里加个priority字段冲突时高优先级的先触发。技能数量我建议控制在10 个以内超过就该考虑分层了——把低频技能收进子目录只在特定场景加载。5.3 技能里的命令在不同环境跑不通这个坑很隐蔽。技能里写了npm test在你 Mac 上跑得好好的同事 Windows 上就挂了因为路径分隔符不一样。解决办法是技能里尽量用跨平台命令或者显式说明本技能假设 Unix 环境。更稳妥的做法是在技能开头加一段环境检查# 检查运行环境 uname -s # Darwin / Linux / MINGW64_NT代理看到环境不对可以提示用户或者切换到备用命令。这一步多花两分钟写能省掉后面一堆为什么他行我不行的扯皮。5.4 独家避坑技巧汇总最后分享几个我踩坑踩出来的经验都是文档里不会写的技能名用动词开头run-tests比tests好deploy比deployment好。代理对动词的识别更准。每个技能正文控制在 50 行以内太长了代理读不完也容易漏掉关键步骤。超了就拆。失败处理一定要写只写成功路径的技能一旦出错代理就懵了。至少写一句若失败先做 X 再重试。定期清理僵尸技能三个月没被触发过的技能要么 trigger 有问题要么根本不需要果断删。技能变更写 changelog哪怕就一行2024-06-01 补充 Windows 兼容命令也比没有强方便回溯。提示如果你在团队里推 agent-skills别一上来就搞大而全。先挑一个最痛的场景通常是跑测试或提交前检查做一个技能让大家尝到甜头再逐步铺开。一上来搞二十个技能大概率没人维护最后烂尾。我个人在实际操作中的体会是agent-skills这类东西的价值不在于让代理更聪明而在于让代理的行为可预测、可复现、可传承。它把老员工脑子里的隐性知识变成了新人和代理都能读的显性文档。这件事做扎实了团队里每个人——不管是不是用 AI——都会受益。至于后续怎么扩展我最近在试的是把 code review 的检查清单也做成技能让代理在提交前自动过一遍效果还在观察等跑顺了再单独写一篇。