1. 从"skills"这个模糊词说起：它到底指什么

第一次看到"skills"这个标题，加上后面跟着的一串热搜词——Google Cloud、Agent Skills、GKE、Genkit、claude agent skills、codex skills、skills开发、skills安装包——我脑子里第一反应是：这词太泛了。泛到如果不做限定，根本没法聊。但把热搜词串起来看，方向其实很清晰：这里的 skills 不是指人类职业技能培训，而是指给 AI Agent 挂载的能力模块，也就是让一个通用大模型或 Agent 框架，通过加载外部定义好的"技能包"，获得特定场景下的专业行为。

说白了，skills 就是 Agent 的"插件系统"或者"技能树"。一个裸的 Agent 什么都能聊，但什么都做不精；给它挂上 skills，它就能在特定任务上表现出接近专家的水准。这个思路在 2024 年下半年到 2025 年集中爆发，Claude 的 Agent Skills、OpenAI 的 Codex skills、Google 的 Genkit 工具链，都在往这个方向走。

我之所以对这个话题有话说，是因为过去大半年我一直在折腾各种 Agent 能力扩展方案，从最早的纯 prompt 工程，到 function calling，再到后来的 MCP、Agent Skills，踩过的坑能写一本书。这篇就围绕 skills 这个核心，把它的本质、安装、开发、选型、避坑，一次性讲透。

提示：本文讨论的 skills 特指 AI Agent 领域的能力扩展模块，不涉及任何其他含义。如果你搜的是别的 skills，可以关掉这篇了。

2. Agent Skills 的本质：它不是 prompt，也不是插件

很多人第一次接触 skills，会把它和 prompt 模板、function calling、MCP 混为一谈。我一开始也这么以为，直到自己动手写了一个才发现，它们解决的是完全不同层次的问题。

2.1 为什么裸 Agent 干不了专业活

先想一个问题：你给一个通用大模型说"帮我做一份财报分析"，它能做吗？能，但做得很浅。它会给你一套通用的分析框架，但不会知道你们公司的科目命名习惯、不会知道行业里哪些指标是关键、不会知道你们内部的分析模板长什么样。

这就是裸 Agent 的根本问题：通用能力很强，领域知识为零。你当然可以在每次对话里把这些背景都塞进 prompt，但那样有三个致命问题：一是 prompt 会变得极长，token 成本飙升；二是每次都要重复描述，效率极低；三是模型在长上下文里容易"忘记"前面的约束。

skills 要解决的就是这个：把领域知识、操作流程、工具调用规范，打包成一个可复用、可版本管理、可按需加载的模块。Agent 需要的时候加载进来，不需要的时候不占上下文。

2.2 skills 和 prompt 模板的分水岭

有人会说，那不就是高级一点的 prompt 模板吗？不完全是。区别在于三个维度：

最关键的是最后一条。skills 的设计哲学是"渐进式披露"——Agent 启动时只知道有哪些 skills 可用（通常只有一行描述），真正需要执行某个任务时，才把完整的 skill 内容加载进上下文。这个设计直接决定了 skills 能规模化，而 prompt 模板不能。

2.3 一个 skill 的最小构成

我拆过好几个不同平台的 skill 包，结构大同小异。一个标准的 skill 通常包含：

• 元数据文件：定义 skill 的名称、描述、触发条件、依赖项。这是 Agent 决定"要不要用这个 skill"的依据。
• 指令正文：告诉 Agent 这个 skill 该怎么用，步骤是什么，注意事项有哪些。
• 资源文件：脚本、模板、参考数据、示例输入输出。这些不一定要全部加载，按需读取。
• 工具绑定：如果 skill 需要调用外部 API 或执行代码，这里定义接口。

拿一个"财报分析 skill"举例，元数据里写"当用户要求分析上市公司财报时使用"，指令正文写分析框架和步骤，资源文件里放行业指标对照表和输出模板，工具绑定里挂一个读取 PDF 的脚本。Agent 收到"分析一下某公司财报"时，匹配到这个 skill，加载进来，按步骤执行。

