1. 从"agent-skills"说起：为什么AI编码代理需要一套技能框架

第一次看到"agent-skills"这个词，很多人会以为它只是某个开源仓库里的一堆提示词模板。但真正在项目里用过AI编码代理的人会明白，它解决的是一个非常具体、非常痛的问题：AI编码代理很强，但它的能力边界完全取决于你给它喂了什么上下文、什么约束、什么工作流。

我最早接触这个概念是在用Claude Code做一个小型重构任务的时候。当时我让它"帮我重构这个模块"，结果它一口气改了十几个文件，删掉了两个它认为"冗余"的函数，还顺手把测试文件也重写了。代码确实能跑，但和我原本的架构意图完全对不上。那次之后我就意识到，AI编码代理不是不够聪明，而是缺少一套可复用的技能定义——它不知道在这个项目里，什么叫做"正确地完成一件事"。

agent-skills要解决的就是这个问题。它本质上是一套面向AI编码代理的技能描述规范与工具链，通过结构化的方式告诉代理：在这个项目里，遇到这类任务应该遵循什么流程、参考什么规范、产出什么形式的交付物。你可以把它理解成给AI代理写的"岗位操作手册"，而不是简单的提示词集合。

这套东西适合谁？三类人最需要：一是已经在日常开发中深度使用Claude Code、Cursor这类AI编码工具的工程师；二是团队里负责制定AI协作规范的技术负责人；三是想把自己的开发经验沉淀成可复用资产、让AI代理替自己执行重复性工作的独立开发者。如果你只是偶尔让AI帮你写个正则表达式，那暂时用不上；但如果你每天有超过30%的编码工作是在和AI代理协作，agent-skills会直接改变你的工作方式。

核心关键词里提到的skills CLI、test-driven-development、Claude Code，其实构成了一个完整的闭环：CLI负责技能的安装、管理和分发，TDD是技能中最典型也最有价值的一类工作流定义，Claude Code则是当前最主流的执行载体之一。接下来我会把这套东西拆开，从设计思路到实操细节，再到踩过的坑，完整讲一遍。

2. agent-skills的整体设计与核心思路拆解

2.1 为什么不是"提示词库"而是"技能框架"

市面上不缺提示词集合。GitHub上搜"awesome prompts"能出来几万个仓库。但agent-skills和它们的本质区别在于：提示词是给一次对话用的，技能是给一类任务用的。

提示词库的问题在于，它假设你每次都能准确地描述清楚当前场景，然后手动挑选合适的提示词粘贴进去。但实际开发中，你面对的是"修复这个bug"、"给这个模块加测试"、"重构这个函数"这种模糊的、重复出现的任务类型。每次都要重新组织提示词，成本极高，而且质量不稳定。

agent-skills的做法是：把一类任务的最佳实践固化成技能定义文件，包含触发条件、执行步骤、约束规则、验收标准四个部分。当AI代理识别到当前任务匹配某个技能时，自动加载对应的技能定义，按照预设的流程执行。这就把"每次都要想怎么问"变成了"一次定义，反复使用"。

这个设计思路背后的逻辑是：AI编码代理的能力瓶颈不在模型本身，而在上下文工程。同一个模型，给它模糊的指令和给它结构化的技能定义，产出质量差距可能是数量级的。agent-skills本质上是在做上下文工程的标准化和复用。

2.2 技能定义的四个核心组成部分

一个完整的agent-skill定义，通常包含以下四个部分，我以最典型的test-driven-development技能为例来说明。

触发条件：定义什么情况下这个技能应该被激活。比如"当用户要求为新功能编写代码时"、"当检测到项目中有测试框架配置时"。触发条件写得越精确，技能被误用的概率越低。

执行步骤：这是技能的核心，定义了代理应该按什么顺序做什么事。TDD技能的步骤通常是：先写一个失败的测试，确认测试失败，然后写最少的代码让测试通过，最后重构。每一步都有明确的输入和输出。

