1. 从agent-skills说起一个被低估的工程化命题第一次看到agent-skills这个词很多人会下意识地把它理解成给 AI 智能体写提示词。这个理解不算错但太浅了。真正在一线用 AI coding agents 干活的人会告诉你提示词只是冰山露出水面的那一角水面之下是一整套可复用、可测试、可版本管理的技能工程体系。agent-skills要解决的恰恰是如何把一次性的对话经验沉淀成团队里每个人都能调用的标准能力这个问题。我接触这套东西的起点很朴素团队里几个人都在用 Claude Code 写代码每个人都在自己的会话里反复调教同一类任务——写单元测试、重构函数、生成迁移脚本、审查 PR。调教的过程很爽但结果留不下来。换个人、换个项目、换台机器一切归零。agent-skills加上配套的 skills CLI本质上就是给这种调教成果找一个正式的存放位置和调用入口让它从个人手感变成工程资产。这篇文章适合三类人看。第一类是已经在用 Claude Code、但还停留在聊天式写代码阶段的开发者你会看到怎么把零散经验结构化。第二类是想给团队搭建 AI 编码规范的 Tech Lead你会看到目录结构、测试驱动、版本管理这些落地细节。第三类是刚听说 AI coding agents、还在纠结要不要上手的新手前半部分会帮你建立正确的认知框架不至于一上来就被各种概念绕晕。全文围绕agent-skills这个核心把设计思路、目录结构、skills CLI 用法、test-driven-development 的落地方式、以及一堆踩坑经验讲透。2. agent-skills 到底是什么概念拆解与设计动机2.1 从提示词到技能的认知升级先把概念掰开。在 AI coding agents 的语境里一个技能skill不是一句提示词而是一个自包含的能力单元通常包含三部分一段描述这个技能做什么、什么时候该用的元信息一段指导 agent 如何执行的操作说明以及可选的辅助资源比如脚本、模板、参考文档。你可以把它类比成给新员工写的 SOP 手册——不是告诉他你要努力而是告诉他遇到 X 情况按 1、2、3 步做注意别踩 Y 这个坑。为什么需要这种结构化因为裸提示词有三个致命问题。第一是不可复用你在这个会话里调好的提示词下个会话就找不到了。第二是不可测试你没法验证这个提示词是不是真的比那个好全靠感觉。第三是不可协作团队里十个人有十套写法质量参差不齐。agent-skills的设计动机就是把这三点逐个击破用文件系统解决复用用 test-driven-development 解决验证用统一的目录约定解决协作。这里有个关键判断技能不是越通用越好。我见过有人试图写一个万能编程技能结果它什么都能干一点什么都干不精。真正好用的技能往往是窄而深的比如给 Python 函数补 pytest 测试、把回调风格的 JS 重构成 async/await、根据 schema 生成数据库迁移文件。窄意味着触发条件清晰agent 知道什么时候该调用它深意味着里面有真正的领域知识不是泛泛而谈。2.2 为什么是 Claude Code 这类 agent 先跑通了这个模式agent-skills这套模式能在 Claude Code 上先跑通不是偶然。Claude Code 这类工具的核心特征是它能直接读写文件系统、执行终端命令、并且有一个相对稳定的技能发现机制——它会去特定目录扫描可用的技能定义。这意味着技能可以像代码一样被 git 管理、被 CI 校验、被 code review。对比一下纯聊天式的 AI 工具你在网页对话框里让模型写测试它写完就完了你复制粘贴走人下次还得重新描述需求。而 Claude Code 里你把写测试这件事写成一个 skill 文件放进项目之后任何人在这个项目里说给这个模块补测试agent 就会自动加载这个技能按你定义的标准来。这个差别是数量级的——前者是消费后者是投资。提示不要把 agent-skills 理解成某个特定产品的专属功能。它是一种工程范式核心思想是把 agent 的能力定义外置成可管理的文件。理解了这一点你换任何支持类似机制的 agent 工具迁移成本都很低。2.3 技能、命令、子代理别把三个概念搞混新手最容易混淆的是 skill、command、subagent 这三个东西。我用一个类比说清楚skill 像是菜谱描述怎么做一道菜command 像是点菜按钮你按一下就触发某个流程subagent 像是专门负责某道菜的厨师它有独立的上下文专门处理某类任务。在实际项目里这三者经常配合使用。比如你有一个代码审查的 skill定义审查的标准和输出格式然后有一个/review的 command一键触发审查流程审查过程中如果发现需要深入分析某个复杂模块可以派一个 subagent 去专门读那部分代码避免污染主会话的上下文。理解这个分工你在设计自己的 agent-skills 体系时就不会把所有东西塞进一个文件里。3. 目录结构与技能组织让技能像代码一样可管理3.1 标准目录布局与命名约定一套能长期维护的 agent-skills 体系目录结构必须清晰。我实测下来比较稳的布局是这样的project-root/ ├── .agent/ │ ├── skills/ │ │ ├── write-pytest-tests/ │ │ │ ├── SKILL.md │ │ │ ├── templates/ │ │ │ └── scripts/ │ │ ├── refactor-to-async/ │ │ │ └── SKILL.md │ │ └── generate-migration/ │ │ ├── SKILL.md │ │ └── reference/ │ ├── commands/ │ │ └── review.md │ └── config.json └── src/每个技能一个独立目录目录名用动词开头的 kebab-case比如write-pytest-tests而不是pytest或tests-helper。为什么强调动词开头因为技能的本质是做一件事动词开头能让 agent 在扫描技能列表时更快匹配到用户意图。SKILL.md是技能的主文件里面包含元信息头通常用 YAML frontmatter和正文说明。辅助资源放在同目录的子文件夹里保持自包含。命名上还有个细节避免用过于宽泛的词。我见过有人把技能命名成coding、helper、utils这种名字对 agent 来说毫无信息量触发准确率极低。好的命名应该让人一眼看出这个技能在什么场景下用比如fix-flaky-test、add-type-hints、split-large-component。3.2 SKILL.md 的元信息设计触发条件是灵魂SKILL.md里最重要的不是正文而是元信息头。因为 agent 决定要不要用这个技能靠的就是元信息里的描述。一个典型的元信息头长这样--- name: write-pytest-tests description: 为 Python 函数或类生成 pytest 单元测试覆盖正常路径、边界条件和异常分支。当用户要求补测试写单测提高覆盖率时使用。 version: 1.2.0 tags: [python, testing, pytest] ---这里description是灵魂。它要同时回答两个问题这个技能做什么以及什么时候该触发。我踩过的坑是早期只写了生成 pytest 测试结果 agent 在用户说这个函数好像有问题时也会误触发。后来加上触发场景描述当用户要求补测试、写单测时使用误触发率明显下降。version字段别省。技能是会迭代的没有版本号你根本不知道线上跑的是哪一版。tags用于分类检索当技能多到几十个时标签能帮你快速定位。这些字段看起来是小事但技能库一旦上规模没有它们就是灾难。3.3 正文写法给 agent 看的说明书不是给人看的文档SKILL.md的正文和普通技术文档写法完全不同。普通文档是写给人看的可以省略显而易见的步骤技能正文是写给 agent 看的必须把每一步都显式化因为 agent 不会脑补你的隐含意图。我的经验是正文按这个结构组织先写适用场景和不适用场景划清边界再写执行步骤用有序列表每步都是可执行的动作然后写输出格式明确告诉 agent 结果应该长什么样最后写注意事项把容易出错的地方点出来。举个写测试技能的例子执行步骤会写成1. 读取目标函数签名和 docstring2. 识别所有分支和异常抛出点3. 为每个分支生成一个测试函数4. 使用 pytest.mark.parametrize 处理多组输入5. 运行测试确认全部通过。每一步都是 agent 能直接执行的动作不含糊。注意正文里绝对不要写根据情况灵活处理这种话。agent 对模糊指令的处理方式是不可预测的你以为的灵活在它那里可能是随机。要么给明确规则要么给判断标准别给模糊空间。4. skills CLI把技能管理变成命令行操作4.1 安装与初始化从零搭起技能库skills CLI 是管理这套技能体系的命令行入口。它的价值在于把创建技能、校验技能、列出技能、同步技能这些操作标准化避免手动建目录、手写元信息时出错。安装方式通常是通过包管理器具体命令随工具版本变化但初始化流程大同小异。初始化一个技能库核心动作是init。它会在项目根目录创建.agent/骨架包括skills/、commands/和一份默认配置。我建议初始化后第一件事是改配置里的技能扫描路径如果你的项目有 monorepo 结构可能需要配置多个扫描根目录否则子包里的技能不会被发现。初始化完成后用list命令确认当前技能列表。空库是正常的接下来就是往里加技能。这里有个实操心得不要一上来就写十个技能。先写一个你每天都在重复的任务把它跑通、跑顺再考虑第二个。技能库的质量远比数量重要十个半成品技能不如一个打磨到位的。4.2 创建与校验new 和 validate 的配合new命令用于创建一个新技能骨架它会生成目录和一份带占位符的SKILL.md。我通常的流程是new生成骨架然后手动填充元信息和正文最后用validate校验。validate这个命令值得单独说。它会检查元信息字段是否完整、description 是否足够具体、正文结构是否符合约定、引用的辅助文件是否存在。早期我觉得这步多余直到有一次技能里的脚本路径写错了agent 调用时静默失败排查了半天才发现是路径问题。从那以后我养成了习惯每次改完技能必跑validate把它加进 pre-commit hook 里。校验能抓的问题类型大致有这么几类我整理成表格方便对照问题类型典型表现validate 是否捕获元信息缺失没有 description 或 version是description 过泛只写处理代码部分会警告辅助文件路径错误引用了不存在的脚本是正文结构混乱缺少执行步骤部分会警告命名不规范用下划线或大写是4.3 同步与分发让团队用上同一套技能技能写好了怎么让团队里每个人都用上这就是sync或类似命令的用武之地。它的逻辑通常是把技能库同步到 agent 的全局配置目录或者从远程仓库拉取最新版本。我的做法是把技能库作为项目仓库的一部分跟着代码一起提交。这样有个好处技能和代码版本绑定某个技能是针对这个项目特定架构写的跟着项目走最合理。对于跨项目通用的技能我会单独维护一个技能仓库通过 CLI 的远程同步功能分发。两种方式结合既保证了项目特定技能的一致性又避免了通用技能在每个项目里重复维护。提示技能同步后agent 不一定立即感知到变化。有些工具需要重启会话或执行一次刷新命令。如果你改了技能但 agent 行为没变先检查是不是没刷新别急着怀疑技能写错了。5. test-driven-development让技能质量可验证5.1 为什么技能也需要测试这是agent-skills体系里最容易被忽视、也最能拉开差距的一环。大多数人写完技能手动试一次觉得能用就完事了。但技能和代码一样会腐化底层模型升级了、项目结构变了、依赖库换版本了昨天好用的技能今天可能就失灵。没有测试你只能等它在实际使用中出问题才发现。test-driven-development 的思路套用到技能上就是先定义这个技能在什么输入下应该产出什么输出然后构造测试用例去验证。技能的测试和普通代码测试有个关键区别技能的输出是自然语言或代码片段不是确定性的返回值所以断言方式要调整。我们通常不比对完整输出而是检查关键特征——比如生成的测试文件是否包含特定数量的测试函数、是否覆盖了指定的边界条件、是否用了项目约定的 fixture 命名。5.2 技能测试的三种粒度我把技能测试分成三种粒度从轻到重依次是结构测试、行为测试、端到端测试。结构测试最轻只检查技能文件本身是否合规——元信息完整、正文有执行步骤、引用的文件存在。这类测试跑得飞快适合放进 pre-commit。行为测试中等构造一个典型输入让 agent 加载技能执行检查输出是否满足预设特征。这类测试需要真实调用 agent有成本通常放在 CI 里按需触发。端到端测试最重在真实项目场景里跑完整流程验证技能和项目其他部分的配合。这类测试我一般只在技能大版本更新时跑日常不跑因为太慢。三种粒度的取舍本质是测试成本和信心之间的平衡。我的经验是结构测试必做行为测试覆盖核心技能端到端测试只覆盖最关键的几个。5.3 一个可复现的技能测试流程具体怎么落地我拿写 pytest 测试这个技能举例。首先准备一个 fixtures 目录里面放几个待测的 Python 文件每个文件代表一种典型场景有分支的函数、会抛异常的函数、有边界条件的函数。然后写一个测试脚本对每个 fixture 调用技能检查输出。检查点我通常设这几个生成的测试文件能否被 pytest 成功收集语法正确测试函数数量是否覆盖了所有分支覆盖率是否包含至少一个异常路径测试命名是否符合项目约定。这四个检查点跑通基本能保证技能在真实场景里不会太离谱。跑测试的时机也有讲究。我把它挂在两个地方一是技能文件变更时自动触发防止改坏二是底层 agent 版本升级后手动跑一次因为模型行为变化可能导致技能失效。第二点特别重要我遇到过模型升级后技能输出格式变了的情况幸好有测试兜底不然要等用户反馈才发现。6. 实操全流程从零搭一个可用的技能库6.1 环境准备与前置检查动手之前先把环境理清楚。你需要一个能跑 Claude Code 的环境无论是 VS Code 插件还是终端版本都行。安装方式各平台不同Mac、Ubuntu、Windows 各有各的步骤核心是确保 agent 能正常启动并读写项目文件。装完之后用一个简单任务验证一下比如让它读一个文件并总结确认基础能力正常。然后是 skills CLI 的准备。确认 CLI 能正常执行--version能访问到项目目录。如果你的项目在远程开发环境里注意 CLI 的工作目录要和 agent 的工作目录一致否则技能扫描路径会对不上。这一步看着简单但我见过不少人卡在这里agent 找不到技能排查半天发现是 CLI 在另一个目录跑的。注意环境准备阶段不要急着写技能。先用 agent 裸跑几个任务感受一下它的行为模式知道它在没有技能时是怎么处理这类任务的。有了这个基线你才能判断技能到底带来了多少提升。6.2 第一个技能从最痛的点切入选第一个技能的原则是高频且标准化。高频保证你很快能验证效果标准化保证技能容易写清楚。我建议从生成单元测试或代码格式化重构这类任务入手因为它们输入输出明确判断标准清晰。以生成单元测试为例创建技能目录写SKILL.md。元信息里 description 要写清楚触发场景。正文里把执行步骤拆细读目标文件、识别函数、分析分支、生成测试、运行验证。辅助资源里可以放一个测试模板文件让 agent 生成时参考项目已有的测试风格。写完先别急着用跑一遍validate再手动触发一次看输出是否符合预期。第一次大概率不完美可能是测试命名不对可能是漏了某个分支。根据实际输出调整正文里的步骤描述把识别所有分支改成更具体的识别 if/elif/else、try/except、循环边界三类分支。技能就是在这样一轮轮微调中变好的。6.3 技能迭代与版本管理技能上线不是终点。我维护技能库的经验是每个技能都要有明确的 owner 和变更记录。SKILL.md里的 version 字段每次改动都要递增配合 git 的 commit message 记录改了什么、为什么改。迭代的驱动力通常来自两个方向一是使用中发现的失败案例agent 在某类输入下表现不好需要补充规则二是底层能力变化模型升级后某些原本需要显式说明的步骤可以简化了。前者是修补后者是优化两种都要做但优先级不同——先保证不坏再追求更好。版本管理还有个实际问题技能更新后正在进行的会话可能还在用旧版本。我的处理方式是重大更新时通知团队重启会话小更新则等下个自然会话周期。这个策略不完美但比强制所有人立刻重启要现实。7. 常见问题与排查技巧实录7.1 技能不触发或误触发这是最高频的问题。技能不触发先检查三件事技能目录是否在扫描路径内、元信息 description 是否包含用户可能说的关键词、agent 是否需要刷新才能感知新技能。我遇到过的案例里八成是 description 写得太抽象用户说帮我写个测试技能描述里只有生成单元测试代码关键词对不上。误触发则相反通常是 description 太宽泛。解决办法是在 description 里加不适用场景比如当用户只是询问测试概念、不需要生成代码时不要使用本技能。给 agent 划清边界比让它自己判断要可靠得多。7.2 技能执行结果不稳定同一个技能两次执行结果差异很大这通常不是技能的问题而是任务本身有歧义。agent 对模糊输入的处理是概率性的你给它的输入越模糊输出越飘。解决办法是在技能正文里增加输入澄清步骤如果用户请求缺少关键信息比如没说测试框架、没说覆盖范围先追问再执行。另一个原因是技能依赖的外部资源不稳定比如引用的脚本在不同环境下行为不同。这类问题要靠测试兜底把环境差异显式化。7.3 技能库膨胀后的管理难题技能写到二三十个之后管理成本会陡增。这时候需要做两件事一是定期清理把长期不用、效果不佳的技能归档或删除二是建立分类索引用 tags 把技能分组方便检索。我还会定期跑一次全量技能的行为测试把失败的技能挑出来修复或下线。下面这张表是我整理的常见问题速查遇到问题先对照排查现象可能原因排查动作技能完全不触发路径不对/未刷新/描述不匹配检查扫描路径重启会话核对关键词技能误触发描述过泛补充不适用场景输出格式不对正文缺输出格式说明在正文加明确的输出模板执行中途失败辅助文件缺失或路径错跑 validate检查引用结果时好时坏输入歧义或环境差异增加澄清步骤固定环境7.4 团队协作中的技能冲突多人维护技能库时冲突不可避免。两个技能可能触发条件重叠导致 agent 不知道该用哪个。解决办法是建立技能命名和描述的评审机制新技能上线前检查是否和现有技能冲突。我还会在技能正文里写明本技能与 X 技能的区别帮助 agent 做选择。提示技能冲突的根源往往是职责划分不清。与其在技能层面打补丁不如回到源头重新想清楚每个技能到底负责什么。一个技能只干一件事冲突自然就少了。8. 我踩过的坑和几条实在建议聊了这么多最后分享几条从实际项目里摔出来的经验。第一条别追求技能数量。我早期一口气写了十几个技能结果维护不过来一半都处于半失修状态。后来砍到五个核心技能每个都打磨到位实际使用效果反而更好。技能库的价值在于可靠不在于多。第二条description 值得反复打磨。我现在的习惯是一个新技能的 description 至少改三遍第一遍写功能第二遍加触发场景第三遍加排除条件。这三遍下来触发准确率能提升一大截。很多人在这上面偷懒结果技能写得不差就是用不起来。第三条测试不是负担是保险。技能测试看起来增加了工作量但它省下的是技能悄悄失效却没人发现的隐性成本。我现在的技能库结构测试全量跑行为测试覆盖核心这套组合让我在模型升级时心里有底。第四条技能要跟着项目走。项目架构变了技能也得跟着改。我见过有人把技能写死成针对某个旧目录结构的项目重构后技能全废。技能正文里尽量用相对路径和抽象描述把具体路径放到配置里这样项目结构变化时改动最小。这套agent-skills的玩法说到底就是把个人调教 AI 的手感变成团队可复用的工程资产。过程有点繁琐但一旦跑通你会发现团队里每个人用 AI 写代码的质量都上了一个台阶而且这个台阶是稳定的、可传承的。后续我打算把技能库和 CI 更深度地结合让技能质量成为代码质量的一部分这条路还长但方向是清楚的。