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-development+code-review+commit-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 通常包含这几个核心字段。我按自己的理解整理成表格，方便你对照：

这里我要特别强调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 技能的组合调用与流水线编排

单个技能跑通之后，真正的威力在于组合。比如一个完整的"开发一个小功能"流程，可以编排成：

1. test-driven-development：写测试和实现
2. code-review：自查代码质量
3. 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 技能不被识别或加载失败

这是最常见的问题，我整理了一个排查表：

我遇到最多的是 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提供的是一套机制，真正有价值的是你往里面填的内容。填得好，它就是团队的加速器；填得随意，它就是一堆没人看的配置文件。