约束规则：定义代理在执行过程中不能做什么。比如"在测试通过之前不允许修改生产代码"、"每次只允许添加一个测试用例"、"不允许跳过失败测试的验证步骤"。这些约束是保证技能执行质量的关键。

验收标准：定义什么叫做"完成了"。比如"所有新增测试通过"、"代码覆盖率不低于某个阈值"、"没有遗留的TODO注释"。验收标准让代理知道自己什么时候可以停下来。

注意：很多人在定义技能时只写执行步骤，忽略约束规则和验收标准，结果代理执行到一半就开始"自由发挥"。约束规则和验收标准才是保证技能可复用的关键。

2.3 为什么选择CLI作为管理入口

skills CLI的设计选择很值得说。为什么不做成IDE插件或者Web平台，而是做成命令行工具？

第一个原因是可组合性。CLI天然适合被其他工具调用，你可以把skills CLI集成到CI流程里，在代码提交时自动检查技能定义是否完整；也可以集成到项目初始化脚本里，新项目一键安装团队的标准技能集。

第二个原因是版本管理。技能定义是文本文件，天然适合用Git管理。CLI可以方便地实现技能的安装、更新、回滚，就像管理npm包一样管理技能。团队可以维护一个私有的技能仓库，新成员入职时一条命令就能拉取全部标准技能。

第三个原因是跨编辑器。Claude Code、Cursor、Windsurf这些工具各有各的插件体系，但CLI是通用的。用CLI管理技能，意味着你的技能资产不被锁定在某个特定编辑器里。

实际使用中，skills CLI的典型命令包括：skills install <skill-name>安装技能、skills list列出已安装技能、skills update更新技能到最新版本、skills create创建自定义技能。这些命令的设计逻辑和包管理器非常相似，学习成本很低。

3. 核心细节解析与实操要点

3.1 技能文件的结构与编写规范

一个agent-skill通常是一个Markdown文件，放在项目的.skills/目录下。文件名就是技能名，比如test-driven-development.md。文件内部有固定的结构，我用一个简化版的TDD技能来演示。

--- name: test-driven-development trigger: 当需要为新功能编写代码或修复bug时 version: 1.0.0 --- ## 执行步骤 1. 阅读需求，确认要实现的函数签名和预期行为 2. 在测试文件中编写一个测试用例，覆盖最基本的情况 3. 运行测试，确认测试失败（红） 4. 编写最少的代码让测试通过（绿） 5. 运行全部测试，确认没有破坏已有功能 6. 重构代码，消除重复，保持测试通过 7. 重复步骤2-6，直到覆盖所有需求场景 ## 约束规则 - 在测试失败之前，不允许编写生产代码 - 每次只添加一个测试用例 - 不允许修改已通过的测试来适应实现 - 重构阶段不允许改变外部行为 ## 验收标准 - 所有新增测试通过 - 已有测试全部通过 - 新增代码有对应的测试覆盖 - 没有遗留的调试代码或注释

这个结构看起来简单，但每个部分都有讲究。触发条件要写得足够具体，避免技能在不该激活的时候激活。执行步骤要按顺序编号，因为代理需要知道先后关系。约束规则要用否定句式，明确划出红线。验收标准要可验证，不能是"代码质量好"这种主观描述。

3.2 技能加载机制与优先级

当AI编码代理启动时，它会扫描项目中的技能目录，加载所有技能定义。但这里有一个关键问题：如果多个技能同时匹配当前任务怎么办？

agent-skills的设计是引入优先级机制。每个技能可以设置一个priority字段，数值越高优先级越高。当多个技能匹配时，代理会优先加载高优先级的技能。如果优先级相同，则根据触发条件的匹配程度来决定。

实际使用中，我建议把技能分为三层：基础技能（如代码风格、提交规范）优先级最低，流程技能（如TDD、代码审查）优先级中等，项目特定技能（如这个项目的部署流程）优先级最高。这样保证项目特定的约束总是优先于通用规范。