3. 安装 skills 的几条路：官方市场、手动部署、包管理器

热搜词里有一堆关于安装的："claude 国内安装skills 官方市场"、"skills安装包下载"、"reasonix如何安装新skills"、"skills下载平台有哪些"。看得出来，安装是大家最关心的实操问题。我把目前主流的几种安装方式梳理一下，每种都说说适用场景和坑。

3.1 官方市场安装：最省事但最受限

Claude 和 Codex 都有自己的 skills 市场或官方仓库。安装方式通常是命令行一条指令，或者直接在客户端里点安装。这种方式的好处是省心，版本、依赖、兼容性都帮你处理好了。

但坑也很明显：一是市场里的 skill 数量有限，很多细分场景根本没有；二是审核周期长，你自己写的 skill 想上架得等；三是有些市场对地区有限制，访问不稳定。我实测下来，官方市场适合装那些通用型 skill，比如文档处理、代码审查、数据分析这类。

3.2 手动部署：最灵活但最容易出错

手动部署就是把 skill 包下载下来，放到 Agent 指定的 skills 目录里。不同平台的目录结构不一样，但逻辑相通。以我常用的方式为例：

# 典型的 skills 目录结构 ~/.agent/skills/ ├── financial-analysis/ │ ├── skill.yaml # 元数据 │ ├── instructions.md # 指令正文 │ └── resources/ # 资源文件 │ ├── template.md │ └── metrics.json ├── code-review/ │ └── ...

手动部署最大的坑是目录层级和命名规范。我见过太多人把 skill 文件夹随便一扔，结果 Agent 根本识别不到。通常要求是：skills 根目录下每个子目录就是一个 skill，子目录名就是 skill 标识符，元数据文件名必须严格匹配平台要求（有的叫 skill.yaml，有的叫 manifest.json，有的叫 SKILL.md）。

还有一个隐蔽的坑：权限问题。如果你把 skill 放在系统目录下，Agent 进程可能没有读取权限。我建议统一放在用户目录下，避免权限纠缠。

3.3 包管理器方式：适合开发者和团队

有些平台支持通过包管理器安装 skills，比如 npm、pip 或者自建的 CLI 工具。这种方式适合需要版本锁定、团队协作的场景。你可以把 skills 写进项目的依赖文件，团队成员一键安装，保证大家用的是同一版本。

# 假设某个平台的 CLI 工具 skills-cli install financial-analysis@1.2.0 skills-cli list skills-cli update --all

这种方式的坑在于依赖冲突。如果两个 skill 依赖同一个工具的不同版本，包管理器可能会报错或者静默覆盖。我的经验是，尽量让每个 skill 的依赖最小化，能内联的脚本就别做成外部依赖。

3.4 安装后的验证：别装完就不管了

装完 skill 一定要验证。我踩过一次坑：装了一个 skill，Agent 表面上说"已加载"，实际执行时根本没调用。后来发现是元数据里的触发条件写得太窄，Agent 匹配不上。

验证方法很简单：构造一个明确应该触发该 skill 的请求，看 Agent 的行为有没有变化。如果没变化，先检查元数据，再检查目录结构，最后看日志。大多数平台的 Agent 都有 debug 模式，能看到 skill 加载和匹配的详细过程。

4. 自己写一个 skill：从需求拆解到调试上线

热搜词里"skills开发"、"codex写论文的skills"、"自动挖洞skills"这些，说明很多人已经不满足于用现成的，想自己写。我写过十几个 skill，从最简单的文本处理到复杂的多步骤工作流，总结下来有一套相对固定的流程。

4.1 先想清楚：这个 skill 解决什么重复问题

写 skill 之前先问自己：这个任务我会不会反复做？如果只做一次，直接写 prompt 就行，没必要做成 skill。skill 的价值在于复用。

判断标准有三个：一是任务有固定流程，每次步骤差不多；二是任务需要特定领域知识，通用模型不具备；三是任务需要调用特定工具或数据。三个占两个以上，就值得做成 skill。

