Agent Skills实战指南：从原理到多平台落地

上个月我在公司内部推Agent编码规范有同事半开玩笑地问我你电脑里装了那么多技能包有几个是自己写的这个问题还真把我问住了。当时我的Claude Code里已经挂了好几个Agent Skills解决了PR描述、测试生成、日志排查这些重复劳动但我确实没认真想过为什么技能机制能把Agent从会聊天变成会干活这件事。后来我把吴恩达那篇关于Agent Skills的教程找出来又翻了不少社区讨论接着在本地项目里把多平台应用这条路完整走了一遍才算是把Agent Skills吃透了。今天就把这一路的理解、实操和踩坑记录整理出来给正在折腾Agent Skills的人一个参考。先交代一下背景Agent Skills是Anthropic在2025年下半年推出的一套Agent能力扩展机制简单说就是把让Agent完成某类任务的方法封装成一个标准化技能包。你既可以把社区现成的技能装进自己的项目也可以自己写技能给团队用还能在同一份技能包在Claude Code、Codex CLI、Cursor等不同Agent平台上流转。文章里出现的npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y就是一条非常典型的技能安装命令后面会专门拆开讲。这篇内容适合三类人一是刚接触Agent、想系统理解Skills机制的二是已经在用Agent写代码、想减少重复劳动的三是打算自己做技能包并发布到社区的。1. 为什么说Agent Skills是Agent落地的关键拼图1.1 从会聊天到会干活差的正是技能层大模型刚火起来的时候大家都追求问什么答什么。但真正把Agent用到生产环境后你会发现模型的能力边界不在理解而在执行。它知道应该怎么写测试但不知道你的项目用Vitest还是Jest它知道应该按规范提PR但不知道你们团队的PR模板长什么样。这时候如果每次都在提示词里手动解释一遍规则既累又容易漏。Agent Skills解决的就是这个问题。它把一条完整的工作流——触发条件、执行步骤、可用脚本、输出规范——打包成一个结构化的技能单元。Agent在运行过程中会读技能的说明文件发现当前任务匹配某个技能时就按技能里的步骤一步步执行。说白了Skills是把专家脑子里的操作手册搬到了Agent的运行环境里。我实际体会最深的一点是技能让Agent的下限变得非常稳定。不装技能的时候让Claude Code写测试脚本它今天用unittest明天用pytest风格完全看心情。装了岗位技能之后它每次都会按照技能里写的测试框架、命名规范、断言风格来写产出的代码像同一个人写的。这对团队协作来说价值极大因为代码审查的成本直接降下来了。1.2 Skills、MCP、Function Calling到底什么关系聊Agent Skills很容易被几个相近的概念绕晕我这里用一张人话版的对照表把它们分清楚。概念本质类比Function Calling模型在对话中决定调用哪个函数并生成参数员工知道打电话这个动作MCP客户端与外部工具之间的标准化通信协议公司统一的电话分机系统Agent Skills一段完整的、可复用的工作流说明和执行脚本新员工入职手册里的客户投诉处理SOP所以它们不是替代关系而是分层关系。Function Calling是模型自身的能力MCP解决的是工具怎么连进来的问题Skill解决的是连进来之后按什么流程干活的问题。实际项目中一个Skill内部完全可以调用MCP服务器提供的工具两者并不冲突。很多人把MCP当成Skills的竞争对手这个理解是错的。MCP服务负责接数据Skills负责定流程配合起来用才是完整方案。1.3 吴恩达的教程为什么值得花时间读吴恩达在这轮AI浪潮里的tutorial一直以把复杂东西讲明白著称Agent Skills的教程出来之后社区里传得很广PDF版本也不难找。他的核心论点我总结成一句话如果我们把Agent比作员工模型是员工的大脑上下文是员工的短期记忆而Skills是员工长期积累的职业技能。教程里最让我受启发的是他对技能应该是原子化的这个观点的强调。也就是说一个Skill最好只解决一个问题而不是把一堆不相干的任务塞进同一个技能包。这个理念直接影响了我后来自己写Skill的取舍能做窄就做窄绝不贪多。我推荐所有想深入Agent开发的人先读一遍这个教程再来看本文后面的实战内容理解起来会顺畅很多。2. Skill包到底长什么样拆开一个技能看看2.1 SKILL.md一份写给Agent看的说明书一个标准的Agent Skill在文件系统里就是一个目录里面最重要的文件叫SKILL.md。这个名字不是随便起的Agent在平台加载技能时会默认寻找这个文件名读取里面的内容来理解技能。一个技能包目录的典型结构大致是这样的my-skill/ ├── SKILL.md ├── scripts/ │ ├── generate_report.py │ └── parse_logs.sh ├── assets/ │ └── templates/ │ └── report_template.md └── requirements.txtSKILL.md是技能的说明书scripts/放实际执行的脚本assets/放模板、样例数据之类的辅助资源requirements.txt标注Python依赖。注意Agent在执行技能时并不是只读SKILL.md需要操作文件时它会在整个技能目录里找脚本所以目录组织是否清晰会直接影响技能执行的成功率。这里有个容易忽略的点技能目录一旦被Agent加载通常会被整体放进Agent可观察的文件范围。也就是说技能包里的资料对Agent来说是可见的它才能在需要时翻开说明书、运行脚本。如果技能包文件特别大加载时间也会变长这个我在后面讲排查时会再提。2.2 Skill如何被Agent识别和触发SKILL.md里除了给人看的功能说明还有一部分是给Agent看的结构化工整信息。以Claude Code的Skills格式为例文件开头通常是这样的--- name: generate-release-notes description: 根据git log和commit信息生成规范的release notes。当用户需要发布版本、生成更新日志或整理提交记录时使用。 --- # Generate Release Notes ## 使用步骤 1. 运行 git log --oneline -20 获取最近提交记录。 2. ... ## 注意 - 只处理当前分支的提交。 - 如果存在 CHANGELOG.md在文件头部追加新内容。对模型来说description是决定什么时候调用这个技能的关键字段。模型不是每句话都去翻技能目录看一遍的它在判断当前对话可能需要某个技能时会优先根据每个技能的description做筛选。所以description写得越具体、越贴近实际场景技能被正确调用的概率就越高。这一点极其重要。很多人在社区反馈技能装了没用排查到最后往往是description写得太泛。比如写用于生成文档模型就不知道什么场景该触发但如果写成当用户要求创建API接口文档、更新接口变更记录或补充测试用例文档时使用模型就能更准确地匹配。2.3 亲手写一个最小可用的Skill理论说再多不如动手写一个。下面是我在本地验证过的一个最小Skill目标是让Agent按固定模板生成每日工作日报。--- name: daily-report description: 根据用户的今日工作记录生成结构化的日报。当用户提到日报工作汇报今日总结等请求时使用。生成结果包含今日完成、明日计划、风险项三部分。 --- # Daily Report ## 输入 - 用户提供的今日工作内容可能是零散列表或一段描述。 ## 执行步骤 1. 提取用户描述中的工作事项归类到今日完成。 2. 如果用户提到计划或后续安排归入明日计划。 3. 如果用户提到阻塞、困难、需要协调的内容归入风险项。 4. 严格按照下面的模板输出不要添加额外内容。 ## 输出模板 markdown ### 今日完成 - ... ### 明日计划 - ... ### 风险项 - ...注意如果用户没有提供足够信息先追问不要自主编造。模板中的分类可以留空但标题必须保留。把上面这段存成目录daily-report/SKILL.md再把目录路径配置到Agent的skills目录或通过技能安装命令加载挂在Claude Code里就能立刻用。这个例子里没有写脚本因为技能不一定必须带脚本纯粹靠提示词就能完成的小任务同样能做成Skill。是否需要脚本取决于任务是不是需要跑命令、处理文件或调用外部API。 ## 3. 安装与复用从一条命令进入技能生态 ### 3.1 全局安装还是项目安装怎么选 技能安装方式主要分两类一是把技能目录放到平台的配置目录下二是用现成的管理工具一条命令拉取。这里不得不提npx skills add这条命令它本质上是一个Node工具封装出来的技能安装器可以从GitHub仓库把技能包直接装进Agent环境。 安装时有一个关键参数要理解-g代表全局安装不带-g则按项目级安装。我的建议是通用型技能比如代码规范检查、日志分析装全局因为每个项目都用得到项目专属技能比如某项目的数据库操作规范、部署流程装项目级避免污染其他项目的上下文。全局技能装多了之后Agent每次加载的说明文件数量变大会导致启动变慢所以我一般控制在10个以内其余都按需安装。 ### 3.2 跑通一条真实的技能安装命令 社区里流传度很高的这条命令可以用来做演示 bash npx skills add sandai-org/vidmuse-skills --agent claude-code -g -y拆开看npx skills add是技能安装工具的入口sandai-org/vidmuse-skills是技能包所在的GitHub仓库标识格式是组织名/仓库名这个仓库实际是一套面向视频生成和多模态创作场景的技能集合--agent claude-code指定安装目标平台是Claude Code-g表示全局安装-y表示跳过交互确认所有提示默认同意。整条命令执行完Claude Code的全局技能目录下就会多出该仓库里定义的技能文件夹。我实际执行这条命令时工具会先解析仓库里的技能结构然后逐个创建目录、下载文件最后提示安装成功。整个过程大概几十秒取决于技能包的大小。如果你装的是不带-g的版本工具会在当前项目下生成一个.claude/skills目录效果是可以看到完整的技能文件方便手动检查内容我建议初学者第一次安装时不要加-g先看清单再决定要不要全局化。3.3 验证技能是否真的被加载了装完技能怎么确认它真的生效我最常用的验证方法有三个。第一个是直接问Agent。在Claude Code里提问你现在可以调用哪些技能它会列出已加载的技能列表包含description。如果刚装的技能出现在列表里说明加载成功。第二个是检查技能目录。全局安装的路径通常是~/.claude/skills/项目级安装路径是.claude/skills/进去看目录结构是否完整。第三个是真实场景测试。这是最有说服力的验证方式直接描述一个技能覆盖的任务观察Agent是否按技能里写的步骤执行。注意这一步不要用含糊的问题比如装了视频生成技能就问帮我把这个项目里的视频素材整理成剪辑脚本而不是问你会视频制作吗。4. 多平台迁移实战同一套技能在不同Agent之间流转4.1 主流Agent平台对Skills的兼容度对比多平台应用是Agent Skills最让我眼前一亮的地方。之前写提示词换一个Agent工具就等于重新写一遍但技能包本身是文件结构理论上可以和平台解耦。我实测了几个主流平台兼容情况如下表所示。平台技能目录约定是否原生支持我的使用评价Claude Code~/.claude/skills/或.claude/skills/是支持最完整文档详细Codex CLI~/.codex/skills/或.codex/skills/支持能读SKILL.md触发稳定Cline自定义技能市场方式半原生需要改目录结构略繁琐Cursor全局规则目录不直接支持建议用规则文件转写丢失部分动态能力OpenCode自定义目录支持社区扩展稳定性一般这里说的支持指的是平台能否原生读取SKILL.md并基于它触发调用。很多工具即使不原生支持也能通过规则引用或提示词加载的方式达到类似效果但体验会有差异。我的经验是如果团队平台统一优先用Claude Code或Codex如果读者想比较各平台就留一套纯SKILL.md的技能不依赖任何平台专属字段。4.2 从Claude Code迁到其他工具时的三处改动实测从Claude Code向Codex CLI迁移同一个技能包时有三处需要特别留意。第一处是目录路径。Claude Code读~/.claude/skills/Codex CLI默认读~/.codex/skills/所以最简单的迁移是复制目录过去或用安装命令重新指定一次--agent参数。实际工作中我用npx skills add重新装一遍比手动复制更省心因为命令会自动处理平台目录差异。第二处是SKILL.md里的元信息格式。Claude Code官方格式在文件头有name和descriptionCodex CLI在很大程度上兼容这个格式但个别版本对YAML front matter的解析要求更严格。迁移后要检查文件开头的---是否被正确解析如果Agent不认技能多半是元信息格式问题。第三处是平台内置工具名不同。你在SKILL.md里写的运行claude --debug到Codex环境里可能对应的是codex exec。为了让技能可迁移最好的做法是在SKILL.md里避免写特定平台的命令而是描述用你当前环境的日志工具把具体命令的选择权交给Agent自己。4.3 同一个Skill包在多平台完成任务的实测我拿自己写的release notes生成技能做了一次跨平台测试。先在Claude Code里触发它正确读取git log按模板生成了版本更新说明然后我把同一个技能目录复制到Codex CLI环境用同样的话术触发Codex也成功调用生成的内容结构一致只是个别措辞有差异。这个结果说明Skills的核心优势就在于一次编写多点复用。但要强调一个前提SKILL.md写得越平台无关迁移越顺畅。凡是你在文档里写死了某个平台专属命令、专属目录、专属配置迁移时就要多花一份力气去改。我现在写新技能的默认标准是脚本尽量用跨平台语言Python或Node路径引用用相对路径命令描述要语义化而不是写死命令字。按这个标准写出来的技能基本可以在不同Agent环境中无缝流转。5. 自己写一个能打的Agent Skill从0到发布5.1 什么样的任务才值得封装成技能写技能之前先做减法。并不是所有任务都适合封装成Agent Skill判断标准我总结成四个字高频、固定。高频指的是这个任务你或你的团队每周都会遇到好几次固定指的是任务的执行流程是明确的、可步骤化的不需要每次进行开放式创意判断。举两个对比鲜明的例子。第一个是生成API接口变更说明这个任务高频、步骤固定、输出模板明确非常适合做技能。第二个是给产品想一个推广文案尽管也高频但每次的输出方向和创意策略差异很大固化流程反而限制发挥不适合做技能。我见过有人把帮我想标题也封装成Skill实际用起来效果很差因为模型在技能约束下反而变得束手束脚。选题对了技能就成功了一半。5.2 SKILL.md的黄金写作组合写作SKILL.md时我的实践组合是四段式头部元信息、使用场景、执行步骤、注意事项与禁用条件。使用场景部分对应description字段要写清楚什么请求下触发、什么请求下不触发执行步骤部分要把流程写到足够细比如先做什么、再做什么、中间需要调用什么脚本都可以列出来注意事项部分越具体越好比如哪些情况必须问用户、哪些信息绝不能编造、输出长度有没有上限。这里分享一个非常实用的技巧在步骤描述里加入如果...就...形式的条件分支。举例如下## 执行步骤 1. 运行日志解析脚本。 2. 如果解析结果为空提示用户检查日志路径不要生成空报告。 3. 如果日志中包含ERROR级别条目按优先级从高到低排列。 4. 输出报告并标注日志的时间范围。加入条件分支之后Agent在面对真实世界的复杂输入时会表现得从容很多。这是我从吴恩达教程里学到的一个重要思想技能文档本质上是在给模型减负你预判的边界越多模型发挥失控的概率就越低。5.3 发布技能自己Host仓库与团队共享技能写好后发布方式取决于使用范围。如果只给自己用把技能目录放进全局目录即可如果要给团队用我推荐两种方式。一种是在GitHub上建一个公开仓库目录名就是技能名仓库根目录放技能内容这样任何同事都可以通过npx skills add 你的组织名/仓库名来安装。另一种是维护一个私有仓库通过npx skills add githttps://github.com/你的组织/私有仓库这样的形式安装适合包含内部规范或敏感模板的技能。命名规范方面仓库名最好是小写字母加连字符比如daily-report、code-review-helper。我见过把技能名取得过于抽象的情况比如叫eagle-eye装完之后根本不知道它干什么。技能名最好直接反映功能description再补充细节。发布之后记得在README里写清技能支持哪些Agent平台方便使用者选择对应的--agent参数。6. 实战中踩过的坑与排查思路6.1 技能装上了但Agent就是不调用怎么查这是社区里反馈最多的一个问题。我的排查链路基本上按照目录有没有放对、元信息能不能被解析、description是否足够具体、当前对话是否触发这个顺序来走。第一步确认SKILL.md真的在平台读取的技能目录下。全局安装常见坑是用户目录选错我把npx skills add输出的安装路径和实际环境变量里的路径对比过一次发现shell配置导致两个路径不一致技能一直没生效。第二步打开调试模式看加载日志。Claude Code可以用claude --debug启动它会打印加载的技能列表。如果列表里没有你的技能说明目录或元信息有问题如果有但现场没触发那就进入第三步。第三步检查description。我建议你把description里写到的场景和你的测试话术对比一下看是否覆盖到。太泛、太窄、用了模型不熟悉的术语都会导致技能不触发。把description改成更贴近真实口语的表述很多时候问题直接解决。6.2 技能脚本输出太长把上下文窗口塞爆技能脚本一旦开始执行它的输出就会进入Agent的上下文。我有一个日志分析技能最初版本会输出完整日志文件内容结果运行不到几轮Agent就开始失忆忘记前面给它的测试要求。排查之后发现是脚本把几千行日志全塞进了对话。修复思路是给脚本增加输出摘要逻辑。脚本不再直接输出原始内容而是输出统计信息和关键异常片段。同时我强制限制了每次技能脚本调用最多输出200行超出的部分写入临时文件Agent需要看时再按行读取。这套改法之后技能在大日志文件场景下明显更稳了。6.3 多个技能之间互相打架的冲突处理技能装的多了之后另一个典型问题是多个技能的description互相重叠。比如我同时装了代码审查助手和Python代码风格检查两个技能让Agent审查一段Python代码时它可能会纠结该调哪个甚至先触发一个再触发另一个结果互相覆盖输出最终效果乱七八糟。我的解决方案有三条第一给每个技能明确划定边界在description里写上当...时不要使用本技能优先考虑XX技能第二统一技能命名风格让Agent看到名字就能知道职责范围第三定期清理很少用到的技能不要舍不得删。技能不是收藏品装而不用只会增加上下文负担还会制造冲突。我现在每个季度会做一次技能清理把近30天没触发的技能先禁用需要时再启用效果很好。另外Skills本质上是知识工程的一部分是需要持续维护的。写一个技能可能只需要半小时但让它在复杂项目里稳定工作需要伴随项目演进不断调整description和执行步骤。我最后的建议是从模仿开始先装上vidmuse-skills这样的现成技能包读一遍SKILL.md理解作者的写作思路然后写一个只服务自己日常工作的最小技能最后再往团队和社区分享。这条路走完你对Agent Skills的理解就基本达到能把控多平台应用的水平了。