还有一个细节是技能的作用域。有些技能是全局的，适用于所有项目；有些技能是项目级的，只在这个项目里生效。CLI通常支持--global和--local两个标志来区分。全局技能放在用户目录下，项目技能放在项目目录下。加载时项目技能会覆盖同名的全局技能。

3.3 与Claude Code的集成方式

Claude Code是目前对agent-skills支持最完善的AI编码代理之一。集成方式主要有两种。

第一种是通过项目配置文件。在项目根目录的.claude/目录下创建一个skills.md文件，里面列出要加载的技能。Claude Code启动时会自动读取这个文件，加载对应的技能定义。这种方式适合团队协作，因为配置文件可以提交到Git，所有成员共享同一套技能。

第二种是通过CLI动态注入。使用skills run <skill-name>命令，可以在当前会话中临时加载某个技能。这种方式适合调试和实验，比如你想试试某个新技能的效果，又不想修改项目配置。

实际使用中，我通常会把常用的技能固化到项目配置里，把实验性的技能用CLI动态加载。这样既保证了日常工作的稳定性，又保留了探索的空间。

提示：Claude Code在加载技能后，会在系统提示中注入技能定义的内容。这意味着技能定义会占用上下文窗口。如果技能太多太长，可能会挤占实际任务的上下文空间。建议单个技能定义控制在500字以内，项目加载的技能总数不超过10个。

4. 实操过程与核心环节实现

4.1 环境准备与skills CLI安装

在开始之前，你需要确认几件事：Node.js版本不低于18，因为skills CLI依赖一些较新的运行时特性；Git已配置好，因为技能仓库通常通过Git分发；Claude Code已经安装并能正常使用。

安装skills CLI的命令很简单：

npm install -g @agent-skills/cli

安装完成后，运行skills --version确认安装成功。如果提示命令找不到，检查npm的全局bin目录是否在PATH中。

接下来初始化项目技能目录：

cd your-project skills init

这个命令会在项目根目录创建.skills/目录，并生成一个示例技能文件。你可以直接编辑这个文件，或者用skills create <name>创建新技能。

4.2 编写第一个自定义技能

我以"API接口开发"为例，演示一个完整的技能编写过程。假设我们的项目是一个Node.js后端服务，使用Express框架，团队约定所有API接口必须包含参数校验、错误处理和单元测试。

首先创建技能文件：

skills create api-endpoint

然后在生成的.skills/api-endpoint.md中填写内容：

--- name: api-endpoint trigger: 当需要新增API接口或修改现有接口时 priority: 10 version: 1.0.0 --- ## 执行步骤 1. 确认接口的HTTP方法、路径、请求参数和响应格式 2. 在routes目录下创建或修改对应的路由文件 3. 使用zod定义请求参数的校验schema 4. 实现业务逻辑，确保所有异步操作都有错误处理 5. 在tests目录下编写单元测试，覆盖正常情况和至少两种异常情况 6. 运行测试，确认全部通过 7. 更新API文档 ## 约束规则 - 所有请求参数必须经过校验，不允许直接使用req.body - 所有异步操作必须使用try-catch包裹 - 错误响应必须包含code和message字段 - 不允许在路由文件中直接写业务逻辑，必须抽离到service层 ## 验收标准 - 单元测试覆盖率不低于80% - 所有测试通过 - API文档已更新 - 没有console.log遗留

写完之后，用skills validate api-endpoint检查技能定义是否符合规范。这个命令会检查必填字段、触发条件是否过于宽泛、验收标准是否可验证等。

4.3 在Claude Code中激活和使用技能

技能写好了，接下来要让Claude Code用起来。在项目根目录的.claude/skills.md中添加：

# 已加载技能 - api-endpoint - test-driven-development - code-review

