1. 从“agent-skills”说起为什么我们需要给AI编码代理装上一套技能系统第一次看到agent-skills这个项目名的时候我脑子里冒出来的第一个念头是这不就是给 AI coding agents 做的一套“技能包”吗后来翻了一圈资料、自己动手跑了几轮发现这个判断基本靠谱但远不止“技能包”这么简单。它更像是一套面向 AI 编码代理的能力编排层把原本散落在各个提示词、脚本、配置文件里的“怎么让代理干好一件事”的经验沉淀成可复用、可组合、可测试的标准化单元。说白了现在用 Claude Code、Cursor、各种 AI coding agents 的人越来越多但大部分人还停留在“写一段提示词让模型帮我改个 bug”的阶段。问题在于提示词这东西太脆弱了——换个模型、换个项目、换个人来写效果天差地别。agent-skills想解决的就是这个把“让代理完成某类任务”的最佳实践固化成 skill通过一个 skills CLI 来管理、调用、组合再配合 test-driven-development 的思路去验证 skill 到底有没有用。这套东西适合谁我觉得三类人最该关注。第一类是已经在日常开发里重度使用 Claude Code 或其他 AI coding agents 的工程师你肯定遇到过“同一个任务昨天跑得好好的今天模型一升级就翻车”的情况。第二类是想把 AI 编码能力引入团队协作的技术负责人你需要一套可复制、可审计的机制而不是每个人各自维护一堆提示词。第三类是喜欢折腾工具链的独立开发者skills CLI 这种命令行工具天然对这类人友好。我自己的使用场景比较典型手头有几个长期维护的项目代码风格、测试规范、提交信息格式都有固定要求。以前每次让 AI 代理改代码都要把这一大段上下文重新贴一遍烦不说还经常漏。用了agent-skills之后这些规范被拆成独立的 skill代理在执行任务时会自动加载相关技能省心很多。下面我就把这套东西的设计思路、核心机制、实操步骤和踩过的坑完整地聊一遍。2. 整体设计思路拆解为什么是“技能”而不是“提示词”2.1 提示词工程的瓶颈到底在哪先说说为什么传统的提示词方案会让人越用越累。我总结下来有三个核心问题。第一个是上下文漂移。你写了一段很长的系统提示词里面规定了代码风格、测试要求、错误处理方式。但对话轮次一多模型对前面内容的注意力就会衰减到后面它可能只记得你最后说的那几句话。这不是模型不行而是当前上下文窗口机制决定的。第二个是不可组合。假设你有一个“写单元测试”的提示词还有一个“重构函数”的提示词。现在你想让代理先重构再补测试怎么办把两段提示词拼起来拼完之后长度爆炸而且两段提示词里可能有冲突的指令模型不知道该听谁的。第三个是无法验证。你怎么知道一段提示词是真的有效还是只是这次运气好没有测试没有回归改了一个词可能整体效果就崩了但你根本不知道是哪个词的问题。agent-skills的设计思路本质上就是把软件工程里“模块化、可组合、可测试”这一套搬到 AI 代理的能力管理上。每个 skill 是一个独立单元有明确的输入输出、有触发条件、有验证方式。代理在执行任务时根据当前上下文动态加载需要的 skill而不是一次性把所有指令都塞进去。2.2 skill 的粒度怎么定这是我在实际使用中觉得最需要想清楚的问题。skill 太粗比如“写一个完整功能”那跟直接写提示词没区别skill 太细比如“在函数末尾加一个换行”那管理成本比收益还高。我自己的经验是一个 skill 的合适粒度应该满足两个条件有明确的触发场景以及有可验证的输出。举个例子“为 Python 函数生成 pytest 单元测试”就是一个好 skill——触发场景清晰用户要求补测试输出可验证跑 pytest 看是否通过。“让代码更好看”就不是一个好 skill因为触发场景模糊输出也无法验证。在agent-skills的体系里我一般会把 skill 分成三层。最底层是原子技能比如“读取文件内容”“执行终端命令”“解析 JSON 输出”这些是代理的基础能力。中间层是领域技能比如“按项目规范写测试”“按约定格式提交代码”“生成 API 文档”。最上层是工作流技能比如“完成一个 bug fix 的完整流程”它会组合多个领域技能和原子技能。这种分层的好处是底层技能稳定不变上层技能可以灵活调整。当项目规范变了我只需要改中间层的领域技能不用动底层。当模型升级了我只需要重新验证底层技能是否还正常工作。2.3 为什么强调 test-driven-development热词里出现了 test-driven-development这不是偶然的。agent-skills把 TDD 的思路引入到 skill 开发本身我觉得这是它最有价值的设计之一。传统 TDD 是“先写测试再写实现”。对应到 skill 开发就是先定义“这个 skill 在什么输入下应该产生什么输出”然后写 skill 的实现最后跑测试验证。听起来很朴素但实际做起来会发现大部分人在写提示词的时候根本没想过“怎么算成功”。我举个自己的例子。之前我写了一个“自动修复 lint 错误”的 skill一开始觉得挺简单把 lint 报错信息给代理让它改代码。结果跑了几次发现有时候代理会把代码改得面目全非lint 是过了但逻辑错了。后来我按照 TDD 的思路先定义测试用例给定一段有特定 lint 错误的代码修复后必须满足“lint 通过”且“原有测试全部通过”且“代码改动行数不超过 N 行”。有了这三个约束skill 的实现方向就清晰多了效果也稳定了很多。提示skill 的测试用例不需要很复杂但一定要覆盖“正常情况”“边界情况”和“失败情况”三类。失败情况尤其重要它能帮你发现 skill 在什么条件下会失控。3. 核心细节解析与实操要点skills CLI 到底怎么用3.1 安装与环境准备agent-skills的核心入口是 skills CLI。我是在 Ubuntu 环境下折腾的Mac 上流程基本一致。安装方式通常有两种通过包管理器全局安装或者从源码构建。我建议先用全局安装跑通流程确认符合需求后再考虑源码方式。# 以 npm 生态为例的全局安装方式 npm install -g agent-skills/cli # 验证安装是否成功 skills --version安装完成后第一件事是初始化工作目录。skills CLI 一般会在用户目录下创建一个配置文件夹用来存放 skill 定义、缓存和日志。你可以通过skills init来生成默认配置。skills init # 输出类似 # Created ~/.agent-skills/config.json # Created ~/.agent-skills/skills/ # Created ~/.agent-skills/logs/这里有个细节值得注意配置目录的位置最好放在项目之外。我一开始把 skills 目录放在项目仓库里结果每次提交代码都会把 skill 的缓存文件带进去后来改成全局目录就清爽了。如果你确实需要项目级的 skill可以用skills init --local在当前目录生成但记得把缓存和日志加到.gitignore里。3.2 skill 的定义结构一个 skill 通常包含几个核心字段名称、描述、触发条件、执行逻辑、验证方式。我用一个实际例子来说明。name: python-pytest-generator description: 为指定的 Python 函数生成 pytest 单元测试 triggers: - 为这个函数写测试 - 补充单元测试 - generate tests for inputs: - name: target_file type: file_path required: true - name: function_name type: string required: false outputs: - name: test_file type: file_path validation: command: pytest {test_file} -v success_criteria: exit_code 0这个结构里我觉得最容易被忽视的是triggers和validation。触发条件写得太宽skill 会在不该触发的时候触发写得太窄又经常匹配不上。我的经验是触发条件要包含用户可能说的原话而不是你自己总结的抽象描述。比如用户更可能说“帮我补个测试”而不是“执行单元测试生成流程”。验证方式则是 skill 质量的保障。没有验证的 skill本质上就是一段提示词你永远不知道它下次会不会翻车。3.3 在 Claude Code 中接入 skillsClaude Code 是我用得最多的 AI coding agent把 skills CLI 接进去之后整个工作流会顺畅很多。接入方式一般是在 Claude Code 的配置里指定 skill 的加载路径或者通过 MCPModel Context Protocol的方式把 skills CLI 暴露成一个工具服务。我采用的是配置文件方式在 Claude Code 的 settings 里加上{ skills: { enabled: true, cli_path: /usr/local/bin/skills, auto_load: [python-pytest-generator, git-commit-formatter] } }auto_load里列出的 skill 会在每次会话开始时自动加载。这里有个坑不要一次性加载太多 skill。我一开始把十几个 skill 全设成自动加载结果每次对话的上下文里都塞满了 skill 描述模型反而抓不住重点。后来改成只自动加载最常用的两三个其他的按需触发效果好很多。如果你用的是 VS Code 里的 Claude Code 插件配置方式类似但要注意插件版本和 CLI 版本的兼容性。我遇到过插件升级后 CLI 路径失效的情况重新在设置里指一遍就好。3.4 用 cc switch 切换不同模型时的注意事项热词里提到了用 cc switch 接入 deepseek、qwen、glm 等模型。这个场景下使用agent-skills需要特别注意一点不同模型对 skill 定义的理解能力差异很大。我实测下来Claude 系列模型对结构化 skill 定义的遵循度最高qwen 和 glm 在中文场景下表现不错但在处理复杂的多步 skill 时偶尔会跳步。deepseek 在代码类任务上表现可以但对触发条件的匹配有时候过于宽松。我的应对策略是为不同模型准备不同的 skill 变体。比如同一个“生成测试”的 skill给 Claude 用的版本可以写得简洁一些给其他模型用的版本则需要把步骤拆得更细、把约束写得更明确。skills CLI 支持通过--profile参数加载不同的 skill 配置集这个功能在多模型切换时非常实用。# 为不同模型加载不同的 skill 配置 skills run --profile claude-profile 为 utils.py 里的 parse_config 函数写测试 skills run --profile qwen-profile 为 utils.py 里的 parse_config 函数写测试注意切换模型后建议先跑一遍 skill 的验证用例确认新模型下 skill 仍然按预期工作。我踩过一次坑换模型后没验证结果代理生成的测试文件路径全错了排查了半天才发现是模型对路径参数的理解有偏差。4. 实操过程与核心环节实现从零搭一个可用的 skill4.1 需求拆解与 skill 设计假设我们要做一个实际场景让 AI 代理按照团队规范自动生成 Git 提交信息。这个需求看起来简单但要做好并不容易因为提交信息有格式要求、有内容要求、还有长度限制。我先把这个需求拆成几个可验证的点。格式上团队规定用 Conventional Commits 风格即type(scope): description。内容上description 要准确概括改动不能太笼统。长度上首行不超过 72 个字符。另外还要考虑边界情况如果改动涉及多个不相关的文件怎么办如果改动只是格式化怎么办拆完之后skill 的设计就清晰了。触发条件是用户说“生成提交信息”或“commit message”。输入是当前暂存区的 diff。输出是一条符合规范的提交信息。验证方式是检查格式正则、检查长度、以及人工确认内容准确性。4.2 skill 实现的关键步骤实现这个 skill 的核心逻辑分三步。第一步是获取 diff这可以通过git diff --staged命令拿到。第二步是把 diff 和规范要求一起交给模型让它生成提交信息。第三步是对生成结果做格式校验不合格就重试。# 获取暂存区 diff git diff --staged --stat git diff --staged这里有个实操细节diff 太长的时候要截断。我有一次改了一个大文件diff 有几千行直接塞给模型导致上下文超限。后来改成先用--stat看改动概览如果文件太多或改动太大就只取每个文件的关键改动片段。格式校验用正则就能搞定import re def validate_commit_message(msg): pattern r^(feat|fix|docs|style|refactor|test|chore)(\(.\))?: .{1,50}$ first_line msg.split(\n)[0] if not re.match(pattern, first_line): return False, 格式不符合 Conventional Commits 规范 if len(first_line) 72: return False, 首行超过 72 字符 return True, OK校验不通过时把失败原因反馈给模型让它重新生成。我一般设置最多重试 3 次超过就放弃并提示用户手动处理。4.3 参数选择与阈值设定在 skill 实现过程中有几个参数需要仔细选择。重试次数设成 3 次是我试出来的平衡点。1 次太少模型偶尔抽风就失败了5 次太多浪费时间且后面几次质量通常更差。diff 截断阈值我设的是单个文件 diff 超过 500 行就截断总 diff 超过 2000 行就只保留 stat 概览。这个阈值可以根据你项目的实际情况调整核心原则是保证模型能看到足够的上下文又不至于超限。温度参数生成提交信息这种任务温度设低一些0.2 到 0.3比较合适输出更稳定。如果是创意类任务可以适当调高。验证严格度格式校验必须严格内容校验可以宽松一些。因为格式是硬性要求内容好坏有时候需要人来判断。4.4 完整运行记录我把这个 skill 跑了一遍完整的流程记录如下。首先暂存几个文件的改动然后触发 skillgit add src/utils.py src/config.py skills run git-commit-formatterskill 输出的中间过程[INFO] 获取暂存区 diff... [INFO] 检测到 2 个文件改动共 87 行新增12 行删除 [INFO] 调用模型生成提交信息... [INFO] 生成结果: feat(config): 增加配置项校验逻辑 [INFO] 格式校验通过 [INFO] 长度校验通过 (首行 38 字符) [INFO] 提交信息已复制到剪贴板整个过程大概 3 到 5 秒比我手动写提交信息快不少而且格式从来不会错。用了一段时间之后我发现团队里其他人的提交信息风格也慢慢统一了因为大家都用同一个 skill。5. 常见问题与排查技巧实录5.1 skill 不触发或误触发怎么办这是最常见的问题。skill 不触发通常是触发条件写得太窄。比如你写的是“生成 pytest 测试”但用户说的是“补个测试”那就匹配不上。解决办法是把触发条件写得更口语化覆盖多种表达方式。误触发则相反触发条件太宽。我写过一个“优化代码”的 skill结果用户说“优化一下这个查询”的时候也触发了但那个场景其实更适合用数据库相关的 skill。后来我把触发条件改得更具体加上“优化代码结构”“重构这个函数”这类明确表述。排查的时候可以用skills debug命令它会显示当前输入匹配到了哪些 skill、匹配分数是多少。这个工具帮我省了很多时间。5.2 模型不按 skill 定义执行有时候模型会忽略 skill 里的某些约束比如你规定了输出格式它偏不按格式来。这种情况我一般从三个方向排查。第一检查 skill 定义是不是太复杂。如果约束太多模型可能顾此失彼。我一般会把约束控制在 5 条以内超过就拆成多个 skill。第二检查约束的表述是不是有歧义。比如“输出简洁的代码”就很模糊“输出不超过 20 行的代码”就明确得多。第三检查模型本身的能力。有些模型对结构化指令的遵循度就是差一些这时候要么换模型要么把 skill 拆得更细。5.3 常见问题速查表问题现象可能原因排查方法解决方向skill 不触发触发条件太窄skills debug看匹配分数补充口语化触发词skill 误触发触发条件太宽检查匹配分数是否过低增加限定词提高匹配精度输出格式错误约束表述模糊查看 skill 定义用具体数值替代模糊描述执行超时diff 或输入太大查看日志中的输入大小增加截断逻辑换模型后失效模型理解差异跑验证用例准备模型专属 skill 变体重试多次仍失败skill 逻辑有缺陷手动执行一遍流程拆解 skill 或调整参数5.4 几个我踩过的坑第一个坑是skill 之间互相干扰。我有两个 skill一个负责生成测试一个负责重构代码。结果有一次让代理重构一个函数它顺手把测试也生成了但生成的测试是针对重构前代码的完全跑不通。后来我在 skill 定义里加了互斥标记同一时间只允许一个 skill 处于激活状态。第二个坑是验证用例过时。项目结构变了之后原来的验证命令路径失效了但 skill 还在跑只是验证永远失败。我现在的做法是每次项目结构有大调整就顺手跑一遍所有 skill 的验证用例。第三个坑是过度依赖自动加载。前面提过自动加载太多 skill 会稀释上下文。我现在的策略是只自动加载那些“每次会话都可能用到”的 skill其他的通过显式调用触发。提示定期用skills list --unused检查哪些 skill 很久没被触发过。这些 skill 要么是触发条件有问题要么是已经不需要了该删就删保持 skill 库精简。6. 把 skill 用出复利一些进阶思路6.1 skill 的版本管理与团队共享一个人用 skill 和团队用 skill复杂度完全不是一个量级。团队场景下skill 需要版本管理需要 code review需要处理冲突。我的做法是把 skill 定义文件放在一个独立的 Git 仓库里通过 skills CLI 的--registry参数指向这个仓库。每次修改 skill 都走正常的 PR 流程有人 review 之后再合并。这样既能保证质量又能留下变更记录。版本管理还有一个好处是回滚。有一次我改了一个 skill 的触发条件结果导致它在不该触发的时候频繁触发。还好有版本记录直接回滚到上一个版本就恢复了。6.2 用 skill 组合出复杂工作流单个 skill 能做的事有限但组合起来就很强了。我现在有一个“完整 bug fix 工作流”它实际上是由四个 skill 串联而成的定位问题、生成修复、补充测试、生成提交信息。串联的方式是在工作流 skill 里定义步骤和依赖关系name: bugfix-workflow steps: - skill: locate-issue output: issue_context - skill: generate-fix input: issue_context output: fix_diff - skill: generate-test input: fix_diff output: test_file - skill: git-commit-formatter depends_on: [fix_diff, test_file]这种组合方式的好处是每个步骤都可以单独测试和替换。如果某天我觉得generate-fix这个 skill 效果不好换一个就行不影响其他步骤。6.3 什么场景不适合用 skill说了这么多好处也得说说局限。不是所有场景都适合用 skill。探索性任务不适合。比如“帮我看看这个项目有什么可以优化的地方”这种任务没有明确的输入输出很难定义成 skill。这种场景还是直接用对话的方式更灵活。一次性任务不适合。如果某个任务你只会做一次花时间写 skill 定义和验证用例投入产出比不划算。高度依赖人工判断的任务不适合。比如“这段代码的可读性怎么样”这种主观性强的任务skill 很难给出稳定的验证标准。我自己的判断标准是如果一个任务我重复做了三次以上而且每次的流程基本一致那就值得做成 skill。否则就先手动做观察一段时间再说。6.4 后续可以扩展的方向agent-skills这套东西还在快速演进我觉得有几个方向值得关注。一是skill 的自动发现。现在 skill 需要手动定义触发条件未来如果能从用户的实际操作中自动学习触发模式会省很多事。二是跨代理的 skill 复用。现在不同 AI coding agents 的 skill 格式还不统一如果能有标准化的 skill 描述格式同一个 skill 就能在 Claude Code、Cursor 等不同工具间复用。三是skill 的效果度量。现在验证 skill 是否有效主要靠测试用例但测试用例覆盖不了所有情况。如果能有一套更完善的度量体系比如统计 skill 触发后的任务成功率、用户满意度等就能更客观地评估 skill 质量。我个人在实际操作中的体会是agent-skills最大的价值不在于它提供了多少现成的 skill而在于它提供了一套把经验固化成可复用能力的方法论。你用它来管理自己的 AI 编码工作流时间越长积累的 skill 越多效率提升就越明显。但前提是你得愿意花时间把每个 skill 定义清楚、验证到位而不是随便写几行提示词就完事。这件事没有捷径但回报是实打实的。