我见过有人给每个一次性任务都写 skill，结果 skills 目录里堆了几十个，Agent 匹配时反而混乱。skill 不是越多越好，是越精越好。

4.2 元数据怎么写才能被正确触发

元数据是 skill 的"门面"，Agent 靠它决定要不要加载。写得不好，要么永远不触发，要么乱触发。

关键字段通常包括：

• name：唯一标识，用英文短横线命名，别用中文和空格。
• description：一句话说清楚这个 skill 干什么、什么时候用。这是最重要的字段，Agent 主要靠它匹配。
• triggers：可选的触发关键词或条件。有的平台支持正则，有的只支持关键词列表。
• version：版本号，方便管理和回滚。
• dependencies：依赖的其他 skill 或工具。

description 的写法有讲究。我一开始写"用于分析财务数据"，结果 Agent 在用户问"帮我看看这个表格"时也触发。后来改成"当用户提供上市公司财报文件并要求进行财务比率分析、趋势判断时使用"，触发就准确多了。描述要具体到场景和动作，不要用泛泛的领域词。

4.3 指令正文的结构：步骤、约束、示例

指令正文是 skill 的核心，告诉 Agent 具体怎么做。我的写法是固定三段式：

第一段：目标与输入。明确这个 skill 接收什么输入，输出什么结果。比如"输入是一份 PDF 格式的财报，输出是包含五个维度的分析报告"。

第二段：执行步骤。按顺序列出每一步做什么。步骤要具体到可操作，不要写"分析数据"这种模糊指令，要写"提取利润表中的营业收入、营业成本、净利润三项，计算毛利率和净利率"。

第三段：约束与示例。说明什么不能做，以及给一两个输入输出示例。约束很重要，比如"不要编造数据，如果某项指标缺失，明确标注为缺失"。

# 财报分析 Skill ## 目标 接收 PDF 格式的上市公司财报，输出结构化分析报告。 ## 步骤 1. 读取 PDF，提取利润表、资产负债表、现金流量表 2. 计算核心指标：毛利率、净利率、ROE、资产负债率 3. 与行业均值对比（参考 resources/industry-benchmark.json） 4. 按 resources/report-template.md 格式输出 ## 约束 - 数据缺失时标注"数据缺失"，不得推测 - 所有计算需展示公式 - 输出语言与输入财报语言一致 ## 示例 输入：某公司2024年报.pdf 输出：见 resources/sample-output.md

4.4 调试：为什么我的 skill 不生效

调试 skill 是最耗时的环节。我总结了一个排查顺序，基本能覆盖 90% 的问题：

1. 目录结构对不对：skill 文件夹是否在正确的 skills 根目录下，元数据文件名是否匹配平台要求。
2. 元数据格式对不对：YAML 缩进、JSON 括号、必填字段是否齐全。格式错误会导致整个 skill 被静默忽略。
3. 触发条件是否匹配：构造一个明确应该触发的请求，看 Agent 日志里有没有加载记录。如果没有，放宽 description 或 triggers。
4. 指令是否被执行：如果加载了但行为不对，检查指令正文是否有歧义，步骤是否可执行。
5. 资源文件路径是否正确：指令里引用的资源文件路径是相对路径还是绝对路径，平台要求哪种。

我遇到最坑的一次是 YAML 里用了 Tab 缩进，肉眼看不出来，Agent 直接忽略整个 skill。后来养成习惯，写完元数据先用在线 YAML 校验器过一遍。

5. 不同平台的 skills 生态：Claude、Codex、Genkit 的差异

热搜词里同时出现了 Claude、Codex、Google Cloud、Genkit、GKE，说明大家在不同平台之间横跳。我三个平台都用过，说说各自的 skills 机制差异，帮你选型。

5.1 Claude Agent Skills：最成熟的渐进式加载