然后启动Claude Code，它会自动加载这些技能。你可以通过提问来验证技能是否生效：问它"帮我新增一个用户注册接口"，观察它的执行过程是否符合技能定义的步骤。

实测下来，加载技能后Claude Code的行为会有明显变化。没有技能时，它可能会直接写一个路由文件，把校验、业务逻辑、错误处理全塞在一起。加载了api-endpoint技能后，它会先确认接口规格，然后分步骤创建schema、service、route、test文件，最后提醒你更新文档。

4.4 技能的组合与嵌套

单个技能的能力有限，真正强大的是技能的组合。agent-skills支持在一个技能中引用其他技能。比如api-endpoint技能可以引用test-driven-development技能，在执行步骤中写"按照test-driven-development技能编写测试"。

这种嵌套引用让技能可以像函数一样被复用。你可以定义一些基础技能，比如"错误处理规范"、"日志规范"、"数据库操作规范"，然后在更复杂的技能中引用它们。这样当基础规范变化时，只需要修改一处，所有引用它的技能都会自动更新。

实际使用中，我建议把技能分为三层：原子技能（不可再分的最小规范）、组合技能（由多个原子技能组成的工作流）、项目技能（项目特定的完整流程）。这种分层让技能库既灵活又易于维护。

5. 常见问题与排查技巧实录

5.1 技能不生效的排查思路

最常见的问题是：技能文件写好了，但Claude Code好像完全没看到。排查顺序如下。

第一步，确认技能文件位置正确。项目技能必须在.skills/目录下，全局技能在~/.agent-skills/目录下。文件名必须以.md结尾。

第二步，确认技能已被加载。运行skills list查看当前项目加载了哪些技能。如果列表里没有你的技能，检查.claude/skills.md中是否列出了它。

第三步，确认触发条件匹配。如果技能加载了但没被激活，可能是触发条件写得太窄。试着把触发条件写得更通用一些，或者手动用skills run <name>强制激活。

第四步，检查技能定义是否有语法错误。YAML frontmatter中的字段名和缩进必须正确，否则解析会失败。用skills validate <name>可以快速定位问题。

5.2 技能冲突与优先级问题

当两个技能对同一件事给出不同约束时，就会发生冲突。比如一个技能说"所有函数必须写JSDoc注释"，另一个技能说"不允许写注释，代码应该自解释"。这种情况下，代理的行为会变得不可预测。

解决方法是明确优先级。在技能定义中设置priority字段，数值高的优先。同时，在编写技能时要检查是否与已有技能冲突。skills check命令可以检测技能之间的冲突，并给出解决建议。

我个人的经验是：约束规则越具体的技能，优先级应该越高。项目特定的技能优先级高于通用技能，流程技能优先级高于风格技能。这样保证在冲突时，更贴近当前项目实际情况的约束会胜出。

5.3 技能导致的上下文溢出

前面提到过，技能定义会占用上下文窗口。当加载的技能太多时，可能会出现代理"忘记"技能内容的情况。典型表现是：代理执行到一半突然不遵守约束了，或者开始重复已经完成的步骤。

排查方法是查看当前会话的上下文使用情况。Claude Code通常会显示剩余上下文百分比。如果低于30%，就需要考虑精简技能了。

精简策略有三个：一是合并功能相近的技能，二是把长技能拆分成按需加载的短技能，三是把技能中的详细说明移到外部文档，技能定义中只保留核心步骤和约束。

注意：不要为了节省上下文而删掉约束规则和验收标准。这两部分是技能质量的关键保障。宁可减少加载的技能数量，也不要削弱单个技能的定义完整性。

5.4 常见问题速查表

6. 技能库的维护与团队协作实践

6.1 技能版本管理与更新策略

技能定义是代码资产，应该像代码一样管理。我建议每个技能都遵循语义化版本，格式为主版本.次版本.修订号。当技能的约束规则发生不兼容变化时，递增主版本；当新增步骤或约束时，递增次版本；当修正错别字或调整措辞时，递增修订号。

