1. 从agent-skills说起为什么AI编码代理需要一套技能体系第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是把散落在各个仓库里的提示词、脚本、工作流模板统一收拢成一套可复用的技能包吗后来实际用下来才发现它想做的事情比这个要深一层——它试图给 AI coding agents 定义一套标准化的能力接口让 Claude Code 这类工具在接到任务时能像人类工程师一样按需调用技能而不是每次都从零开始理解上下文。说白了agent-skills解决的是一个非常具体的痛点AI 编码代理很聪明但它的聪明是一次性的。你这次教会它怎么跑测试、怎么规范提交信息、怎么处理某个框架的目录结构下次开个新会话它又忘了。而agent-skills的思路是把这些可复用的操作流程、领域知识、检查清单封装成一个个独立的 skill通过一个 skills CLI 来管理、分发和加载。这样无论是 Claude Code、还是其他支持技能协议的编码代理都能在需要的时候精准调用。这套东西适合谁我自己的判断是三类人第一类是已经在日常开发里重度使用 Claude Code 的工程师想让代理的行为更稳定、更可控第二类是做团队协作的 Tech Lead想把团队的编码规范、测试流程固化下来让 AI 和人都遵守同一套标准第三类是喜欢折腾工具链的独立开发者想搞清楚 AI coding agents 的底层扩展机制到底是怎么设计的。如果你只是偶尔用 AI 补全几行代码那这套东西可能有点重但如果你已经把 AI 代理当成日常开发的一部分那它值得花时间研究。我下面会从设计思路、核心机制、实操落地、踩坑排查几个角度把agent-skills这套东西拆开讲清楚。中间会穿插 Claude Code 的安装配置、skills CLI 的使用、test-driven-development 这类典型 skill 的实现逻辑以及我在实际接入过程中遇到的各种问题。尽量做到你看完能直接上手而不是只停留在哦有这么个东西的层面。2. 核心设计思路为什么是技能而不是插件或提示词2.1 技能、插件、提示词三者的本质区别要理解agent-skills的设计得先搞清楚它和另外两个容易混淆的概念——插件plugin和提示词prompt——到底差在哪。我刚开始也以为这就是个提示词管理工具用了一段时间才意识到区别很大。提示词是一次性指令你写一段话告诉 AI 要做什么它执行完就结束了下次还得重写。插件是代码级扩展通常需要写具体的函数、注册钩子、处理事件门槛高而且和宿主程序强耦合。而 skill 介于两者之间它是一份结构化的、带元数据的操作说明既不是纯自然语言也不是纯代码而是自然语言描述 可执行脚本 触发条件的组合。打个比方提示词像是你临时口头交代同事一件事插件像是你给公司装了一套新系统而 skill 像是你写了一份标准作业程序SOP放在共享盘里谁需要谁拿去用而且这份 SOP 还能被机器读取和执行。这个定位决定了agent-skills的几个关键设计选择技能是声明式的你用一份清单描述这个技能是干什么的、什么时候用、需要哪些输入、产出什么而不是写一堆 if-else 逻辑。技能是可组合的一个复杂任务可以拆成多个 skill 串联比如写代码这个任务可以调用test-driven-developmentcode-reviewcommit-convention三个技能。技能是跨代理的理论上只要代理支持技能协议同一份 skill 就能在 Claude Code、其他编码代理之间复用不用为每个工具重写一遍。2.2 为什么选择 CLI 作为管理入口agent-skills用 skills CLI 作为主要的管理入口这个选择我觉得挺务实的。你可能会问为什么不做成 GUI 或者 IDE 插件我的理解是AI 编码代理的使用场景本身就高度依赖终端——Claude Code 本身就是终端里的工具开发者的工作流也在终端里再套一层图形界面反而增加摩擦。CLI 的好处是可以脚本化、可以进 CI、可以被其他工具调用。比如你可以在项目的package.json里加一个pre-commit钩子自动跑某个 skill 做代码检查也可以在 CI 流水线里调用 skill 做自动化测试。这种可编程性是 GUI 给不了的。另外 CLI 天然适合做技能的安装、更新、版本管理。你可以像装 npm 包一样装 skill像升级依赖一样升级 skill这对团队协作来说很重要——大家用的是同一份技能定义不会出现你那边跑得通我这边跑不通的情况。2.3 技能协议的核心字段拆解虽然agent-skills的具体实现细节可能随版本变化但根据我接触到的资料和实际使用经验一个 skill 通常包含这几个核心字段。我按自己的理解整理成表格方便你对照字段作用我的实操建议name技能唯一标识用短横线命名如test-driven-development避免空格和大写description技能用途说明写清楚什么时候该用这是代理判断是否调用的主要依据trigger触发条件可以是关键词、文件类型、命令模式越具体越好inputs需要的输入明确参数类型和是否必填减少代理瞎猜steps执行步骤分步骤写每步说清楚做什么、用什么工具outputs产出物说明产出格式方便下游技能消费constraints约束条件比如不要修改测试文件必须通过 lint这里我要特别强调description和trigger这两个字段。很多人写 skill 的时候把精力都花在steps上结果代理根本不知道该在什么时候调用它。实际上代理选择技能的逻辑主要看 description 和 trigger。description 要写得像给同事的交接说明trigger 要写得像精确的匹配规则。我踩过的坑是description 写得太泛比如帮助写代码结果代理在任何场景都想调用它反而干扰了正常流程。3. 环境准备Claude Code 与 skills CLI 的安装配置3.1 Claude Code 的安装路径选择既然agent-skills主要服务于 Claude Code 这类 AI coding agents那第一步肯定是把 Claude Code 装好。我分别在 macOS、Ubuntu 和 VS Code 环境里装过这里把几条路径都讲一下你可以根据自己的系统选。macOS 上最省事的方式是用官方提供的安装脚本一条命令搞定。装完之后claude命令会进 PATH直接在终端敲claude就能启动。Ubuntu 上稍微麻烦一点需要注意 Node.js 版本我实测下来 Node 18 以上比较稳Node 16 会有一些依赖报错。如果你用的是 Ubuntu 22.04 或 24.04建议先用nvm装一个干净的 Node 20 LTS再装 Claude Code能避开不少系统级依赖冲突。VS Code 用户还有一条路装 Claude Code 的 VS Code 插件。这个插件的好处是能和编辑器深度集成比如你在编辑器里选中一段代码直接右键让代理处理。但要注意插件版和终端版的功能不完全一致有些 skill 相关的操作在插件里可能没有对应入口。我的建议是主力用终端版插件版作为辅助。终端版对 skills CLI 的支持更完整调试也方便。提示安装过程中如果遇到网络相关的报错先检查你的包管理器源和 Node 版本大部分安装失败都是这两个原因导致的和工具本身无关。3.2 skills CLI 的初始化与目录结构Claude Code 装好之后接下来是 skills CLI。这个 CLI 的核心作用是管理技能的生命周期安装、列出、更新、删除、执行。初始化的时候它会在你的项目目录或者用户目录下创建一个技能仓库通常长这样.agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── skill.yaml │ │ └── scripts/ │ ├── code-review/ │ └── commit-convention/ ├── config.yaml └── cache/skills/目录下每个子目录就是一个技能skill.yaml是技能定义文件scripts/放可执行脚本。config.yaml是全局配置比如默认加载哪些技能、技能搜索路径等。cache/是运行时缓存一般不用手动碰。我建议在项目根目录初始化一份项目级技能库同时在用户目录维护一份个人级技能库。项目级的技能跟着仓库走团队成员 clone 下来就能用个人级的技能是你自己积累的通用工具跨项目复用。CLI 加载的时候会先查项目级再查用户级同名技能项目级优先。3.3 模型接入的几种常见方式Claude Code 默认走官方模型但实际使用中很多人会想接入其他模型比如 DeepSeek、Qwen、GLM 这些。这里我不展开讲具体的接入细节不同版本配置方式差异较大但可以分享几个通用原则。第一模型能力决定技能效果。agent-skills里的技能很多依赖模型的理解和推理能力如果你接的模型在指令遵循上比较弱技能执行的成功率会明显下降。我实测下来做复杂多步任务时能力强的模型和弱模型差距非常明显。第二上下文长度很关键。技能定义本身会占用上下文加上项目代码很容易超长。选模型的时候要关注它的上下文窗口太小的模型跑复杂技能会频繁截断。第三接入方式要稳定。不管你是用配置文件还是环境变量建议把配置写在一个统一的地方方便切换和回滚。我见过有人把配置散落在好几个文件里出问题的时候排查半天。注意关于账号注册与否的区别简单说就是注册后能用官方同步、团队协作等功能不注册也能本地用但部分云端能力受限。具体以官方文档为准我这里不展开。4. 核心技能拆解以 test-driven-development 为例4.1 为什么 TDD 是第一个该封装的技能在agent-skills的生态里test-driven-development是我认为最值得优先封装的技能没有之一。原因很简单TDD 的流程高度标准化而且 AI 代理最容易在这个流程上偷懒。你让 AI 写个功能它往往直接就把实现代码写完了测试要么不写要么随便写两个凑数。但如果你把 TDD 封装成技能强制代理走先写测试 → 跑测试看失败 → 写实现 → 跑测试看通过 → 重构这个流程它的产出质量会稳定很多。这不是因为 AI 变聪明了而是因为流程约束住了它的随意性。从工程角度看TDD 技能的价值在于它把质量这件事从依赖人的自觉变成了依赖流程的强制。人写代码会偷懒AI 也会但流程不会。4.2 TDD 技能的步骤设计与参数说明一个完整的 TDD 技能我通常会设计成这几个步骤。这里给出我自己的版本你可以根据团队习惯调整name: test-driven-development description: 当需要实现新功能或修复 bug 时按 TDD 流程编写代码确保测试先行 trigger: - 用户要求实现新功能 - 用户要求修复 bug - 涉及核心业务逻辑的代码变更 inputs: - name: feature_description type: string required: true - name: test_framework type: string required: false default: jest steps: - 理解需求列出需要覆盖的测试场景 - 编写失败的测试用例 - 运行测试确认测试失败红 - 编写最小实现让测试通过 - 运行测试确认通过绿 - 重构代码保持测试通过 - 检查测试覆盖率 constraints: - 不允许先写实现再补测试 - 每次只处理一个测试场景 - 重构阶段不允许改变外部行为 outputs: - 测试文件 - 实现代码 - 测试运行报告这里有几个参数值得展开说。test_framework默认给jest但实际项目里可能是pytest、vitest、go test等等所以设计成可选参数让代理根据项目实际情况覆盖。constraints里的不允许先写实现再补测试是核心约束没有这条代理很容易走回老路。steps里我特意把确认测试失败单独列出来这一步很多人会跳过。但它的意义在于如果测试一开始就通过说明要么测试写错了要么功能已经存在。这个检查能挡掉很多低级错误。4.3 技能执行时的上下文注入技巧技能执行的时候代理需要知道项目的测试框架、目录结构、命名规范这些信息。这些信息如果每次都让代理去猜效率很低。我的做法是在技能定义里加一个context字段或者用 CLI 的上下文注入功能把项目关键信息提前喂给代理。比如你可以注入测试文件存放路径tests/还是__tests__/测试命名规范*.test.ts还是*_test.go断言库偏好expect还是assert覆盖率阈值要求这些信息注入之后代理生成的测试代码会更贴合项目实际减少来回修改。我实测下来注入上下文之后TDD 技能的一次通过率能从大概六成提升到八成以上。实操心得上下文注入不要贪多只注入代理猜不出来的信息。项目里显而易见的约定比如用 TypeScript不用注入浪费上下文。5. 实操全流程从零搭建一套可用的技能库5.1 初始化项目与技能目录假设你现在有一个新项目想从零搭一套技能库。第一步是初始化。在项目根目录执行 skills CLI 的初始化命令它会创建.agent-skills/目录和基础配置文件。然后你可以手动创建第一个技能目录或者用 CLI 的create命令生成模板。我习惯手动创建因为模板有时候会带一些用不上的字段删起来麻烦。手动创建的话就是建目录、写skill.yaml、建scripts/子目录三步。skill.yaml的字段按前面讲的填先写最小可用版本跑通了再逐步加约束。初始化完成后用skills list命令确认技能被正确识别。如果列表里没有检查目录名和skill.yaml里的name是否一致这是最常见的识别失败原因。5.2 编写第一个自定义技能我拿一个实际场景举例团队要求所有提交信息遵循 Conventional Commits 规范。这个需求很适合做成技能因为规则明确、重复性高、AI 容易出错。技能定义大概是这样name: commit-convention description: 当需要生成 git 提交信息时按 Conventional Commits 规范生成 trigger: - 用户要求提交代码 - 用户要求生成 commit message inputs: - name: change_summary type: string required: true steps: - 分析变更内容判断类型feat/fix/docs/style/refactor/test/chore - 确定影响范围scope - 生成符合规范的提交信息 - 检查长度不超过 72 字符 constraints: - 类型必须是允许的七种之一 - 描述用祈使句首字母小写 - 不添加句号结尾 outputs: - 提交信息文本写完之后用skills run commit-convention测试一下。测试的时候故意给一些模糊的变更描述看代理能不能正确判断类型。我试过给修改了登录逻辑修复了 token 过期问题代理正确判断为fix(auth)说明技能生效了。5.3 技能的组合调用与流水线编排单个技能跑通之后真正的威力在于组合。比如一个完整的开发一个小功能流程可以编排成test-driven-development写测试和实现code-review自查代码质量commit-convention生成规范提交信息CLI 支持用配置文件定义这种流水线也可以在执行时用参数串联。我一般会在项目里放一个pipeline.yaml定义常用流水线团队成员直接调用流水线名就行不用记每个技能的名字。编排的时候要注意技能之间的数据传递。前一个技能的outputs要能作为后一个技能的inputs。如果格式对不上中间加一个转换步骤。我踩过的坑是TDD 技能输出的测试报告格式和 code-review 技能期望的输入格式不一致导致流水线中断。后来统一了输出格式都用 JSON问题就解决了。5.4 版本管理与团队分发技能库是要进版本控制的。我建议把.agent-skills/目录整个提交到仓库包括skill.yaml和scripts/。cache/目录加到.gitignore里那是运行时产物不该进仓库。团队分发的时候有两种模式一种是每个项目独立维护技能库适合项目差异大的团队另一种是维护一个共享技能库各项目通过 CLI 引用适合规范统一的团队。我倾向于混合模式通用技能如 commit 规范、代码审查放共享库项目特有技能放项目库。更新技能的时候要注意向后兼容。如果改了某个技能的inputs字段所有调用它的流水线都要跟着改。我的做法是给技能加版本号大版本变更时保留旧版本一段时间给团队迁移的时间。6. 常见问题与排查技巧实录6.1 技能不被识别或加载失败这是最常见的问题我整理了一个排查表现象可能原因排查方法skills list看不到技能目录名与 name 不一致检查skill.yaml的 name 字段技能加载报 YAML 解析错误缩进或特殊字符问题用 YAML 校验工具检查技能被识别但执行报错scripts 权限或路径问题检查脚本可执行权限和相对路径项目级技能不生效被用户级同名技能覆盖检查加载优先级配置我遇到最多的是 YAML 缩进问题。YAML 对缩进极其敏感多一个空格少一个空格都可能解析失败。建议用编辑器的 YAML 插件实时校验。另外description里如果有冒号要用引号包起来否则会被当成键值分隔符。6.2 代理不按技能步骤执行有时候技能加载成功了但代理执行的时候不按步骤来跳步或者乱序。这个问题通常出在description和trigger上。如果 description 写得太模糊代理可能觉得这个技能不太相关就自己发挥了。解决办法是把 description 写得更具体明确在什么情况下必须使用这个技能。另外可以在constraints里加一条必须严格按 steps 顺序执行给代理更强的约束。我试过在 description 里加必须使用这样的强指令词执行遵循度会明显提升。还有一种情况是模型能力不足理解不了多步指令。这时候要么换模型要么把技能拆得更细每步只做一件事。6.3 技能执行超时或上下文溢出复杂技能执行时间长或者上下文占用大会导致超时或溢出。我的应对策略是拆分技能把一个大技能拆成几个小技能分步执行精简上下文只注入必要信息去掉冗余描述设置超时在 CLI 配置里设置合理的超时时间避免无限等待增量执行大任务分批次处理每批完成后保存状态我遇到过一次上下文溢出是因为技能定义里嵌了一大段示例代码。后来把示例代码移到单独的参考文件里技能定义只保留引用问题就解决了。技能定义要精简详细内容放外部文件。6.4 多技能冲突与优先级处理当多个技能的 trigger 重叠时代理可能不知道该调用哪个。比如code-review和security-check都可能在代码变更时触发。这时候需要定义优先级。CLI 通常支持在配置里设置技能优先级数字越小优先级越高。我的经验是越具体的技能优先级越高。security-check比code-review具体所以优先级更高。另外可以在 trigger 里加更精确的条件减少重叠。如果冲突频繁说明技能划分有问题考虑合并或者重新划分职责边界。7. 我踩过的坑与几条实用建议7.1 不要一开始就追求大而全我刚开始搭技能库的时候恨不得把所有能想到的流程都封装成技能结果搞了二十多个技能维护成本极高而且很多技能根本用不上。后来砍到五个核心技能反而用得更顺。建议是从最痛的那个点开始。哪个流程你重复最多、最容易出错就先封装那个。跑通一个再扩展不要贪多。7.2 技能定义要像写文档一样认真很多人写技能定义很随意觉得反正代理能理解。但实际上技能定义的质量直接决定执行效果。我现在的习惯是写技能定义的时候想象自己在给一个新同事写交接文档每个字段都写清楚不留歧义。特别是description和constraints这两个字段值得反复打磨。description 决定代理会不会用constraints 决定代理用得对不对。7.3 定期回顾和清理技能库技能库是会腐化的。项目在变规范在变有些技能可能过时了有些可能被更好的技能替代了。我建议每个季度回顾一次技能库删掉不用的更新过时的合并重复的。清理的时候注意删技能之前先确认没有流水线在引用它。可以用 CLI 的依赖分析功能或者手动 grep 一下配置文件。7.4 把技能当成团队资产来经营最后一条也是我觉得最重要的一条技能库不是个人玩具是团队资产。如果只有你一个人用价值有限如果整个团队都在用价值会放大很多倍。所以从第一天起就要考虑团队协作技能定义要清晰到别人能看懂变更要有记录重要技能要有测试。我见过一些团队把技能库经营得很好新人入职第一天就能用上团队的标准化流程效率提升非常明显。这套东西说到底核心不是技术多复杂而是把隐性知识显性化、把个人经验流程化。agent-skills提供的是一套机制真正有价值的是你往里面填的内容。填得好它就是团队的加速器填得随意它就是一堆没人看的配置文件。