1. 从“agent-skills”说起为什么它值得单独拎出来聊第一次看到agent-skills这个词是在翻 AI coding agents 相关仓库的时候。当时我的第一反应是这不就是把 prompt 模板换个马甲吗但真正把它拉下来跑了一遍、又对照着 Claude Code 的 skills 机制读了一圈文档之后我改主意了——这东西解决的是一个非常具体、非常痛的工程问题怎么让 AI 编码代理在多次会话之间稳定地复用同一套“做事的方法”而不是每次都要你重新教它一遍。说白了agent-skills是一套面向 AI coding agents 的技能封装规范与配套 CLI 工具。它把“怎么做一个 TDD 流程”“怎么按团队规范写 commit”“怎么在改代码前先跑一遍测试”这类可复用的工作流打包成一个个独立的 skill 目录然后通过skillsCLI 安装、分发、挂载到 Claude Code 这类代理里。你不需要每次都写一大段 prompt代理在合适的时机自己就会去调用对应的 skill。它适合谁三类人最该关注。第一类是天天用 Claude Code 写业务代码的开发者尤其是团队里想统一 AI 输出风格的第二类是做 AI 工具链、想把内部规范沉淀成可分发资产的平台工程师第三类是想研究 agent 能力扩展机制的技术爱好者。哪怕你现在只是偶尔用 AI 补个函数理解 skills 这套思路对你写 prompt 的组织方式也有直接帮助。我下面会从设计思路、核心机制、实操落地、踩坑排查四个角度把agent-skills这套东西拆开讲透。内容里涉及 Claude Code 的部分都是基于公开文档和实际使用经验做的合理补充具体版本行为可能随官方更新变化以你本地实测为准。2. agent-skills 的整体设计与思路拆解2.1 它到底解决什么问题从“一次性 prompt”到“可复用技能”用过 AI coding agent 的人都有体会你精心调好的一段 prompt比如“改代码前先写测试、测试通过再改实现、最后跑一遍 lint”在这一次会话里效果很好。但关掉窗口、第二天开新会话代理又变回那个“上来就改代码”的愣头青。你得把那段话再贴一遍或者存到某个笔记里反复复制。这就是典型的上下文不可持久化问题。prompt 是会话级的而工程规范是项目级、团队级甚至公司级的。agent-skills的核心设计动机就是把这个层级差补上把“方法”从“会话”里抽出来变成磁盘上一个有明确结构的目录代理按需加载。一个 skill 本质上是一个文件夹里面通常包含一个描述文件说明这个 skill 叫什么、什么时候用、怎么用和若干辅助资源脚本、模板、参考文档。代理启动时会扫描已安装的 skills把它们的元信息名称、触发条件、简介注入到自己的可用工具列表里。当任务匹配到某个 skill 的描述时代理就会读取该 skill 的完整内容并执行。这个机制和传统的“系统提示词塞一大堆规则”有本质区别。系统提示词是常驻的塞太多会挤占上下文、稀释注意力skills 是按需加载的平时只占一行元信息真正用到时才展开。这就像你电脑里的软件不是所有程序都开机自启而是需要时再点开。2.2 为什么用 CLI 分发而不是手动拷贝skillsCLI 的存在感很强这不是为了炫技。手动把 skill 目录拷到~/.claude/skills/当然也能用但一旦涉及多台机器、多个项目、团队协作手动拷贝就会失控版本对不上、路径写错、更新时漏掉某个文件。CLI 把这件事标准化了。它负责几件事从远端仓库拉取 skill、校验结构合法性、安装到约定路径、列出已安装项、升级和卸载。你可以把它理解成npm之于 Node 包或者brew之于 macOS 软件——核心价值是可发现、可版本化、可复现。我实测下来CLI 最大的好处是让“技能”变成了可以写进 README、写进 onboarding 文档的东西。新同事入职一行命令装好团队约定的 skillsAI 代理的行为立刻对齐不用挨个口头传授“你用 AI 的时候记得先让它跑测试”。2.3 和 test-driven-development 的天然契合热搜词里test-driven-development和agent-skills绑在一起出现不是偶然。TDD 是最典型的“有固定流程、但 AI 经常偷懒跳过”的工作流。人写代码时TDD 靠自律和 code review 保证AI 写代码时如果没有强制机制它倾向于直接给你一版能跑的实现测试往往是事后补的甚至不补。把 TDD 封装成一个 skill等于给代理装了一个“流程护栏”。skill 里可以明确规定收到改代码的请求后第一步必须先写失败测试第二步运行测试确认它失败第三步才写实现第四步运行测试确认通过第五步重构。每一步都有明确的动作和验证点代理不容易跳步。这就是 skills 相比普通 prompt 的另一个优势它可以把流程拆成带验证点的步骤而不是一段模糊的自然语言描述。验证点让代理有了自我检查的依据也让整个流程更接近人类工程师的真实工作方式。3. 核心机制与实操要点解析3.1 skill 的目录结构与关键文件一个规范的 skill 目录结构大致是这样的my-skill/ ├── SKILL.md # 核心描述文件必需 ├── scripts/ # 可执行脚本可选 │ └── run_tests.sh ├── templates/ # 模板文件可选 │ └── test_template.py └── references/ # 参考文档可选 └── style_guide.mdSKILL.md是整个 skill 的灵魂。它通常包含两部分元信息头frontmatter和正文说明。元信息头用 YAML 格式写在文件最上方声明这个 skill 的名称、描述、以及什么时候应该被触发。正文则是给代理看的详细指令告诉它具体怎么做。元信息里的description字段尤其关键因为它决定了代理能不能“想起来”用这个 skill。写得太笼统比如“帮助写代码”代理几乎不会触发写得太窄又容易漏掉适用场景。我的经验是描述里要同时包含“做什么”和“什么时候用”比如“当用户要求修改现有函数或新增功能时强制执行先写测试再写实现的 TDD 流程”。3.2 触发机制代理是怎么“想起”某个 skill 的这是很多人第一次接触 skills 时最困惑的点。代理并不是每次都会把所有 skill 全文读一遍——那样上下文早爆了。实际机制是代理启动时只加载所有 skill 的元信息名称 描述形成一个轻量的“技能索引”。当它处理用户请求时会拿请求内容和这些描述做匹配判断哪个 skill 相关然后才去读取那个 skill 的完整SKILL.md。这意味着两件事。第一描述的质量直接决定触发率。第二skill 数量不宜过多。如果你装了五十个 skill每个描述都写得很宽泛代理的匹配就会变得混乱该触发的不触发不该触发的乱触发。我一般建议单个项目挂载的 skill 控制在十个以内核心流程类的三到五个就够了。提示如果你发现某个 skill 死活不触发先别怀疑机制八成是 description 写得太抽象。把它改成“当用户做 X 时执行 Y”这种具体句式触发率会明显上升。3.3 用 skills CLI 安装与管理CLI 的常用操作我整理成了一张表方便对照操作命令示例说明安装单个 skillskills install skill-name从配置的源拉取并安装列出已安装skills list查看当前挂载的所有 skill升级skills update skill-name拉取最新版本卸载skills remove skill-name从本地移除查看详情skills info skill-name显示描述、版本、路径安装路径通常是用户级的~/.claude/skills/也有项目级的.claude/skills/。两者的区别很重要用户级对所有项目生效项目级只对当前仓库生效。团队协作场景下我强烈建议把项目专属的 skill 放在项目级目录并提交到版本控制这样每个人 clone 下来就自动拥有相同的 AI 行为规范。3.4 写一个 TDD skill 的完整示例光说理论没意思直接上一个我实际在用的 TDD skill 的SKILL.md骨架--- name: tdd-workflow description: 当用户要求新增功能、修改现有函数或修复 bug 时使用。强制执行测试先行的开发流程。 --- # TDD 工作流 收到代码修改请求后严格按以下步骤执行不得跳步 1. 理解需求明确要改哪个函数、预期行为是什么。 2. 在对应的测试文件中先写一个会失败的测试用例。 3. 运行测试确认它确实失败红。 4. 编写最小实现让测试通过绿。 5. 运行完整测试套件确认没有破坏其他测试。 6. 如有必要重构实现保持测试通过。 ## 注意事项 - 第 3 步的“确认失败”不能省略否则无法证明测试有效。 - 实现阶段只写让测试通过的最少代码不要顺手加无关功能。 - 如果项目没有测试框架先询问用户使用哪个框架不要擅自引入。这个 skill 装上去之后我让 Claude Code 改一个已有函数它会先去找测试文件、写失败用例、跑测试然后才动实现。整个过程比我口头叮嘱靠谱得多因为它有明确的步骤编号和验证点。4. 完整实操流程与关键环节实现4.1 环境准备Claude Code 与 skills 的对接要让 skills 真正跑起来前提是你已经有一个能用的 AI coding agent 环境。以 Claude Code 为例基本流程是先完成安装各平台有对应的安装方式macOS、Ubuntu、Windows 下步骤略有差异然后确认 CLI 能正常启动、能读取项目目录。这一步的具体安装命令随版本变化建议直接对照官方文档操作不要照搬网上过时的教程。环境就绪后确认 skills 的挂载目录存在。如果目录不存在CLI 安装时一般会自动创建。你可以手动检查一下~/.claude/skills/这个路径确认权限没问题——在 Linux 和 macOS 上权限问题是最常见的“装了但没生效”的元凶。注意如果你在受限网络环境下使用某些远端拉取操作可能失败。这种情况下可以手动把 skill 目录放到挂载路径CLI 的本地管理功能依然可用。4.2 安装并验证第一个 skill假设我们要装一个官方的或社区提供的 skill流程大致是# 查看可用 skill具体子命令以你本地 CLI 帮助为准 skills list --available # 安装 skills install tdd-workflow # 确认安装成功 skills list装完之后别急着上生产项目。先在一个测试仓库里验证随便提一个“给这个函数加个参数校验”的请求观察代理的行为。如果它先去找测试文件、先写失败用例说明 skill 生效了如果它直接改实现说明触发没成功回去检查 description。这个验证步骤我强烈建议每次都做。skills 的触发是概率性的不是确定性的同一个 skill 在不同措辞的请求下表现可能不同。多试几种说法你才能摸清它的触发边界。4.3 把团队规范沉淀成 skill 的实操真正体现 skills 价值的是把团队内部那些“口口相传但从不写下来”的规范固化下来。我举几个我们团队实际封装过的例子commit 规范 skill规定 commit message 的格式、必须关联的 issue 编号、禁止的措辞。API 设计 skill新增接口时必须遵循的命名、错误码、分页约定。日志规范 skill什么级别用什么日志、敏感信息脱敏规则。封装这些 skill 的过程本身就是一次团队规范的梳理。很多规范平时没人说得清一旦要写成给 AI 看的明确指令模糊地带就暴露出来了。我甚至觉得写 skill 是检验团队规范是否清晰的最好方式——如果连你自己都写不清楚步骤说明这个规范本身就没落地。4.4 参数与配置的取舍逻辑skills 本身没有太多需要调的数值参数但有几个配置决策值得说清楚。第一是挂载层级的选择。用户级还是项目级我的判断标准是跟具体技术栈绑定的比如某个框架的测试写法放项目级跟个人工作习惯绑定的比如“回答我时先给结论”放用户级。第二是skill 的粒度。一个 skill 是应该覆盖一整个开发流程还是只做一件小事我倾向于单一职责一个 skill 只干一件事但干得足够明确。流程编排交给代理自己去组合多个 skill而不是塞进一个大 skill 里。这样复用性更好也更容易维护。第三是是否引入脚本。有些 skill 需要执行确定性操作比如跑一个固定的检查脚本这时候把脚本放进scripts/目录让 skill 指令去调用它比让代理“自己想办法”可靠得多。能用脚本固化的就不要留给模型自由发挥。5. 常见问题与排查技巧实录5.1 skill 装了但不触发怎么排查这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法完全不触发目录路径不对确认 skill 在~/.claude/skills/或项目级目录下完全不触发元信息格式错误检查 frontmatter 的 YAML 是否合法偶尔触发description 太模糊改成“当用户做 X 时”的具体句式触发但行为不对正文指令有歧义把步骤拆细加验证点装了多个后混乱skill 数量过多精简到十个以内合并同类项我踩过最坑的一次是 frontmatter 里多了一个缩进YAML 解析失败整个 skill 静默失效没有任何报错。后来养成了习惯装完 skill 第一件事就是skills list确认它被正确识别识别不了就是格式问题。5.2 代理跳步、不遵守 skill 指令怎么办即使 skill 触发了代理也可能“偷懒”——比如 TDD skill 要求先写失败测试它却直接写了实现。这种情况通常有两个原因。一是指令不够强硬。自然语言里“建议”“可以”这类词模型会当成可选项。改成“必须”“不得跳过”“严格按以下步骤”会好很多。二是步骤缺少验证点。如果每一步都有明确的、可执行的验证动作比如“运行测试并确认输出为 FAIL”代理就更难跳过因为它跳过后下一步的验证会对不上。我的经验是把 skill 写成一份给新人的 SOP而不是一段建议。新人看了能照着做的代理基本也能照着做写得含糊的代理一定含糊。5.3 多个 skill 冲突的处理当两个 skill 的触发条件重叠时代理可能只选一个或者行为摇摆。解决办法有两个一是明确优先级在 description 里写清楚适用边界比如“仅在项目使用 pytest 时使用”二是合并如果两个 skill 经常一起用考虑合成一个更大的流程 skill。我一般倾向于先合并。skills 数量少而精比多而杂好维护得多。真正需要拆分的场景是那些确实互斥、且各自独立的流程。5.4 版本升级后的兼容问题skills 依赖的 agent 行为会随官方版本更新而变化。我遇到过升级 Claude Code 之后某个 skill 的触发率明显下降的情况。这时候不要急着改 skill先确认是不是 agent 的匹配逻辑变了。稳妥的做法是升级 agent 后把核心 skill 重新验证一遍确认触发和行为都正常再投入日常使用。提示把 skill 目录纳入版本控制每次 agent 升级后如果发现行为异常可以快速回滚到上一个可用版本定位问题。6. 我个人的一些实操体会用了一段时间agent-skills之后我最大的感受是它把“和 AI 协作”这件事从即兴发挥推向了工程化。以前我调 prompt 像在碰运气效果好就截图存下来效果差就重来。现在我把有效的方法固化成 skill它就成了团队资产不依赖我个人的记忆和手感。另一个体会是关于 TDD 的。以前我总觉得让 AI 写测试是浪费时间它写的测试质量参差不齐。但用 TDD skill 强制它先写失败测试之后我发现它写的测试反而更聚焦了——因为它必须先想清楚“这个函数应该有什么行为”才能写出测试。这个“先想清楚”的过程恰恰是 TDD 最有价值的部分对 AI 和对人都一样。最后分享一个小技巧如果你不确定某个流程值不值得封装成 skill就问自己一个问题——“这个流程我是不是每次都要重新跟 AI 解释一遍”如果是那就值得封装。封装的门槛其实很低一个SKILL.md加几行指令就能起步用起来之后再逐步完善。别一上来就追求完美先跑通再迭代。