1. 从agent-skills说起一个被低估的工程化命题第一次看到agent-skills这个词很多人会下意识把它理解成给 AI 智能体写提示词。这个理解不算错但太浅了。真正做过一段时间 AI coding agents 的人会明白agent-skills本质上是一套可复用、可组合、可版本化的能力封装机制——它把让 AI 干某件事从一次性的对话变成了一份可以提交到仓库、可以被团队 review、可以被 CI 校验的工程资产。我最初接触这个概念是在折腾 Claude Code 的时候。当时我给它写了一大堆零散的提示词散落在各个项目的CLAUDE.md、临时笔记、聊天记录里。用着用着就发现一个致命问题同一个任务今天跑得好明天换个上下文就崩了。后来我才意识到问题不在于模型能力而在于我把能力和上下文混在了一起。agent-skills要解决的恰恰就是这个分离问题。这篇文章适合三类人看一是已经在用 Claude Code、Cursor、各类 AI coding agents但总觉得用得不顺手的开发者二是想把 AI 能力沉淀成团队规范、而不是每个人各自为战的技术负责人三是刚入门、还没搞清楚 skills CLI 和普通提示词区别的新手。我会从设计思路讲到实操落地把踩过的坑和验证过的方案都摊开说。需要先明确一点agent-skills不是某个厂商的专有名词它更像是一种约定俗成的工程模式。不同工具链对它的实现方式不同但核心思想是一致的——把技能从对话里抽出来做成独立单元。2. 核心设计思路为什么要把技能抽出来2.1 从提示词堆砌到技能单元的认知转变大部分人用 AI coding agents 的起点是在一个文件里堆提示词。比如在CLAUDE.md里写上一大段你是资深工程师写代码要遵循以下规范……测试要覆盖边界……提交信息要符合约定…… 这种写法在项目初期没问题但项目一复杂就失控。原因很简单提示词是线性的而任务是分支的。你写一个生成测试的任务和写一个重构模块的任务需要的上下文、约束、输出格式完全不同。把它们塞进同一个文件模型每次都要读一遍无关内容既浪费 token又容易串味。agent-skills的思路是把每个能力拆成独立单元。一个 skill 通常包含触发条件什么时候用、输入约定需要什么信息、执行步骤怎么做、输出规范交付什么、校验标准怎么算做对了。这五要素一旦固定下来这个 skill 就可以被反复调用而且每次行为一致。我打个生活化的比方提示词堆砌就像你每次做饭都从先买菜、再洗菜、再切菜开始口述一遍而 skill 就像你写好了一份菜谱卡片需要的时候抽出来照着做做完放回去。菜谱卡片可以改、可以传给别人、可以贴到冰箱上这就是工程化。2.2 为什么 test-driven-development 是天然的 skill 样板在所有 skill 里test-driven-developmentTDD是最适合拿来做样板的一个。原因有三第一流程极其明确。红-绿-重构三步走没有歧义。这种确定性强的流程最适合封装成 skill因为模型不需要发挥只需要执行。第二校验标准客观。测试跑没跑过是二元的不依赖主观判断。这让 skill 的完成定义非常清晰。第三复用频率高。几乎每个功能开发都要走一遍封装一次受益长期。我实测下来把 TDD 做成 skill 之后AI 生成代码的一次通过率明显提升。不是模型变聪明了而是它每次都被强制走先写失败测试这条路避免了先写实现再补测试这种自欺欺人的做法。2.3 skills CLI 在整条链路里的位置skills CLI是这套体系里的包管理器角色。它负责技能的安装、列举、更新、卸载。你可以把它理解成npm之于 JavaScript 包或者brew之于 macOS 软件。为什么需要一个 CLI而不是手动复制文件因为技能是需要版本管理的。你今天写了一个 skill明天发现有个边界情况没覆盖改了一版。如果靠手动复制团队里五个人可能用着五个版本。有了 CLIskills install xxx1.2.0一执行所有人对齐。提示skills CLI 的具体命令因工具链而异但核心动作install / list / update / remove基本一致。落地前先确认你所用 agents 工具是否原生支持还是需要社区方案。3. 核心细节拆解一个合格 skill 到底长什么样3.1 五要素结构触发、输入、步骤、输出、校验我拿一个真实项目里的 skill 举例名字叫add-api-endpoint功能是给现有服务新增一个 REST 接口。它的结构是这样的触发条件用户说加一个接口新增 endpoint实现某个 API时激活。输入约定需要接口路径、HTTP 方法、请求体结构、响应体结构、是否需要鉴权。执行步骤在路由文件里注册路径写 handler 函数骨架写请求参数校验写业务逻辑占位写单元测试先失败补实现让测试通过更新 API 文档输出规范改动文件列表 测试运行结果 文档 diff。校验标准测试全绿、lint 无报错、文档已更新。你看这五要素一旦写清楚这个 skill 就变成了一个可执行说明书。模型拿到它不需要猜照着走就行。团队新人拿到它也知道这个项目的接口开发规范是什么。3.2 触发条件的写法宁窄勿宽新手写 skill 最容易犯的错是把触发条件写得太宽。比如写当用户需要写代码时激活。这种触发条件等于没写因为几乎所有任务都符合。我的经验是触发条件要窄到能明确排除掉不该激活的场景。比如add-api-endpoint的触发条件里我会明确写不适用于修改已有接口的返回结构那种情况走modify-api-responseskill。这样做的好处是避免 skill 之间打架。当你有十几个 skill 的时候如果触发条件都写得很宽模型会不知道该用哪个最后要么乱用要么不用。3.3 输入约定的价值把猜变成问很多人忽略输入约定这一环觉得模型自己会问。实测下来模型确实会问但问得没章法有时候问一堆无关的有时候该问的不问。明确写输入约定等于给模型一份必问清单。缺什么问什么不缺就不问。这能显著减少来回对话的轮次。我做过一个对比同一个新增接口任务没有输入约定的 skill 平均要 4-5 轮对话才能开工有输入约定的 skill通常 1-2 轮就能进入执行。省下来的时间累积起来很可观。3.4 输出规范与校验标准让完成可判定完成这个词在 AI 协作里特别模糊。模型说我做完了你一看测试没跑、文档没更新、边界没处理。所以 skill 必须定义清楚什么叫做完。我的做法是把校验标准写成可执行的检查项而不是描述性语言。比如不写代码质量良好而写npm test全绿且覆盖率不低于 80%。这样模型自己就能判断有没有做完不需要你反复确认。下面这张表是我总结的描述性标准 vs 可执行标准对照供参考描述性标准不推荐可执行标准推荐代码质量良好lint 无 error复杂度不超过阈值测试覆盖充分行覆盖率 ≥ 80%分支覆盖率 ≥ 70%文档已更新README 对应章节 diff 非空性能可接受基准测试 P95 延迟 200ms兼容性没问题目标运行时版本矩阵全部通过4. 实操过程从零搭一套可用的 skills 体系4.1 环境准备与工具链确认在动手之前先确认你的工具链。以 Claude Code 为例它本身支持通过项目根目录的配置文件来定义行为但skills这种模块化能力通常需要配合社区方案或自建目录结构。我的建议是先在项目里建一个skills/目录每个 skill 一个子目录里面放一个SKILL.md。这个结构简单、直观、不依赖任何特定工具任何 agents 都能读。mkdir -p skills/add-api-endpoint touch skills/add-api-endpoint/SKILL.md如果你用的工具链有原生 skills 支持那就按它的规范来。如果没有这套目录结构也能用只是需要你在主配置文件里手动引用。注意不同 agents 工具对 skill 文件的解析方式不同。有的要求 YAML frontmatter有的要求纯 Markdown。落地前先看官方文档别想当然。4.2 写第一个 skill以 TDD 为例的完整模板下面是我实际在用的 TDD skill 模板你可以直接抄--- name: test-driven-development trigger: 当需要实现新功能、修复 bug、或重构代码时 inputs: - 目标行为描述 - 涉及的模块/文件 - 验收标准 steps: 1. 根据目标行为写出一个会失败的测试 2. 运行测试确认它确实失败红 3. 写最小实现让测试通过绿 4. 运行全部测试确认没有破坏其他功能 5. 重构代码保持测试全绿 6. 重复 1-5 直到目标行为全部覆盖 outputs: - 测试文件 diff - 实现文件 diff - 测试运行结果 validation: - 新增测试全部通过 - 原有测试无回归 - 覆盖率不低于改动前 --- # TDD Skill ## 核心原则 先写测试再写实现。禁止先写实现再补测试。 ## 常见陷阱 - 测试写得太宽泛无法定位失败原因 - 实现写得太多一次让多个测试通过 - 重构阶段引入新行为重构不应改变行为这个模板的关键在于validation部分。它让做完有了客观标准模型自己就能判断。4.3 用 skills CLI 管理版本与依赖当你有了五六个 skill 之后手动管理就开始痛苦了。这时候 skills CLI 就派上用场。典型的工作流是这样的# 列出当前项目已安装的 skills skills list # 安装一个社区 skill skills install tdd-workflowlatest # 锁定版本避免自动升级带来意外 skills install tdd-workflow1.2.0 # 更新所有 skills 到最新兼容版本 skills update # 移除不再需要的 skills remove old-skill版本锁定这一步特别重要。我踩过一次坑某个 skill 自动升级后输出格式变了导致下游的自动化脚本解析失败。后来我养成了习惯生产项目里所有 skill 都锁版本升级前先在测试分支验证。4.4 把 skill 接入 CI让规范变成硬约束skill 最大的价值是能变成 CI 的一部分。比如 TDD skill 的校验标准是测试全绿那就在 CI 里加一步跑测试不绿就拒绝合并。# .github/workflows/verify.yml 片段 - name: Run tests run: npm test -- --coverage - name: Check coverage run: | COVERAGE$(cat coverage/summary.json | jq .total.lines.pct) if (( $(echo $COVERAGE 80 | bc -l) )); then echo Coverage $COVERAGE% below 80% exit 1 fi这样一来skill 里写的规范就不再是建议而是必须。AI 生成的代码要过 CI人写的代码也要过 CI标准统一。5. 常见问题与排查技巧实录5.1 skill 不激活或激活错误怎么办这是最高频的问题。排查思路按顺序来第一步检查触发条件是否太窄。如果触发词写得太具体用户换个说法就激活不了。比如只写新增接口用户说加个 endpoint就不认。解决办法是列同义词。第二步检查是否有多个 skill 触发条件重叠。重叠会导致模型随机选一个或者干脆不用。解决办法是给每个 skill 加排除条件。第三步检查 skill 文件是否被正确加载。有的工具需要显式声明 skill 路径光放文件不生效。看日志确认。下面这张速查表是我整理的常见症状与对策症状可能原因对策skill 完全不激活文件未被加载检查配置里的 skill 路径声明激活了但行为不对触发条件太宽收窄触发条件加排除项多个 skill 抢触发条件重叠明确优先级或互斥条件输出格式不稳定输出规范不具体用 schema 或模板约束校验总是不通过校验标准不可执行改成可执行检查项升级后行为变化未锁版本生产环境锁版本5.2 上下文超限skill 太多反而变慢有个反直觉的现象skill 装得越多AI 反而越慢、越容易出错。原因是每个 skill 都要占用上下文窗口装了几十个之后真正有用的信息被挤出去了。我的做法是按项目裁剪。一个项目只装它真正需要的 skill通常 5-10 个足够。跨项目的通用 skill 放在全局项目特有的放在项目目录。定期清理不用的。提示如果你发现 AI 开始忘记之前说过的约束先怀疑是不是 skill 装太多导致上下文被挤占而不是模型变笨了。5.3 skill 之间的冲突与优先级当两个 skill 都能处理同一个任务时必须定义优先级。我的经验是越具体的 skill 优先级越高。比如add-api-endpoint比通用的write-code更具体所以前者优先。实现方式有两种一是在触发条件里写排除二是在配置里显式排序。前者更可靠因为它不依赖工具链的排序实现。5.4 团队协作skill 的 review 与演进skill 是代码资产就该走代码 review 流程。我们团队的做法是skill 改动必须提 PR至少一人 review改动触发条件或校验标准的必须附上测试用例。演进节奏上我建议小步快跑。不要憋一个大版本而是发现一个问题就改一版。skill 的价值在于持续打磨不在于一次写完美。6. 影响范围与延展思考agent-skills这套东西表面上是提示词工程实际上是团队知识管理。它把老员工脑子里的经验变成了新人能直接调用的资产。这个价值远超省几轮对话。从影响范围看它至少改变了三件事一是 AI 协作从个人技巧变成团队规范二是代码质量从事后 review前移到生成时约束三是知识传承从口口相传变成版本化文件。我个人在实际操作中的体会是别一上来就追求大而全的 skill 库。先挑一个你每天都在重复的任务把它做成 skill用一周改三版跑顺了再复制这个模式做第二个。我见过太多人一口气写二十个 skill结果一个都没用起来。慢就是快这话在 skill 工程里特别成立。最后再分享一个小技巧给每个 skill 写一句这个 skill 不解决什么问题。这句话能帮你守住边界避免 skill 无限膨胀成一个什么都管的怪物。边界清晰的 skill才是能长期复用的 skill。