1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词合集而是一套把 AI coding agent 当可训练对象来对待的工程化方案。关键词里同时出现了skills CLI、test-driven-development、Claude Code这三者放在一起指向的其实是一条很清晰的链路——用命令行工具管理技能包用测试驱动的方式约束 agent 的行为最终落到 Claude Code 这类终端 agent 上跑起来。很多人对 AI coding agent 的理解还停留在对话框里问一句、它答一句。但真正在项目里用过一段时间就会发现agent 最大的问题不是不够聪明而是不稳定同一个任务今天跑得对明天换个上下文就跑偏你教它一次规范下次开新会话它全忘了。agent-skills这类项目要解决的核心痛点就是把你希望 agent 怎么做这件事从一次性的对话变成可复用、可版本管理、可测试的资产。这篇文章适合三类人看一是已经在用 Claude Code 或类似终端 agent、但总觉得每次都要重新调教的开发者二是想给团队建立一套 AI 协作规范、却不知道从哪下手的技术负责人三是纯粹好奇skills 到底是个什么东西、值不值得投入时间学的观望者。我会从概念拆解讲到实操落地把中间那些文档里不会写的坑一并交代清楚。需要先说明一点agent-skills这个仓库本身公开信息有限下面的内容是基于标题、关键词和当前 AI coding agent 生态的常见实践做的合理推演与补全凡是推演的部分我都会明确标注方便你对照自己的实际情况判断。2. skills 到底是什么把调教经验变成可复用资产2.1 从提示词到技能包的认知升级大部分人用 agent 的方式是遇到问题写一段提示词得到结果关掉窗口。下次遇到类似问题再写一遍或者翻聊天记录复制粘贴。这种做法在一次性任务上没问题但一旦任务重复出现——比如每次新增 API 都要写对应的测试每次改数据库 schema 都要同步更新文档——你就会发现自己在做大量重复劳动。skills 的思路完全不同。它把一类任务的触发条件、执行步骤、约束规则、验收标准打包成一个结构化的目录agent 在遇到匹配场景时自动加载。你可以把它理解成给 agent 装的插件或者操作手册不是每次口头交代而是提前写好、随取随用。这里有个关键区别值得强调普通提示词是上下文相关的会话一结束就失效skills 是持久化的存在文件系统里可以提交到 git可以 review可以迭代。这个差别看起来小实际上决定了你能不能把 AI 协作真正纳入工程流程。2.2 一个 skill 通常包含哪些部分根据当前主流 agent 框架的通用设计一个 skill 目录大致长这样skills/ add-api-endpoint/ SKILL.md # 技能说明什么时候用、怎么用 template.py # 代码模板 checklist.md # 验收清单 examples/ # 正反例SKILL.md是核心通常包含几块内容触发描述什么情况下该激活这个技能、前置条件需要哪些信息才能开始、执行步骤分几步、每步做什么、输出格式结果长什么样、常见错误哪些坑要避开。这个结构和人写 SOP 的逻辑是一样的只不过读者从人变成了 agent。我个人的经验是SKILL.md里最值钱的不是步骤而是常见错误那一节。步骤 agent 自己也能推出来个大概但那些上次这里踩过坑的经验只有写进去它才知道。这恰恰是 skills 相对于通用提示词的核心价值——承载的是你的项目特定知识而不是通用能力。2.3 为什么用 CLI 来管理关键词里出现了skills CLI这说明项目提供了命令行工具来管理技能包。为什么不用图形界面、不用手动复制文件夹因为 CLI 天然适合集成到开发流程里。想象几个场景新同事入职一条命令skills install就把团队所有规范装好技能更新了skills update一键同步想看看某个技能被用过多少次、效果如何skills list --stats直接出报表。这些操作如果靠手动拖文件夹很快就会乱成一锅粥。CLI 还有一个隐性好处可脚本化。你可以在 CI 流程里加一步检查 skills 是否最新在 pre-commit hook 里加一步验证 skill 格式合法性。这些自动化能力是图形工具给不了的。3. 为什么 skills 和测试驱动开发绑在一起3.1 agent 的不确定性需要测试来兜底传统软件开发里测试的作用是保证改了 A 不会弄坏 B。AI agent 场景下这个问题更严重agent 的行为受上下文、模型版本、甚至温度参数影响同一段提示词在不同时间可能给出不同结果。如果没有一套验证机制你根本不知道这次改动到底让 agent 变好了还是变坏了。test-driven-development出现在关键词里我认为它有两层含义。第一层是用 TDD 的方式开发 skill 本身先写清楚这个 skill 应该产出什么结果相当于测试用例再写 skill 内容最后跑验证。第二层是skill 的内容本身就在教 agent 做 TDD比如一个新增功能的 skill会强制要求 agent 先写测试、再写实现。这两层其实是统一的你希望 agent 遵守 TDD那你自己定义 skill 的过程也得是 TDD 式的。以身作则逻辑才自洽。3.2 给 skill 写测试具体怎么写给代码写测试大家都熟给 skill 写测试是个新问题。我的做法是维护一个场景-期望对照表场景输入期望行为验证方式用户说加个登录接口激活 add-api-endpoint skill检查 agent 是否读取了 SKILL.md用户说改下这个函数名不激活该 skill检查是否走了通用流程skill 执行到第 3 步产出符合模板的代码对比 template.py 结构故意给错误输入触发常见错误提示检查是否命中 checklist这张表不需要多复杂关键是把我以为它会怎么做变成我验证过它会怎么做。很多 skill 写完之后从没验证过结果 agent 要么不激活要么激活了乱来你还以为是模型不行。3.3 一个反直觉的结论我踩过最大的坑是skill 写得越详细agent 反而越容易僵化。早期我给一个 skill 写了 20 多条规则结果 agent 遇到稍微不同的场景就卡住因为它死抠规则字面意思不会变通。后来我调整了策略规则只写必须遵守的硬约束比如必须写测试不能改公共接口把建议做法单独放一节明确标注可灵活调整。这样 agent 既有边界感又有发挥空间。这个经验我认为对所有写 skill 的人都适用——约束要硬建议要软两者别混在一起。4. 在 Claude Code 里跑通 skills 的完整链路4.1 环境准备别在第一步就卡住Claude Code 是终端里的 agent 工具安装方式根据系统不同有差异。macOS 和 Ubuntu 上的安装流程基本一致核心是确保 Node 环境版本够新建议 18 以上然后用官方提供的安装方式拉取。安装完成后第一次运行会引导你完成账号相关配置。这里有个常见问题很多人装完之后发现命令找不到八成是 PATH 没配好。解决办法是检查安装脚本输出的路径提示手动加到 shell 配置文件里然后source一下。这个坑几乎每个新手都会踩一次提前知道能省半小时。VS Code 用户还可以装对应的插件把 Claude Code 集成到编辑器里。插件配置的核心是告诉它用哪个终端、走哪个模型。如果你用的是第三方模型接入方案配置项会多一些需要填 API 地址和密钥。这部分配置建议单独放一个文件管理别硬编码在项目里避免误提交。4.2 把 skills 挂载到 agent 上skills 目录准备好之后需要让 Claude Code 知道去哪找。通常有两种方式一是放在项目根目录的约定位置比如.claude/skills/agent 启动时自动扫描二是通过 CLI 显式注册路径。我推荐第一种因为约定优于配置团队协作时不用每个人都去配一遍。目录结构建议按功能分类.claude/skills/ backend/ add-api-endpoint/ add-db-migration/ frontend/ add-component/ common/ write-tests/ update-docs/分类的好处是当技能多起来之后你能快速定位。而且 agent 扫描时也能根据当前任务类型缩小范围减少误激活。4.3 验证 skill 是否真的生效挂载完之后别急着用先做一次验证。最简单的办法是给 agent 一个明确匹配某个 skill 的任务然后观察它的行为有没有读取 SKILL.md执行步骤是否符合预期输出格式对不对如果没生效排查顺序是先确认目录路径对不对再确认 SKILL.md 的触发描述是否够明确最后确认 agent 的版本是否支持 skills 机制。我遇到过最隐蔽的问题是触发描述写得太抽象比如写处理代码相关任务结果 agent 觉得所有任务都匹配反而不知道该不该激活。触发描述要具体到当用户要求新增 REST API 端点时这种程度。提示skill 调试期间建议开一个单独的测试项目别在正式项目里试。agent 误操作改坏代码的情况虽然少见但一旦发生很耽误事。5. 写一个能用的 skill从零到跑通的实操5.1 先想清楚这个 skill 解决什么重复问题不是所有任务都值得做成 skill。判断标准很简单这个任务你会不会做第二次、第三次如果是一次性的写提示词就够了如果是反复出现的才值得投入时间做 skill。举个例子给项目加一个新的 API 端点就是典型的高频任务涉及路由注册、控制器编写、参数校验、测试补充、文档更新等一串固定动作非常适合做成 skill。而帮我分析下这段代码为什么慢这种高度依赖具体上下文的任务做成 skill 反而累赘。我一般会先列一个重复任务清单按频率排序从最高频的开始做 skill。做完一个用一周看效果再决定要不要做下一个。别一上来就想搞个大而全的技能库那是典型的过度设计。5.2 SKILL.md 的写法结构比文采重要一份好的 SKILL.md我总结成五段式第一段是触发条件用一两句话说明什么情况下激活。要具体包含关键词比如当用户要求新增 API 端点、添加路由、创建控制器时激活。第二段是前置检查列出开始前必须确认的信息。比如确认端点路径、HTTP 方法、是否需要鉴权。如果信息不全agent 应该主动询问而不是瞎猜。第三段是执行步骤分步骤写每步一个动作。步骤之间要有明确的先后依赖别写成并列的清单。第四段是输出要求说明结果应该包含哪些文件、什么格式。最好配一个模板文件让 agent 照着填。第五段是常见错误把你踩过的坑写进去。这一节是 skill 的灵魂直接决定它比通用提示词强多少。5.3 用 TDD 思路验证 skill写完 SKILL.md 别急着用先设计几个测试场景。我通常准备三类标准场景正常输入看输出对不对、边界场景信息不全或格式奇怪看 agent 会不会乱来、干扰场景相似但不该激活的任务看会不会误触发。跑完这三类基本能判断 skill 是否可用。如果标准场景通过、边界场景 agent 会主动询问、干扰场景不误触发那这个 skill 就算合格了。任何一类出问题回去改 SKILL.md 对应部分再跑一遍。这个过程听起来繁琐但比写完直接用、出问题再改效率高得多。因为 skill 一旦被团队其他人用了改起来成本就高了——你得通知所有人更新还得解释为什么改。在发布前多测一轮比发布后救火划算。6. 那些文档里不会写的坑6.1 skill 之间的冲突当技能多起来之后最容易出现的问题是多个 skill 同时匹配一个任务。比如你有一个新增 API的 skill又有一个写测试的 skill用户说给新接口写测试两个都可能激活agent 就懵了。解决办法是在触发条件里写清楚优先级和互斥关系。比如新增 API的 skill 里注明本 skill 包含测试编写步骤若已激活本 skill不要再单独激活 write-tests。这种协调逻辑框架一般不会自动处理得靠人工设计。6.2 模型切换导致的行为漂移现在很多人会用第三方模型接入方案在不同模型之间切换。这里有个大坑同一个 skill 在不同模型上的表现可能差很多。有的模型对结构化指令遵循得好有的模型更依赖自然语言描述。我的应对策略是skill 的核心约束用最直白的祈使句写别用委婉表达同时在 skill 里留一个模型适配说明章节记录在不同模型上验证过的注意事项。这样换模型时至少知道哪些地方要重新测。6.3 版本管理别偷懒skills 目录一定要纳入 git 管理而且 commit message 要写清楚改了什么、为什么改。因为 skill 的改动会直接影响 agent 行为出问题时你得能快速定位是哪次改动引入的。我还会给每个 skill 加一个版本号写在 SKILL.md 顶部。当 skill 行为发生不兼容变化时升大版本号并在 changelog 里说明。这样团队里有人发现 agent 行为变了能第一时间对上是 skill 更新导致的。7. 把 skills 用出复利一些进阶思路7.1 让 skill 自己进化skill 不是写完就固定的。我有个习惯每次 agent 用某个 skill 出了偏差就在 SKILL.md 的常见错误里补一条。时间长了这个 skill 会越来越贴合实际项目价值越来越高。更进一步可以定期回顾 agent 的执行日志找出反复出现的纠正把它们固化成 skill 规则。这相当于让 skill 在实践中自我迭代比一次性设计要靠谱得多。7.2 团队协作中的 skill 治理如果是团队使用建议指定一个人负责 skill 的 review 和合并避免每个人各写各的、风格混乱。同时建立一套命名规范比如动词-名词格式add-api-endpoint、update-docs方便检索。新人入职时把 skills 目录作为必读材料之一比口头讲规范有效得多。因为 skill 里写的是具体怎么做而不是应该怎么做新人照着跑一遍就上手了。7.3 什么情况下该放弃 skill最后说个反向经验不是所有重复任务都适合做成 skill。如果某个任务虽然重复但每次的上下文差异极大skill 里的规则反而会束缚 agent。这种情况下维护一份高质量的提示词模板可能更合适。判断标准是任务的不变部分是否大于变化部分。如果 80% 是固定的做 skill 划算如果 50% 都要根据情况调整那 skill 的维护成本可能超过收益。这个度需要自己根据项目情况把握没有标准答案。我在实际项目里跑下来一个中等规模的代码库维护 10 到 15 个核心 skill 是比较舒服的区间。太少覆盖不全太多管理成本陡增。从最高频的两三个任务开始边用边加是比较稳妥的节奏。