Claude 的 Agent Skills 是目前设计最完整的。它的核心机制是"渐进式披露"：Agent 启动时只加载所有 skill 的元数据（名称和描述），当对话内容匹配到某个 skill 时，才加载完整指令，需要资源文件时再单独读取。

这个设计的好处是上下文利用率极高。你可以装几十个 skill，但实际对话中只加载相关的几个，token 消耗可控。缺点是元数据的 description 必须写得非常精准，否则匹配不准。

Claude 的 skill 目录结构比较固定，通常放在~/.claude/skills/下，每个 skill 一个文件夹，核心文件是SKILL.md。安装第三方 skill 就是把这个文件夹复制进去。

5.2 Codex skills：偏向代码和工程场景

Codex 的 skills 更偏向软件开发场景。热搜词里"codex好用的skills"、"codex写论文的skills"能看出来，大家用它做代码生成、论文写作这类任务。

Codex 的 skill 机制和 Claude 类似，但更强调与代码仓库的集成。它的 skill 可以直接绑定仓库里的脚本和配置文件，执行时在仓库环境下运行。这对需要读写文件、跑测试、调 API 的任务很友好。

坑在于：Codex 的 skill 对运行环境有要求，如果你的项目依赖没装好，skill 执行会失败。我建议给每个 Codex skill 配一个环境检查步骤，执行前先确认依赖齐全。

5.3 Genkit 与 GKE：把 skills 部署成服务

Google 的 Genkit 是另一条路线。它不只是本地 Agent 的 skill 加载，而是把 skill 做成可部署的服务，跑在 GKE 上。这意味着你的 skill 可以被多个 Agent、多个用户共享，适合团队或产品级场景。

Genkit 的 skill 定义更接近传统的微服务：有输入输出 schema，有独立的部署单元，有版本管理。学习曲线比前两个陡，但扩展性和可维护性更好。

选型建议：个人用 Claude，开发用 Codex，团队和产品用 Genkit。当然也可以混用，我就同时在用 Claude 和 Codex，各取所长。

6. 那些没人告诉你的坑：skills 使用中的真实教训

这部分是我最想写的。官方文档不会告诉你这些，只有真正踩过才知道。

6.1 skill 冲突：两个 skill 抢同一个任务

当你装了多个 skill，它们的触发条件可能有重叠。比如你装了一个"数据分析 skill"和一个"财报分析 skill"，用户说"分析这份财报"，两个都可能触发。Agent 的处理策略各平台不同，有的选第一个匹配的，有的选描述最匹配的，有的干脆都加载。

结果就是行为不稳定。我的解决办法是：在 description 里明确排除条件。比如财报分析 skill 的 description 写"当用户明确要求分析上市公司财报时使用，不用于一般数据分析"。这样边界就清晰了。

6.2 上下文污染：skill 加载太多导致模型变笨

渐进式加载虽然省 token，但如果你一个对话里触发了太多 skill，上下文里塞满了各种指令，模型反而会混乱。我遇到过一次性加载了五个 skill，结果模型在步骤之间跳来跳去，哪个都没执行完。

经验是：一个对话专注一个任务。如果任务复杂需要多个 skill 协作，考虑把它们合并成一个复合 skill，或者用工作流编排的方式串起来，而不是让模型自己决定加载哪些。

6.3 版本漂移：skill 更新后行为变了

第三方 skill 会更新。你昨天用得好好的，今天作者改了一版，行为可能就变了。更坑的是，有些 skill 更新后和你的 Agent 版本不兼容，直接报错。

我的做法是：生产环境锁定版本。用包管理器安装的，写死版本号；手动部署的，备份一份当前可用的，更新前先测试。别盲目追新。

6.4 安全边界：skill 能执行代码意味着什么

这是最需要警惕的一点。很多 skill 包含可执行脚本，Agent 加载后会运行这些脚本。如果 skill 来源不可信，脚本可能做任何事——读取你的文件、发送网络请求、修改系统配置。

我只从可信来源安装 skill，自己写的 skill 也会审查每一行脚本。对于包含网络请求的 skill，我会先看它请求哪些地址、发送什么数据。skill 的权限应该最小化，能只读就别给写权限，能本地执行就别联网。

