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 模板吗不完全是。区别在于三个维度维度Prompt 模板Agent Skills加载方式每次全量注入按需动态加载内容结构纯文本结构化定义 资源文件可执行性只能描述可绑定工具、脚本、数据版本管理手动复制独立目录、可分发上下文占用始终占用触发时才占用最关键的是最后一条。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-analysis1.2.0 skills-cli list skills-cli update --all这种方式的坑在于依赖冲突。如果两个 skill 依赖同一个工具的不同版本包管理器可能会报错或者静默覆盖。我的经验是尽量让每个 skill 的依赖最小化能内联的脚本就别做成外部依赖。3.4 安装后的验证别装完就不管了装完 skill 一定要验证。我踩过一次坑装了一个 skillAgent 表面上说已加载实际执行时根本没调用。后来发现是元数据里的触发条件写得太窄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.md4.4 调试为什么我的 skill 不生效调试 skill 是最耗时的环节。我总结了一个排查顺序基本能覆盖 90% 的问题目录结构对不对skill 文件夹是否在正确的 skills 根目录下元数据文件名是否匹配平台要求。元数据格式对不对YAML 缩进、JSON 括号、必填字段是否齐全。格式错误会导致整个 skill 被静默忽略。触发条件是否匹配构造一个明确应该触发的请求看 Agent 日志里有没有加载记录。如果没有放宽 description 或 triggers。指令是否被执行如果加载了但行为不对检查指令正文是否有歧义步骤是否可执行。资源文件路径是否正确指令里引用的资源文件路径是相对路径还是绝对路径平台要求哪种。我遇到最坑的一次是 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/GKE服务化部署团队共享、产品集成高选型建议个人用 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 都有用。