1. 从“agent-skills”说起为什么它值得单独拎出来聊第一次看到agent-skills这个词是在翻 Claude Code 相关生态的时候。当时我的第一反应是这不就是把“提示词工程”换了个马甲吗但真正上手用了一段时间、又自己动手拆过几个 skill 之后我改变了看法。agent-skills本质上是一套给 AI coding agent 用的能力封装规范它把过去散落在各个 prompt 模板、系统指令、项目约定里的“隐性经验”变成了可复用、可版本管理、可被 CLI 直接调用的显式技能包。说得再直白一点以前你让 Claude Code 帮你写测试你得在对话里反复叮嘱“先写测试、再写实现、跑一遍确认失败、再补实现”每次开新会话都得重来一遍。现在你可以把这一整套流程固化成一个 skill命名成test-driven-development之后只要触发对应场景agent 就自动按这套流程走。这就是agent-skills最核心的价值——把重复的、有固定套路的工程动作沉淀成 agent 能直接调用的技能。它解决的问题其实很具体AI coding agent 能力很强但“发挥不稳定”。同一个模型你今天让它写代码它写得很好明天同样的需求它可能就跳过了测试、忽略了边界条件。原因不是模型变笨了而是上下文里缺少稳定的行为约束。agent-skills就是补上这一环的机制。配合skills CLI这类工具你可以安装、列出、更新、卸载技能像管理 npm 包一样管理 agent 的行为模式。这篇文章适合谁看三类人。第一类是把 Claude Code 当日常主力开发工具、想让它更“听话”的人第二类是团队里负责统一 AI 编码规范、希望把团队约定固化下来的人第三类是对 AI coding agent 底层机制好奇、想自己写 skill 的技术人。不管你是刚装完 Claude Code 的新手还是已经用了一阵子但总觉得“差点意思”的老用户下面这些内容应该都能对上你的需求。2. agent-skills 的整体设计与思路拆解2.1 它到底解决了什么痛点要理解agent-skills的设计得先理解 AI coding agent 的一个根本矛盾通用性和确定性之间的拉扯。模型本身是通用的你问它什么它都能答但工程实践要求的是确定性同一个任务每次都应该按同样的标准完成。这个矛盾在真实项目里会以各种形式冒出来。我举个自己踩过的例子。有段时间我用 Claude Code 做一个 Node 项目反复让它“加个接口”。前几次它很规范会先看现有的路由结构、复用已有的中间件、补上参数校验。到第五六次的时候它突然开始自己造一套新的错误处理格式跟项目里原有的完全不一致。我回头翻对话才发现是因为那次会话里我没提“遵循现有约定”而前面的上下文又被压缩掉了。这种问题靠“每次多说一句”是治标不治本的因为你不可能记住所有该叮嘱的点。agent-skills的思路是把这些“该叮嘱的点”从对话里抽出来变成独立的、有明确触发条件的技能单元。每个 skill 本质上是一份结构化的说明文档告诉 agent在什么场景下、应该按什么步骤、遵守什么约束、产出什么结果。它不依赖你每次手动提醒而是由 agent 根据当前任务自动匹配和加载。2.2 为什么是“技能”而不是“提示词”这里有个关键的设计选择值得说清楚。很多人会问我直接写个长 prompt 不就行了为什么要搞成 skill区别在于三个层面。第一是触发机制。普通 prompt 需要你主动粘贴或者放在系统指令里它是“常驻”的会一直占用上下文。而 skill 是“按需加载”的agent 判断当前任务需要某项技能时才把它拉进来用完就释放。这对上下文窗口宝贵的 coding agent 来说非常重要。第二是组织粒度。一个 skill 对应一个明确的能力边界比如“写单元测试”“做代码审查”“处理数据库迁移”。这种粒度让技能可以被组合、被替换、被单独升级。你不可能把一个两万字的巨型 prompt 拆开维护但你可以维护二十个各司其职的 skill。第三是可分发性。skill 是文件可以放进 git 仓库、可以通过 CLI 安装、可以团队共享。prompt 是文本散落在聊天记录、笔记、文档里很难形成工程化的资产管理。skills CLI的存在就是为了解决分发问题让技能像依赖包一样可管理。2.3 和 Claude Code 的关系agent-skills不是 Claude Code 独有的但它在 Claude Code 生态里体现得最明显。Claude Code 作为终端里的 AI coding agent本身就支持通过配置文件、项目约定文件来约束行为。agent-skills是在这个基础上更进一步把行为约束标准化、模块化。实际使用中你会看到 skill 通常以目录形式存在每个目录里有一个描述文件一般是 markdown 或特定格式的配置说明这个技能的元信息、触发条件、执行步骤。Claude Code 在运行时扫描这些技能根据当前任务上下文决定加载哪些。这套机制让“让 agent 按我的方式干活”这件事从玄学变成了可配置的工程问题。提示不要把 skill 理解成“更长的系统提示”。它的核心是条件触发 结构化步骤写 skill 时最重要的不是把话说得多全而是把触发条件和执行边界划清楚。3. 核心细节解析与实操要点3.1 一个 skill 的典型结构长什么样虽然不同实现细节有差异但一个可用的 skill 通常包含几个必备部分。我用一个test-driven-development技能来举例说明因为这是热词里出现频率最高的场景之一也是最容易看出 skill 价值的场景。一个 TDD skill 大致需要包含这些信息技能名称和描述让 agent 知道这是干什么的、触发条件什么情况下该用这个技能比如“用户要求新增功能”或“用户要求修复 bug”、执行步骤先写失败测试、再写最小实现、再重构、再验证、约束条件比如“测试必须先于实现”“每次只处理一个断言”“不允许跳过失败验证”、产出要求测试文件位置、命名规范、覆盖率要求。把这些写清楚之后agent 在遇到“帮我加个功能”这类请求时就会自动套用这套流程而不是直接上来就写实现代码。这就是 skill 相对普通 prompt 的优势——它把“怎么做”固化下来了。3.2 触发条件的设计是成败关键我见过很多人写 skill 失败问题几乎都出在触发条件上。要么写得太宽泛导致 agent 在不该用的时候也加载干扰正常任务要么写得太窄实际根本触发不了。好的触发条件应该描述任务意图而不是具体关键词。比如“当用户要求实现新功能或修改现有行为时”就比“当用户说‘加个功能’时”要好因为后者只能匹配特定措辞。同时要给出排除条件比如“当用户只是询问概念、不涉及代码改动时不触发此技能”。这种正反两面的界定能大幅提升触发准确率。还有一个实操心得触发条件里最好带上优先级或冲突处理。如果两个 skill 的触发条件重叠了怎么办比如“代码审查”和“重构”可能同时匹配一个任务。这时候需要在 skill 里说明优先级或者让 agent 按顺序执行。这个细节很多人会忽略但在技能多了之后会变成大问题。3.3 步骤描述要“可执行”而非“可理解”写 skill 最容易犯的错是用人类读起来很顺、但 agent 执行起来很模糊的语言。比如“确保代码质量”这种话人看了知道大概意思agent 看了不知道具体做什么。好的步骤描述应该是动作 对象 判定标准。对比一下模糊版“写好测试后运行验证。”可执行版“运行测试命令确认新测试失败且失败原因与预期一致若测试直接通过说明测试未覆盖目标行为需重写测试。”后者把“验证”这个动作拆成了可判断的分支agent 执行时不会含糊。这个原则贯穿整个 skill 编写过程——凡是需要 agent 做判断的地方都要给出明确的判定依据。3.4 用 skills CLI 管理技能包skills CLI是配套的工具用来安装、查看、更新技能。它的使用逻辑跟包管理器很像。常见操作包括列出当前可用的技能、安装某个技能到项目或全局、查看某个技能的详情、更新到最新版本、卸载不再需要的技能。实操中我建议项目级技能和全局技能分开管理。项目级技能放在项目目录下跟着代码走团队成员拉下来就有一致的 agent 行为全局技能放在用户目录下是你个人的通用习惯比如“我总是希望代码注释用中文”。这样区分之后换项目时不会把上个项目的特殊约定带过去团队协作时也不会因为个人偏好污染项目规范。注意安装第三方 skill 之前一定要读一遍它的内容。skill 会直接影响 agent 的行为一个写得不好的 skill 可能让 agent 做出你不期望的操作。把它当成要引入项目的依赖来对待该审的审该锁版本的锁版本。4. 实操过程与核心环节实现4.1 环境准备先把 Claude Code 跑起来要玩agent-skills前提是有一个能用的 AI coding agent 环境。以 Claude Code 为例安装方式根据系统不同有差异。macOS 和 Ubuntu 上的安装流程大同小异核心是确保运行环境里有合适的 Node 版本然后通过官方提供的安装方式把 CLI 装好。装完之后用claude命令启动首次使用需要完成账号相关的初始化流程。这里有个常见疑问不注册账号能不能用其他模型实际操作中Claude Code 支持通过配置接入第三方模型服务包括一些国内可访问的模型。配置方式通常是在设置文件里指定 API 端点和密钥。这个环节的细节建议直接参考官方文档因为接口格式和配置项会随版本变化。我自己的经验是先把默认配置跑通再折腾第三方接入否则出问题时很难判断是环境问题还是配置问题。VS Code 用户还可以装对应的插件在编辑器里直接调用。插件配置的核心是让编辑器知道 CLI 的路径和启动参数。Ubuntu 环境下如果遇到权限或路径问题检查一下 shell 的 PATH 配置通常能解决。4.2 写第一个 skill从 TDD 开始环境就绪后我们来实际写一个 skill。选 TDD 作为第一个是因为它的流程足够清晰容易验证效果。第一步确定 skill 的存放位置。项目级的话在项目根目录下建一个约定的技能目录。第二步创建技能描述文件按前面说的结构填入名称、描述、触发条件、步骤、约束。第三步写完后在 Claude Code 里触发一次观察它是否按预期加载并执行。我实际写的时候TDD skill 的步骤是这么组织的接收功能需求后先不写实现代码而是分析需求涉及的输入、输出、边界情况。为每个边界情况写一个测试用例测试文件放在项目约定的测试目录下。运行测试确认所有新测试都失败且失败原因是“功能未实现”而非“测试本身有语法错误”。编写能通过测试的最小实现不追求优雅只追求通过。再次运行测试确认全部通过。在测试保护下重构实现代码每次重构后重跑测试。输出变更摘要包括新增测试数、实现文件、覆盖率变化。这套步骤写进 skill 之后我特意测试了几次。第一次让它“加一个邮箱格式校验函数”它确实先写了测试跑出失败再写实现。第二次我故意说“快点直接写实现”它仍然坚持先写测试因为 skill 里的约束明确写了“测试必须先于实现”。这就是 skill 的价值——它让 agent 在你想偷懒的时候替你守住纪律。4.3 参数与判定标准的量化写 skill 时凡是能量化的地方尽量量化。比如“测试覆盖率”这种要求如果只写“保持较高覆盖率”agent 没法判断。写成“新增代码行覆盖率不低于 80%分支覆盖率不低于 70%”就可执行了。再比如“代码审查”技能里“检查函数长度”可以量化为“单个函数不超过 50 行超过则建议拆分”。量化的好处是让 agent 的产出有明确的验收标准也方便你在 skill 迭代时判断效果。我一般会在 skill 里放一个简单的检查清单agent 执行完主要步骤后逐项自检。这个自检环节能显著减少“看起来做了但没做到位”的情况。4.4 技能的组合与编排单个 skill 用顺了之后自然会想组合。比如一个完整的“新增 API 接口”任务可能涉及“TDD 写测试”“数据库迁移”“接口文档更新”三个技能。这时候有两种编排方式一种是让 agent 根据任务自动匹配多个技能并按依赖顺序执行另一种是写一个上层 skill显式调用下层技能。我倾向于后者因为显式编排更可控。上层 skill 里写清楚“先执行数据库迁移技能再执行 TDD 技能最后执行文档技能”agent 就按这个顺序走。自动匹配虽然省事但技能多了之后容易出现顺序错乱或遗漏。可控性优先于自动化这是我踩过几次坑之后的结论。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。技能写好了但 agent 该用的时候没用。排查思路按顺序来先确认技能文件放在 agent 会扫描的目录下路径错了后面都白搭再检查触发条件的描述是否过于具体导致实际任务匹配不上然后看是不是有另一个技能的触发条件更宽泛把任务“抢”走了。我遇到过一次TDD 技能死活不触发最后发现是另一个“快速实现”技能的条件写成了“任何涉及代码修改的任务”优先级还更高。把那个技能的条件收窄之后TDD 就正常了。所以技能之间的触发条件要互相避让这是设计时就要考虑的事。5.2 技能触发了但执行走样有时候技能加载了但 agent 执行到一半就偏离了。常见原因是步骤描述里有歧义或者约束条件不够硬。比如“尽量先写测试”里的“尽量”就是软约束agent 可能理解为“可以不做”。改成“必须先写测试未写测试前不得修改实现文件”就硬多了。另一个原因是上下文太长skill 的内容被挤到了后面agent 注意力下降。这时候可以考虑把 skill 拆小或者把最关键的约束放在 skill 描述的开头。重要的约束前置这是个很实用的技巧。5.3 多个技能冲突技能冲突的表现是 agent 行为前后矛盾或者反复横跳。根源通常是两个技能的约束互相打架。比如一个技能要求“所有函数必须有注释”另一个要求“代码保持简洁避免冗余注释”。这种冲突需要在设计层面解决要么合并技能要么明确优先级。我的做法是维护一个技能清单定期检查触发条件和约束是否有重叠。技能数量控制在十个以内比较好维护超过之后冲突概率明显上升。5.4 常见问题速查表问题现象可能原因排查方向技能完全不触发路径错误或触发条件过窄检查存放目录放宽触发描述技能被其他技能抢占触发条件重叠且优先级不明收窄宽泛技能的条件明确优先级执行中途偏离步骤有歧义或约束太软把软约束改成硬约束关键约束前置行为前后矛盾多技能约束冲突合并或拆分技能明确执行顺序技能更新后失效版本不兼容或格式变化回滚版本对照最新格式检查5.5 几个独家避坑技巧第一新写的 skill 先在沙盒项目里试别直接上生产项目。skill 的行为影响面比你想的大一个措辞不当可能让 agent 在关键任务上做出奇怪操作。第二给 skill 写版本号和变更记录。技能是会迭代的没有版本管理的话某天发现行为变了都不知道是哪次改动导致的。第三定期清理不再用的 skill。技能堆积不仅增加冲突概率还会拖慢 agent 的匹配过程。我一般每个月过一遍把三个月没用过的删掉或归档。第四团队共享的 skill 要配文档。光有 skill 文件不够得说明它解决什么问题、什么时候该用、有什么已知限制。不然新人看到一堆技能目录会懵。6. 技能生态的延展与个人实践体会agent-skills这套机制真正有意思的地方在于它把“怎么和 AI 协作”这件事从个人经验变成了可积累的资产。以前你用 AI 写代码用得好不好全看个人会不会提问现在你可以把好的协作方式固化成技能让它稳定复现还能分享给别人。我自己的技能库现在有十几个覆盖测试、审查、重构、文档、迁移这些高频场景。最明显的变化是我不再需要每次开新会话都重新“调教”agent它一上来就按我习惯的方式干活。这种一致性带来的效率提升比单纯追求模型能力提升要实在得多。往后看技能生态大概率会往两个方向走一是标准化出现通用的技能格式和分发渠道让技能能跨不同的 agent 平台使用二是组合化单个技能解决单点问题多个技能编排解决复杂工作流。现在已经有这个苗头了skills CLI这类工具就是在往标准化方向走。如果你还没开始写自己的 skill我的建议是从一个你每天都要重复叮嘱 agent 的动作开始。把它写下来跑通再迭代。不用追求一次写完美技能这东西是越用越顺的。我第一个 TDD 技能改了七八版才稳定但改的过程本身就是对“我到底希望 AI 怎么帮我干活”的一次梳理这个收获比技能本身还值。