团队协作中，技能库通常放在独立的Git仓库里。项目通过skills install从仓库拉取技能。当技能更新时，项目可以选择自动更新或手动确认。我建议对基础技能开启自动更新，对项目特定技能保持手动确认，避免意外变更影响项目稳定性。

6.2 技能效果的评估与迭代

写了一个技能，怎么知道它好不好用？我的做法是记录每次使用技能时的"返工率"。如果代理执行完技能后，我还需要手动修改超过30%的产出，说明技能定义有问题，需要迭代。

迭代的方向通常是：补充约束规则、细化执行步骤、增加验收标准。比如我发现代理总是忘记写错误处理的测试用例，就在TDD技能的验收标准里加上"异常情况的测试覆盖率不低于正常情况"。

另一个评估维度是"技能使用频率"。如果一个技能三个月都没被激活过，要么是触发条件写得太窄，要么是这个技能本身没有存在的必要。定期清理低使用率的技能，保持技能库的精简。

6.3 从个人技能到团队规范

个人使用技能和团队使用技能，最大的区别在于一致性要求。个人使用时，你可以容忍一定的模糊性，因为你自己知道想要什么。但团队使用时，技能定义必须足够精确，让不同的人、不同的代理实例都能得到一致的产出。

我的经验是：团队技能定义中，约束规则的数量应该是个人技能的两倍以上。因为个人技能中很多"不言自明"的约定，在团队场景下需要显式写出来。比如"提交信息要清晰"这种个人技能中不会写的内容，在团队技能中必须写成"提交信息必须包含类型前缀和不超过50字的描述"。

还有一个实践是定期做"技能评审"。每个月花半小时，团队成员一起过一遍当前使用的技能，讨论哪些约束需要调整、哪些步骤可以优化。这个过程本身就是团队对齐开发规范的好机会。

7. 我踩过的坑和最后分享的几个技巧

第一个坑是技能定义写得太长。我一开始恨不得把所有的编码规范都塞进一个技能里，结果技能文件超过2000字，加载后代理的上下文被严重挤占，执行任务时反而变得迟钝。后来我把技能拆成多个小文件，每个文件只解决一类问题，效果好了很多。单个技能定义控制在300到500字之间，是我实测下来比较理想的区间。

第二个坑是触发条件写得太技术化。我写过"当检测到AST中存在未处理的Promise时"这种触发条件，结果代理根本识别不了。触发条件应该用自然语言描述任务场景，而不是技术实现细节。改成"当需要修改异步函数时"，匹配率立刻上去了。

第三个坑是忽略技能的负面约束。早期我只写"应该做什么"，不写"不应该做什么"。结果代理在执行TDD技能时，虽然会先写测试，但也会顺手把生产代码也写了，完全违背了TDD的红绿重构节奏。后来我在约束规则里明确写了"在测试失败之前，不允许编写生产代码"，问题才解决。

最后分享一个小技巧：给技能加一个"示例"部分。在技能定义的最后，附上一个简短的输入输出示例，展示这个技能被正确执行时应该是什么样子。这个示例不需要很长，三五句话就够，但对代理理解技能意图非常有帮助。我试过在几个复杂技能里加了示例，执行准确率有明显提升。

还有一个技巧是用技能来沉淀项目特有的知识。每个项目都有一些"只有老成员才知道"的约定，比如某个模块的代码风格和其他模块不一样、某个接口的命名有历史原因不能改。把这些约定写成技能，新成员加入时一条命令就能获得这些知识，比口头传承靠谱得多。

这个方向后续还可以继续扩展，比如把技能和CI流程打通，在代码提交时自动检查是否遵守了相关技能约束；或者把技能和代码审查结合，让代理在审查代码时自动引用相关技能作为评判标准。这些我都还在摸索中，有新的心得再分享。