1. 从“agent-skills”说起为什么它值得单独拿出来聊第一次看到agent-skills这个项目名我脑子里蹦出来的不是某个具体工具而是一类正在快速成型的东西——给 AI coding agents 用的技能包。你可以把它理解成一套“插件化的能力说明书”把测试驱动开发、代码审查、提交规范、重构流程这些原本靠人记在脑子里的工程习惯拆成一个个可被 agent 加载、调用、复用的 skill。它解决的核心问题很直接——同一个 agent为什么在 A 项目里像个老手在 B 项目里却像个实习生答案往往不在模型本身而在于你有没有把“这个项目该怎么干活”讲清楚。agent-skills这类项目通常围绕一个skills CLI展开配合Claude Code这类 AI coding agent 使用。它适合三类人一是已经在用 Claude Code、但觉得输出质量忽高忽低的开发者二是想把团队工程规范沉淀下来、不想每次靠 prompt 复述的 tech lead三是刚接触 AI coding agents、想找个靠谱起点的新手。我下面会从设计思路、核心机制、实操落地、踩坑排查几个角度把这类项目拆开讲透尽量让你看完就能自己动手搭一套。2. 核心设计思路为什么是“技能”而不是“提示词”2.1 提示词会漂移技能不会大多数人用 AI coding agent 的方式是打开对话框敲一段 prompt比如“帮我用 TDD 写一个函数”。问题在于这段 prompt 每次都要重敲而且措辞一变agent 的行为就跟着变。今天你说“先写测试”它老老实实 TDD明天你说“顺便写个测试”它可能先写完实现再补测试——顺序一反TDD 的意义就没了。agent-skills的思路是把这类流程固化成结构化的技能单元。一个 skill 通常包含触发条件什么时候用、执行步骤怎么做、约束不能做什么、验收标准做完长什么样。这跟 prompt 的本质区别在于prompt 是“一次性指令”skill 是“可复用资产”。前者靠记忆后者靠文件。提示判断一个流程值不值得做成 skill标准很简单——如果这个流程你一个月内重复说了三次以上就该沉淀下来。2.2 技能包的分层结构我见过的agent-skills类项目目录结构大同小异核心是三层技能定义层每个 skill 一个目录或文件里面写清楚元信息名称、描述、适用场景和具体指令。加载层skills CLI负责扫描、注册、按需注入到 agent 的上下文里。执行层agent 在真实任务中命中某个 skill按里面的步骤走。这种分层的好处是解耦。技能定义不关心你用的是 Claude Code 还是别的 agent加载层不关心技能内容是什么执行层只负责跑。你换模型、换工具技能资产不用重写。2.3 为什么选 TDD 作为典型技能热搜词里test-driven-development出现得很频繁这不是偶然。TDD 是少数流程顺序比结果更重要的工程实践先写测试、看它失败、再写实现、看它通过、最后重构。这个顺序一旦被打乱TDD 就退化成“补测试”。而 AI agent 恰恰容易“抄近路”——它倾向于直接给你一个能跑的完整实现因为那样看起来更高效。把 TDD 做成 skill本质上是用结构对抗模型的惰性。skill 里明确写“第一步只能写测试禁止写实现”agent 就没法跳步。这比在 prompt 里反复强调“一定要先写测试”可靠得多。3. 核心机制拆解skills CLI 到底在做什么3.1 技能发现与注册skills CLI的第一个职责是发现。它通常会在约定目录比如项目根目录下的.agent-skills/或用户主目录下的配置目录里扫描技能文件。扫描逻辑一般支持两种粒度单文件技能和目录技能。单文件适合简单流程目录适合带辅助资源模板、脚本、示例的复杂技能。注册环节的关键是元信息解析。每个 skill 头部通常有一段结构化描述类似name: tdd-workflow description: 强制按测试驱动开发流程执行编码任务 triggers: - 写新功能 - 实现函数 - 添加模块 constraints: - 禁止在测试通过前编写实现代码CLI 解析这段元信息后建立索引。当 agent 接到任务时CLI 根据任务描述匹配 triggers决定注入哪些 skill。3.2 上下文注入的时机与粒度这是最容易被忽略、也最影响效果的一环。技能注入不是越多越好。我实测下来同时注入超过 3 个 skillagent 的注意力就会明显分散开始顾此失彼。所以好的skills CLI会做优先级排序和数量控制。注入时机一般有两种前置注入任务开始前根据任务类型一次性注入相关 skill。按需注入agent 执行到某一步时动态拉取对应 skill。前置注入简单可靠适合流程固定的场景按需注入灵活但对 CLI 的匹配能力要求高。我个人的选择是混合核心流程如 TDD前置注入辅助技能如提交规范按需注入。3.3 技能之间的依赖与冲突技能不是孤立的。tdd-workflow可能依赖code-review而code-review又可能和fast-prototype冲突——一个要求严谨一个要求快。skills CLI需要处理这种依赖和冲突。处理方式通常是声明式依赖 冲突标记。在 skill 元信息里写明depends_on和conflicts_withCLI 在加载时做拓扑排序和冲突检测。如果检测到冲突要么报错要么按优先级取舍。这块做得好不好直接决定了技能包能不能规模化。4. 实操落地从零搭一套可用的技能包4.1 环境准备与 CLI 安装假设你已经装好了 Claude Code并且能在终端里正常调用。接下来是skills CLI的安装。不同项目的安装方式不一样常见的是通过包管理器# 以 npm 为例具体以项目文档为准 npm install -g agent-skills-cli # 验证安装 skills --version装完之后通常需要初始化一个技能目录skills init这个命令会在当前目录创建.agent-skills/文件夹和一个示例技能。如果你是在已有项目里接入建议把.agent-skills/提交到版本库这样团队每个人拉下来就能用同一套技能。注意CLI 的全局安装和项目级配置要分清。全局装的是工具本身项目级放的是技能内容。别把技能文件塞进全局目录否则换个项目就串味了。4.2 编写第一个技能以 TDD 为例我拿 TDD 举例写一个最小可用的 skill 文件.agent-skills/tdd-workflow.md--- name: tdd-workflow description: 强制按测试驱动开发流程执行编码任务 triggers: - 写新功能 - 实现函数 - 添加模块 constraints: - 禁止在测试通过前编写实现代码 - 每次只处理一个测试用例 --- ## 执行步骤 1. 理解需求写出第一个失败的测试用例 2. 运行测试确认它失败红 3. 编写最小实现让测试通过绿 4. 运行全部测试确认没有破坏其他功能 5. 重构保持测试通过 6. 重复 1-5直到需求完成 ## 验收标准 - 每个功能点都有对应测试 - 测试先于实现存在 - 重构后测试仍全部通过这里有几个细节值得说。triggers要写得具体但不啰嗦“写新功能”比“编程”好“实现函数”比“写代码”好。constraints是灵魂它把“不能做什么”写死比正面描述“要做什么”更能约束 agent 的行为。4.3 加载与验证写完技能后用 CLI 加载skills load然后给 agent 一个任务比如“实现一个计算斐波那契数列的函数”。观察它的行为如果它先写测试、跑测试、看失败、再写实现说明 skill 生效了。如果它直接甩给你一个完整实现说明触发条件没匹配上或者注入没成功。验证环节我建议故意制造一次失败。比如把 skill 里的约束临时删掉看 agent 行为是否变化。如果删不删都一样说明这个 skill 根本没起作用得回头查加载链路。4.4 技能的组合与编排单个技能跑通后就可以考虑组合了。比如一个完整的开发流程可能是tdd-workflow→code-review→commit-convention。编排方式有两种串行前一个技能完成后触发下一个。并行多个技能同时注入agent 自行协调。串行可靠但慢并行快但容易乱。我的经验是核心流程串行辅助检查并行。TDD 和 code review 串行提交规范和文档生成可以并行。5. 常见问题与排查技巧实录5.1 技能不生效的排查路径这是最高频的问题。排查顺序建议从外到内排查层级检查项常见原因CLI 层skills list能否看到技能文件没被扫描到路径不对元信息层元信息格式是否正确YAML 语法错误字段名拼错匹配层triggers 是否命中任务触发词太窄或太宽注入层上下文里是否有技能内容注入数量超限被截断执行层agent 是否遵守约束约束描述太模糊我踩过最坑的一次是 YAML 缩进用了 TabCLI 解析直接静默失败skills list里啥都没有查了半天才发现是缩进问题。5.2 技能冲突导致行为混乱当两个技能对同一件事给出相反指令时agent 会表现得“精神分裂”。比如tdd-workflow要求先写测试fast-prototype要求先出可运行版本。解决办法是在元信息里显式声明冲突conflicts_with: - fast-prototypeCLI 检测到冲突后要么报错让你手动选要么按优先级自动取舍。千万别指望 agent 自己协调它只会随机选一个而且每次选的可能还不一样。5.3 上下文超限与技能裁剪技能写得太长注入后会把上下文撑爆导致 agent 丢失关键信息。我的一般原则是单个 skill 正文控制在 500 字以内超出的部分拆成子技能或放到辅助文件里按需加载。如果确实需要长技能可以用“摘要 详情”结构注入时只给摘要agent 需要细节时再通过 CLI 拉取完整内容。这样既省上下文又不丢信息。5.4 跨项目复用的坑把技能包从一个项目搬到另一个项目最容易出问题的是路径依赖和工具假设。比如某个技能里写了“运行npm test”但新项目用的是pnpm。解决办法是把这类环境相关的命令抽成变量在项目级配置里覆盖。# 项目级配置 test_command: pnpm test技能里引用{{test_command}}CLI 在注入时替换。这样技能本身保持通用项目差异在配置层解决。6. 进阶玩法让技能包自己进化6.1 从失败中沉淀新技能每次 agent 犯错都是一次技能沉淀的机会。比如你发现它总是忘记处理边界条件那就写一个edge-case-checklist技能在写测试时自动注入。久而久之你的技能包会越来越贴合项目的真实痛点。我习惯在项目里维护一个lessons.md记录每次 agent 翻车的场景和对应的技能改进。攒到一定量就批量更新技能包。6.2 技能版本管理技能包也是代码需要版本管理。建议给每个技能加version字段并在 CHANGELOG 里记录变更。当技能行为发生不兼容变化时升大版本号让团队成员知道要重新适配。name: tdd-workflow version: 1.2.06.3 与 CI 的结合技能包跑在本地是一回事跑在 CI 里是另一回事。CI 环境没有交互式终端agent 的行为可能不同。我的做法是在 CI 里只启用确定性强的技能如代码格式检查、提交规范把需要交互的技能如 TDD 的逐步确认留在本地。这样既保证了 CI 的稳定性又不牺牲本地的灵活性。7. 我个人的一些实操体会搭agent-skills这套东西最大的收获不是让 agent 变聪明了而是逼着我把团队的工程习惯写清楚。很多规范平时靠口口相传写进技能文件的时候才发现漏洞百出——原来我们自己都没统一过“什么叫测试通过”。另一个体会是别贪多。我一开始恨不得把所有流程都做成技能结果 agent 被一堆约束绑得死死的反而不会干活了。后来砍到只剩三个核心技能效果反而更好。技能包的价值不在于覆盖多少场景而在于每个技能都真的被用上、真的解决问题。最后分享一个小技巧给每个技能写一句“反例”。比如 TDD 技能里加一句“反例先写实现再补测试即使测试最终通过也不算完成”。反例比正例更能约束 agent因为它直接堵死了那条“看起来更高效”的捷径。这个技巧我用了大半年实测下来对减少 agent 偷懒非常有效。