注意：安装任何第三方 skill 前，务必检查其包含的脚本和资源文件。不要因为"官方市场"就放松警惕，市场审核不代表零风险。

6.5 跨平台迁移：skill 不是通用的

Claude 的 skill 不能直接拿到 Codex 用，反之亦然。元数据格式、目录结构、触发机制都不一样。我试过把一个 Claude skill 迁移到 Codex，改了元数据格式、调整了资源路径、重写了触发条件，折腾了大半天。

如果你需要跨平台，建议一开始就按"平台无关"的方式组织内容：指令正文用纯 Markdown，资源文件用通用格式，元数据单独维护多份。这样迁移时只需要改元数据。

7. 从 skills 到工作流：当单个 skill 不够用时

用了一段时间 skills 之后，你会发现有些任务单个 skill 搞不定，需要多个 skill 按顺序协作。这就涉及到工作流编排。

7.1 什么时候该把 skill 串起来

判断标准：任务有明确的阶段划分，每个阶段需要不同的专业能力。比如"写一份行业研究报告"这个任务，可以拆成：数据收集 skill → 数据分析 skill → 报告撰写 skill → 格式排版 skill。四个阶段，每个阶段用不同的 skill。

如果硬塞进一个 skill，指令会变得极长，而且难以维护。拆成多个 skill，每个专注一件事，通过工作流串起来，清晰得多。

7.2 编排的两种方式：Agent 自主 vs 显式定义

一种方式是让 Agent 自己决定调用顺序。你只需要把相关 skill 都装上，Agent 根据任务进展自主选择。这种方式灵活，但不可控，容易跑偏。

另一种是显式定义工作流，明确每一步用哪个 skill，上一步的输出作为下一步的输入。这种方式可控，适合流程固定的任务。

我通常混合使用：核心流程显式定义，细节处理让 Agent 自主。比如报告撰写的主流程固定为"收集→分析→撰写→排版"，但每个阶段内部的具体操作让 Agent 根据 skill 指令灵活处理。

7.3 工作流中的状态传递

多个 skill 协作时，状态传递是个问题。上一个 skill 的输出怎么传给下一个？通常有两种方式：一是通过对话上下文传递，Agent 把上一步结果放在上下文里，下一步 skill 读取；二是通过文件传递，上一步写文件，下一步读文件。

上下文传递简单但受 token 限制，适合小数据量。文件传递适合大数据量，但需要管理文件路径和清理。我一般小任务用上下文，大任务用文件，并且在 skill 指令里明确写清楚输入输出的格式和位置。

8. 写在最后：我用了大半年 skills 的真实感受

折腾 skills 这大半年，最大的感受是：它确实改变了我和 AI 协作的方式，但不是银弹。

好的地方很明显：重复性任务效率提升巨大，以前每次都要重新描述的需求，现在一个 skill 搞定；领域知识的沉淀有了载体，团队里一个人的经验可以打包成 skill 给所有人用；Agent 的行为更可控了，不再是每次都给不一样的答案。

但坑也不少：skill 的调试成本比想象中高，一个触发条件可能要改十几遍；跨平台迁移麻烦，生态还没统一；安全边界需要自己把控，不能全指望平台。

如果你刚开始接触 skills，我的建议是：先从官方市场装几个成熟的用起来，感受一下它的工作方式；然后挑一个你反复做的任务，试着写第一个 skill；踩过几次坑之后，再考虑复杂的工作流和团队共享。别一上来就追求大而全，skill 这东西，精比多重要。

热搜词里那些"今天学会了skills，打开新世界"的说法，我理解那种兴奋，但也想泼点冷水：skills 是工具，不是魔法。它能放大你的能力，但前提是你得先有清晰的需求和流程。需求模糊的话，写出来的 skill 也是模糊的，Agent 执行起来照样一团糟。

先把一个 skill 写明白，比装一百个 skill 都有用。