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解决的是"工具怎么连进来"的问题，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.txt

SKILL.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工具就等于重新写一遍，但技能包本身是文件结构，理论上可以和平台解耦。我实测了几个主流平台，兼容情况如下表所示。

这里说的"支持"，指的是平台能否原生读取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和description，Codex 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 git+https://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的理解就基本达到能把控多平台应用的水平了。