1. 从agent-skills这个标题能读出什么第一次看到agent-skills这个仓库名我的直觉是这不是又一个提示词大全而是一套给 AI coding agent 用的能力封装规范。关键词里同时出现了skills CLI、Claude Code、test-driven-development基本可以确定它的定位——把让 AI 写代码这件事从每次靠嘴描述升级成调用一个个可复用的技能包。说白了大多数人用 AI 编程工具的方式是打开对话框敲一段自然语言等它吐代码不满意再改。这种方式在一次性脚本上够用但一旦进入真实项目问题立刻暴露上下文记不住、规范不统一、测试不写、改一处崩三处。agent-skills想解决的就是这个——把资深工程师的工作习惯固化成 agent 可以加载的技能让 AI 在动手前先知道这个项目该怎么干。这篇内容适合三类人看一是已经在用 Claude Code 或类似 AI coding agent、但总觉得它不够听话的开发者二是想给自己的团队搭一套 AI 协作规范的技术负责人三是纯粹好奇skills 到底是个啥、值不值得折腾的观望者。我会从概念拆解讲到落地实操包括 CLI 怎么用、技能怎么写、TDD 怎么和 agent 结合以及我自己踩过的几个坑。需要先说明一点agent-skills本身是一个偏约定和工具链的东西它不绑定某一个模型或某一家厂商。你完全可以在本地把它和不同的模型后端搭配使用核心价值在于技能的组织方式而不是某个特定平台。2. agent-skills 到底解决了什么问题2.1 传统对话式编程的三个硬伤先讲清楚痛点不然没法理解 skills 的价值。我用 AI 写代码这两年多最头疼的三件事第一上下文漂移。你在一轮对话里告诉它这个项目用 pnpm 不用 npm、测试用 vitest、组件必须写 PropTypes聊到第十轮它就开始用 npm 命令了。这不是模型笨是长上下文里指令权重会被稀释。每次重新贴一遍规范累而且容易漏。第二能力不可复用。你今天教会它怎么给这个项目写一个符合规范的 API 路由明天开新会话这套知识归零。团队里五个人用 AI五个人各自调教经验完全不沉淀。第三缺少强制流程。你希望 AI 先写测试再写实现但它天然倾向于直接给你能跑的代码。你不盯着它就不写测试你盯着又回到了人工监督的老路。agent-skills的思路是把这些你反复叮嘱的东西变成结构化的技能文件agent 在需要时主动加载。这就像给新来的实习生一本《团队开发手册》而不是每次口头交代。2.2 skills 和 prompt、和 MCP 的区别很多人会把 skills 和 prompt 模板、和 MCPModel Context Protocol搞混我用自己的理解区分一下概念本质解决什么加载时机Prompt 模板一段预设文本省去重复描述手动粘贴MCP一套协议连接外部工具/数据让 agent 能调用外部能力常驻连接Skills结构化的能力包含说明脚本资源让 agent 掌握怎么做某类任务按需触发打个比方MCP 是给 agent 装上了手能读文件、能查数据库skills 是给它一本操作手册遇到这类任务该按什么步骤、守什么规矩。两者不冲突反而互补——agent 用 MCP 拿到工具用 skills 知道怎么用才对。2.3 一个具体场景为什么写测试这件事必须靠 skills拿 TDD 举例。你直接跟 AI 说用 TDD 写这个功能它大概率会先写实现再补几个测试然后告诉你测试通过了。这不是 TDD这是事后补测试。真正的 TDD 是红-绿-重构先写一个会失败的测试跑一遍确认它确实失败再写最小实现让它通过最后重构。这个流程有强顺序依赖而且中间有必须验证失败这种反直觉步骤。靠一句 prompt 很难稳定复现但把它写成一个 skill里面明确列出步骤、甚至附带一个检查脚本agent 每次都会照做。这就是 skills 的核心价值把有流程、有规范、有验证点的任务从靠模型自觉变成按手册执行。3. skills 的目录结构与编写逻辑3.1 一个 skill 长什么样虽然agent-skills的具体实现可能随版本演进但这类工具的设计思路高度一致。一个典型的 skill 通常是一个目录里面至少包含一个描述文件可能还有辅助脚本和资源。结构大致是这样skills/ test-driven-development/ SKILL.md # 技能说明什么时候用、怎么用 scripts/ check-red.sh # 辅助脚本验证测试确实失败 resources/ template.test.tsSKILL.md是灵魂。它一般包含几块内容元信息技能名、一句话描述、触发条件、使用说明分步骤的操作流程、注意事项容易出错的地方。关键在于触发条件——agent 需要知道什么情况下该加载这个技能否则它要么不用要么乱用。3.2 描述文件里最该写什么我写 skill 描述文件时遵循一个原则写给一个聪明但完全不了解你项目的新人看。具体来说这几块必须写清楚这个技能解决什么任务一句话别绕。什么时候触发比如当用户要求新增功能且项目启用了 TDD 时。执行步骤编号列出每步说清楚做什么和做完怎么验证。禁止事项比如禁止在测试通过前修改实现代码。示例给一个最小可运行的例子比长篇解释管用。我见过很多人写 skill 写成了一篇散文agent 读完抓不住重点。记住skill 是给机器执行的操作手册不是给人看的教程。步骤要短、要可判定、要能验证。3.3 为什么用 Markdown 而不是 JSON/YAML有人会问为什么不用结构化格式写技能我的实测结论是Markdown 对模型更友好。模型在训练时见过海量 Markdown 文档对标题层级、列表、代码块的理解非常稳。你用 JSON 写模型也能读但一旦字段嵌套深了它容易漏字段或者把值搞错。Markdown 的容错性高得多而且人也能直接读、直接改维护成本低。提示如果你的 skill 需要传递结构化参数可以在 Markdown 里嵌一个 YAML front matter 块兼顾可读性和机器解析。4. skills CLI 的实操从安装到跑通第一个技能4.1 环境准备与安装假设你已经有一个能用的 AI coding agent 环境比如 Claude Code 已经装好并能正常对话。skills CLI 通常是作为配套工具安装的。常见做法是通过包管理器全局安装# 以 npm 生态为例具体包名以官方文档为准 npm install -g agent-skills-cli # 验证安装 skills --version如果你在 Ubuntu 或 macOS 上Node 环境建议用 nvm 管理避免权限问题。我踩过的坑是用系统自带 Node 装全局包结果skills命令找不到排查半天发现是 PATH 没配好。用 nvm 就没这问题。安装完先跑一下skills --help看看有哪些子命令。一般会有init初始化技能目录、list列出已装技能、add添加技能、run执行技能这几类。4.2 初始化你的技能库在项目根目录执行初始化skills init这会在项目里创建一个skills/目录或者.skills/取决于约定。我建议把技能库纳入版本控制和代码一起提交。原因很简单技能是团队规范的一部分应该像代码规范一样被 review、被追溯。谁改了什么技能、为什么改git log 里一目了然。初始化后你可以先skills list看看有没有内置的示例技能。很多工具会自带几个通用技能比如代码审查、提交信息生成、TDD 流程可以直接拿来改。4.3 添加并激活一个技能假设我们要加一个 TDD 技能。如果官方仓库有现成的skills add test-driven-development如果是自己写的直接把目录拷进skills/就行。激活方式通常有两种一是 agent 根据触发条件自动加载二是你在对话里显式点名比如用 TDD 技能来实现这个功能。我个人的习惯是关键流程显式点名。自动触发虽然省事但有时候 agent 判断不准该用的时候没用。显式点名最稳尤其是团队协作场景大家约定好涉及新功能就说一句用 TDD 技能行为就统一了。4.4 验证技能真的生效了这一步很多人跳过结果以为装好了其实没生效。验证方法让 agent 执行一个明确需要该技能的任务然后观察它的行为是否符合技能定义。比如 TDD 技能你就看它是不是先写测试、先跑失败。如果它上来就写实现说明技能没加载或者描述文件写得不够明确。我一般会在技能里加一条自检步骤比如要求 agent 在开始前先复述一遍它将要遵循的流程。这样你能立刻看出它到底读没读技能。5. 把 TDD 写成 skill一份可复用的模板5.1 为什么 TDD 特别适合做成 skill前面提过TDD 有强顺序依赖和反直觉步骤天然适合固化成流程。而且它有个好处每一步都有客观验证点。测试失败是客观的测试通过也是客观的不像代码写得好不好这种主观判断。有客观验证点的流程最适合交给 agent 按手册执行。5.2 技能描述文件的核心内容一份 TDD 技能的SKILL.md我会这样组织--- name: test-driven-development description: 当需要新增功能或修复 bug 时按红-绿-重构流程执行 trigger: 用户要求实现新功能或项目启用了 TDD 规范 --- ## 执行流程 1. 阅读需求明确要实现的**最小行为单元** 2. 编写一个测试只覆盖这个行为单元 3. 运行测试**确认它失败**红 - 如果测试直接通过说明测试写错了或功能已存在回到第 2 步 4. 编写**最小实现**让测试通过绿 - 禁止写超出测试范围的代码 5. 运行全部测试确认没有破坏其他功能 6. 在测试保护下重构每次重构后重跑测试 ## 禁止事项 - 禁止在测试失败前编写实现代码 - 禁止一次写多个测试 - 禁止跳过确认失败这一步 ## 验证 每完成一轮输出测试名、失败原因、实现摘要、通过状态注意第 3 步的确认失败和第 4 步的最小实现这两条是 TDD 的灵魂也是最容易被 AI 忽略的地方。写进技能里它就没法偷懒。5.3 配套脚本让流程更硬光靠文字约束还不够可以加一个脚本做硬校验。比如一个检查最近一次测试运行是否失败的脚本#!/bin/bash # check-red.sh - 确认测试处于失败状态 if npm test 21 | grep -q failed; then echo RED confirmed, proceed to implementation exit 0 else echo ERROR: test did not fail, TDD flow violated exit 1 fi让 agent 在写实现前先跑这个脚本跑不过就不许往下走。这种脚本级的约束比纯文字可靠得多因为它是可执行的、有退出码的。5.4 实测中的意外情况我第一次跑 TDD 技能时遇到一个问题agent 写的测试太宽泛一个测试覆盖了三个行为结果确认失败通过了但实现阶段它一次性把三个行为都写了TDD 的粒度就废了。后来我在技能里加了一条每个测试只能有一个断言焦点情况才好转。还有个坑某些测试框架的失败输出格式不统一脚本里的grep failed可能匹配不到。解决办法是让脚本检查退出码而不是输出文本退出码非零就是失败这个最可靠。6. 和 Claude Code 这类 agent 的配合方式6.1 技能加载的两种模式和 Claude Code 这类工具配合时技能加载一般有两种模式项目级和用户级。项目级的技能放在项目目录里只对这个项目生效用户级的放在用户配置目录对所有项目生效。我的建议是通用技能放用户级项目专属规范放项目级。比如 TDD 流程、提交信息规范这种放用户级到处都能用而这个项目的 API 必须走某个网关这种放项目级跟着代码走。6.2 在对话中如何触发技能最直接的方式是在 prompt 里点名。比如用 test-driven-development 技能实现用户登录功能。 需求邮箱密码登录密码错误返回 401。点名之后agent 会去加载对应技能按里面的流程走。如果它没加载你可以追问一句你加载 TDD 技能了吗通常它就补上了。另一种是配置自动触发。在项目的 agent 配置文件里声明涉及新功能开发时自动加载 TDD 技能。这种方式适合流程已经跑顺的团队减少每次点名的麻烦。6.3 技能和项目规范的协同技能不是孤立的它应该和项目的其他规范协同。比如你的项目有 ESLint 配置、有提交信息规范、有 CI 流程技能里就应该引用这些而不是另起一套。我见过有人写了个技能里面规定的代码风格和项目 ESLint 冲突结果 agent 写完代码 CI 直接挂。正确做法是技能里写遵循项目根目录的 ESLint 配置而不是把规则抄一遍。这样规范只有一处定义不会漂移。7. 我踩过的坑和几条实用经验7.1 技能写太细反而不好用刚开始我恨不得把每个细节都写进技能结果描述文件长到几百行agent 加载后反而抓不住重点执行时经常漏步骤。后来我悟了技能应该写决策逻辑和验证点而不是操作细节。操作细节让 agent 自己发挥你只需要卡住关键节点。比如用 vitest 写测试这种细节不用写agent 自己会但必须先确认测试失败这种反直觉的约束必须写。7.2 技能之间会打架如果你同时装了多个技能它们可能对同一件事有不同要求。比如一个技能说提交前跑全量测试另一个说提交前只跑相关测试agent 就懵了。解决办法是给技能分优先级或者在描述里写明本技能优先级高于 XX。我的做法是控制同时激活的技能数量一般不超过三个。技能多了agent 的注意力被分散效果反而下降。7.3 定期清理和迭代技能技能不是写完就完事。项目在变规范在变技能也得跟着改。我一般每个月 review 一次技能库把过时的删掉把踩过坑的新约束加进去。这个过程本身就是团队知识的沉淀——你会发现写技能的过程逼着你想清楚我们到底是怎么干活的。7.4 别指望技能解决所有问题最后泼盆冷水skills 能规范流程但替代不了人的判断。agent 按 TDD 流程走不代表它写的测试就有价值它按规范提交代码不代表代码就没 bug。技能是下限保障不是上限提升。真正决定代码质量的还是你对需求的理解和架构的设计。8. 从单个技能到技能体系当你跑通第一个技能后很自然会想能不能把更多流程都技能化我的经验是优先技能化那些高频、有流程、有验证点的任务。按这个标准值得做成技能的包括代码审查流程、bug 修复流程、依赖升级流程、文档生成流程。而那些一次性的、高度依赖具体上下文的任务做成技能反而累赘。技能体系搭起来之后你会发现一个有意思的副作用团队里怎么干活这件事从隐性知识变成了显性资产。新人来了不用口口相传直接看技能库就知道这个团队怎么开发、怎么测试、怎么提交。这可能是 agent-skills 这类工具最被低估的价值。至于具体怎么组织技能库、怎么和 CI 打通、怎么让技能在多个 agent 之间共享这些可以随着你用得越来越深再逐步探索。先把一个技能跑顺比一次性搭个大框架有用得多。