1. 从agent-skills说起为什么这个项目值得单独聊第一次看到agent-skills这个标题我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agent 用的技能包。你可以把它理解成一套插件化的能力说明书让 Claude Code 这类命令行里的智能体在写代码、跑测试、改配置、查日志的时候不用每次从零开始摸索而是直接调用已经沉淀好的技能模块。我接触 Claude Code 有一段时间了从最早的命令行版本到后来在 VS Code 里挂插件中间踩过的坑不算少。最开始我以为它就是个会写代码的终端助手用久了才发现真正拉开效率差距的不是模型本身而是你有没有给它准备好一套可复用的技能体系。agent-skills这个项目本质上就是在解决这个问题把零散的操作经验抽象成 agent 能识别、能调用、能组合的 skill。它适合谁三类人最该关注。第一类是已经在用 Claude Code、但每次都要重复交代背景的开发者第二类是想把团队内部的编码规范、测试流程固化下来的技术负责人第三类是刚入门 AI coding agent、还在纠结这东西到底能干嘛的新手。不管你是哪一类理解 skill 的组织方式比记住某个具体命令重要得多。这篇文章我不打算写成官方文档的复述而是按我自己实际折腾的顺序把agent-skills的设计思路、核心结构、落地步骤、以及那些文档里不会写的坑一条条摊开讲。你看完至少能做到知道 skill 该长什么样、怎么让 agent 正确加载、以及为什么 test-driven-development 这类流程特别适合做成 skill。2. agent-skills 的整体设计与思路拆解2.1 为什么是技能而不是提示词很多人第一反应是这不就是写一段更长的 prompt 吗我一开始也这么想直到我把同一段逻辑分别用 prompt 和 skill 实现了一遍才发现差别很大。Prompt 是一次性的你这次对话里交代清楚了下次开新会话agent 又忘了。而 skill 是持久化的、可被检索的。它通常以文件形式存在项目目录里agent 在需要的时候主动去读、去匹配。这就好比prompt 是你临时口头交代同事一件事skill 是你写进团队 wiki 的标准操作流程。前者靠记性后者靠制度。更关键的是skill 有结构。一个合格的 skill 一般包含几个部分触发条件什么时候用、输入输出约定、具体步骤、以及边界情况处理。这种结构让 agent 能判断当前任务该不该调用这个 skill而不是无脑把所有上下文都塞进去。上下文窗口是有限的资源skill 的按需加载机制本质上是在做上下文管理。2.2 核心设计原则单一职责与可组合我翻了不少同类项目的组织方式发现做得好的agent-skills都有一个共同点每个 skill 只干一件事。比如运行单元测试是一个 skill根据失败用例生成修复建议是另一个 skill提交前检查代码风格又是第三个。它们可以串联但不会揉成一坨。这个原则听起来简单落地时特别容易违反。我自己就犯过错误一开始写了个大而全的 skill想让它同时处理测试、构建、部署。结果 agent 每次调用都要读一大堆无关内容反而变慢、变笨。后来拆成三个独立 skill命中率和执行准确度都上去了。可组合性还带来一个好处复用。测试相关的 skill 在多个项目里都能用只要目录结构一致直接拷过去就行。这也是为什么agent-skills这类项目往往配套一个 CLI——用命令行管理 skill 的安装、更新、启用禁用比手动复制文件靠谱得多。2.3 和 test-driven-development 的天然契合热搜词里出现了test-driven-development这不是巧合。TDD 的流程本身就是高度结构化的先写失败测试、再写最小实现、再重构。这种步骤明确、每步有明确输入输出的流程简直是为 skill 量身定做的。我实测下来把 TDD 做成 skill 之后agent 的行为稳定了很多。以前它经常跳过测试直接写实现现在只要任务描述里出现新功能或修复 bug它就会先去找测试相关的 skill按流程走。这不是模型变聪明了而是流程被固化下来了。人也是一样靠自觉容易偷懒靠清单就稳得多。提示设计 skill 时优先考虑那些步骤固定、容易漏步骤的流程。TDD、代码审查、发布检查清单都是高价值场景。3. 核心细节解析与实操要点3.1 一个 skill 的最小结构长什么样我不打算给你一个标准答案因为不同项目组织方式不一样。但根据我的实践一个能跑起来的 skill 至少要有这么几块内容我用一个运行测试并汇总结果的例子来说明。首先是元信息skill 的名字、一句话描述、以及触发关键词。这部分决定了 agent 能不能在合适的时机找到它。名字要短描述要准关键词要覆盖用户可能的各种说法。比如跑测试执行用例testrun tests都该能命中。其次是前置条件执行这个 skill 需要什么。比如项目根目录存在测试配置依赖已安装。写清楚前置条件能避免 agent 在环境没准备好的时候瞎执行。然后是执行步骤这是主体要写成 agent 能照着做的有序列表。每一步尽量具体比如在项目根目录执行npm test而不是运行测试。模糊的指令会让 agent 自由发挥结果不可控。最后是输出约定告诉 agent 执行完之后该怎么汇报。是只报通过/失败还是要列出失败用例、附上错误摘要这个约定直接决定了你后续能不能顺畅地接上下一个 skill。3.2 触发机制让 agent 在对的时候想起你这是整个体系里最容易被低估的部分。我见过太多人把 skill 写得很好但 agent 就是不用原因几乎都出在触发机制上。触发一般有两种思路。一种是关键词匹配skill 描述里包含某些词agent 扫描任务描述时命中就加载。这种方式简单直接但容易误触发或漏触发。另一种是显式引用在项目的主配置里列出可用 skillagent 每次启动时先读一遍清单再按需深入。这种方式更可控但需要维护清单。我的建议是两者结合。核心 skill 用显式清单保证一定被看到边缘 skill 用关键词匹配按需加载。另外触发描述里要写反例——明确说什么情况下不要用这个 skill。这一条特别有用能大幅减少误调用。比如本 skill 仅用于单元测试不用于端到端测试一句话就能挡掉很多错误场景。3.3 参数与上下文传递的坑skill 之间要串联就得传递数据。这里有个很现实的坑agent 不会自动记住上一个 skill 的输出除非你显式告诉它。我的做法是在 skill 的输出约定里明确要求把关键结果写成结构化格式比如一个简短的 JSON 或者固定字段的文本块。下一个 skill 的前置条件里就声明需要上一个 skill 的输出作为输入。这样 agent 在串联时会主动去引用而不是重新猜。还有一个坑是路径问题。skill 里如果写死了绝对路径换个环境就废了。统一用相对于项目根目录的路径并且在前置条件里声明假设当前工作目录为项目根目录。这一条能省掉大量为什么在我机器上跑不通的排查时间。注意skill 里尽量避免依赖具体的人名、机器名、临时目录。任何环境相关的东西都应该是参数或前置条件而不是硬编码。4. 实操过程与核心环节实现4.1 环境准备与目录规划先说环境。Claude Code 的安装方式在不同系统上略有差异Mac 和 Ubuntu 都有对应的安装流程VS Code 里也可以挂插件。这部分官方文档写得比较清楚我就不逐条复述了。重点说目录规划因为这是agent-skills能不能用好的地基。我的习惯是在项目根目录下建一个专门的目录来放 skill比如.agent/skills/。每个 skill 一个子目录目录名就是 skill 名里面放一个主文件通常是 markdown 或 yaml。这样结构清晰agent 扫描的时候也容易定位。为什么不把所有 skill 塞进一个文件因为那样加载时无法按需读取等于每次都把全部内容塞进上下文浪费窗口。分目录之后agent 可以先读目录列表再决定深入读哪个。这个先看目录再看内容的两段式加载是我实测下来最省上下文的方式。4.2 用 CLI 管理 skill 的安装与更新热搜里提到skills CLI这类工具的价值在于批量管理。手动复制文件在单项目里还行多项目就崩了。CLI 一般提供几个核心命令安装从某个源拉取 skill 到本地、列出看当前有哪些 skill、启用/禁用控制哪些生效、更新同步最新版本。我建议把 skill 源做成一个独立的仓库团队共享。每个人本地用 CLI 拉取需要改的时候改源仓库再统一更新。这样避免了张三的 skill 和李四的不一样这种混乱。CLI 的具体命令各家实现不同但思路是一致的把 skill 当依赖管理而不是当散落的文件。4.3 手把手写一个 TDD skill光说理论没意思我带你走一遍我实际写 TDD skill 的过程。第一步定名字和描述。名字叫tdd-workflow描述写当需要实现新功能或修复 bug 时按测试先行的流程推进。关键词覆盖新功能修复实现featurebugfix。第二步写前置条件。声明需要项目已有测试框架配置且当前工作目录为项目根目录。第三步写步骤。我把它拆成五步先根据需求写一个会失败的测试运行测试确认它确实失败这一步很多人会跳过但很重要能验证测试本身有效写最小实现让测试通过再运行测试确认通过最后重构并再次运行测试。每一步都写清楚具体命令和预期结果。第四步写输出约定。要求 agent 在每步结束后汇报当前状态并在最后给出一个总结新增了哪些测试、修改了哪些文件、最终测试结果。第五步写边界情况。比如如果测试框架未配置先提示用户配置不要自行安装如果测试一直无法通过最多重试三次后停下来汇报。写完这个 skill 之后我拿一个真实的小需求测了一遍。以前 agent 经常直接写实现现在它会先写测试而且会主动运行确认失败。这个行为变化就是 skill 带来的确定性。4.4 参数计算与选择上下文预算怎么估这里补充一个很多人忽略的点上下文预算。skill 不是越多越好每个 skill 被加载都会占用窗口。我的经验是单个 skill 的主文件控制在几百行以内超过就该拆。粗略估算一个中等复杂度的 skill加载后大概占用几百到一千多 token。如果你同时激活十几个 skill光 skill 本身就可能吃掉上万 token留给实际任务的空间就紧张了。所以我的原则是常用 skill 常驻冷门 skill 按需。CLI 的启用/禁用功能就是干这个的。5. 常见问题与排查技巧实录5.1 agent 不调用我的 skill 怎么办这是最高频的问题。排查顺序我总结成一张表按可能性从高到低排。现象可能原因排查方法完全不调用skill 未被加载检查目录位置和清单配置偶尔调用触发关键词覆盖不足补充同义词和口语化说法调用但行为不对步骤描述模糊把每步改成可执行的具体指令频繁误调用缺少反例说明在描述里明确不适用场景调用后中断前置条件未满足检查环境依赖和路径我踩过最典型的一个坑是skill 文件放在了项目根目录但 agent 的工作目录被设成了子目录结果扫描不到。后来统一把 skill 放在工作目录能覆盖到的位置问题就没了。所以路径一致性要反复确认。5.2 skill 之间互相打架当你 skill 多了难免出现两个 skill 都想处理同一类任务的情况。比如一个通用测试skill 和一个TDDskill都可能在写测试时被触发。解决办法是明确优先级和适用边界。在描述里写清楚TDD skill 用于新功能开发通用测试 skill 用于已有代码的测试补充。如果还是冲突就在主配置里给 skill 排个序agent 按顺序匹配命中即停。这个排序机制很多 CLI 都支持值得用起来。5.3 更新 skill 后行为没变有时候你改了 skill 内容但 agent 还是老样子。原因通常是缓存。有些实现会把 skill 内容缓存起来改完需要重启会话或者手动刷新。我的习惯是改完 skill 后开一个全新会话验证避免被旧上下文干扰。另外如果你用的是共享源改完记得推送到源仓库本地再拉一次。我见过有人改了本地文件以为团队都生效了结果别人拉的是旧版本白忙一场。5.4 独家避坑技巧汇总先写反例再写正例描述里先说什么时候不用能挡掉大部分误触发。步骤里带命令能写具体命令就别写运行测试越具体越稳。输出结构化要求 agent 用固定格式汇报方便后续 skill 引用。小步验证每加一个 skill 就单独测一次别攒一堆再一起调。版本化skill 也要有版本概念改之前先备份出问题能回滚。提示把 skill 当成代码来管理——有版本、有测试、有审查。这样它的可靠性会高一个量级。6. 我的实际体会与后续扩展方向折腾agent-skills这段时间我最大的感受是AI coding agent 的上限很大程度上取决于你给它搭的脚手架。模型能力是底座但 skill 体系决定了它能不能稳定地、可复现地完成复杂任务。同样一个 Claude Code有人用起来像个高级补全有人用起来像个能独立推进任务的助手差距往往就在这套技能体系上。我现在的做法是每完成一个重复性任务就顺手把它抽象成一个 skill。日积月累agent 越来越懂我的项目我也越来越少重复交代背景。这个正循环一旦转起来效率提升是肉眼可见的。后续我打算往两个方向扩展。一是把 skill 和项目的 CI 流程打通让 agent 在提交前自动跑一遍检查 skill二是做一套 skill 的测试机制确保改了 skill 之后行为符合预期而不是靠人肉验证。这两块目前还在摸索等有成熟经验了再单独写一篇。如果你也在用 Claude Code 这类工具我的建议是从一个小 skill 开始别一上来就追求大而全。先让一个流程稳定下来尝到甜头再逐步铺开。踩坑是必然的但每踩一个坑你对这套体系的理解就深一层。