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

最近一段时间，"skills"这个词在技术社区里的出现频率明显高了起来。如果你只是偶尔刷到，可能会以为它说的是"技能"这个泛泛的概念，但实际在开发者圈子里，它已经变成了一个有明确指向的术语——Agent Skills，也就是给 AI 智能体（Agent）挂载的"技能包"。

我最早接触这个概念是在折腾一个自动化工作流的时候。当时的需求很朴素：让一个 AI 助手能按照固定流程帮我处理一批文档，包括读取、分类、提取关键字段、生成摘要。一开始我走的是"大提示词"路线，把所有规则塞进 system prompt 里，结果提示词越写越长，模型开始丢三落四，改一处崩一处。后来有人跟我说，你试试把每个能力拆成独立的 skill，让 Agent 按需调用。这一试，确实打开了新世界。

所以这篇内容我想聊的，不是空泛地解释"什么是技能"，而是把Agent Skills 这套机制从原理到落地讲透：它解决了什么问题、核心结构长什么样、怎么从零写一个能用的 skill、在 Google Cloud 和 GKE 这类环境里怎么部署、以及我在实际开发中踩过的那些坑。不管你是刚听说这个词想入门，还是已经在用 Claude、Codex 这类工具想深入定制，应该都能从里面找到能直接抄作业的部分。

需要先说明一点：Agent Skills 目前并没有一个全球统一的强制标准，不同平台（比如 Anthropic 的 Claude、OpenAI 的 Codex、Google 的 Genkit 生态）在具体实现上有差异，但核心思想是高度一致的——把"能力"从"模型"里解耦出来，做成可插拔、可复用、可版本管理的模块。理解了这层思想，具体 API 怎么变都不慌。

2. Agent Skills 到底解决了什么问题

2.1 大提示词模式的三个死穴

在 skills 出现之前，绝大多数人给 Agent 加能力的方式就是往提示词里堆。我把它叫"大提示词模式"。这个模式在能力少的时候没问题，一旦超过某个临界点，就会暴露三个死穴。

第一个死穴是上下文污染。你给 Agent 加了十个能力，每个能力的规则、示例、边界条件都塞在同一个上下文里。当它处理任务 A 的时候，任务 B 到 J 的规则也在旁边"干扰"它。模型不是数据库，它没法精确地只读取相关部分，于是经常出现"张冠李戴"——用处理图片的规则去处理文本。

第二个死穴是维护成本指数级上升。改一个能力的描述，可能影响其他九个能力的行为。你没法单独测试某个能力，因为所有能力共享同一个提示词。这就导致迭代变得极其痛苦，改一次要全量回归。

第三个死穴是无法复用。你在这个项目里写好的"PDF 解析"能力，想搬到另一个项目，只能复制粘贴那一大段提示词，然后手动删掉不相关的部分。没有版本、没有依赖管理、没有组合机制。

2.2 Skills 的核心思路：能力解耦

Agent Skills 的本质，是把上面这种"一锅炖"改成"分餐制"。每个 skill 是一个独立的单元，包含三样东西：元数据（metadata）、指令（instructions）、以及可选的资源（resources/scripts）。

元数据告诉 Agent "我是谁、我什么时候该被调用"；指令告诉 Agent "调用我之后该怎么做"；资源则是这个 skill 依赖的模板、脚本、参考文档等。Agent 在运行时，先看所有 skill 的元数据，判断当前任务需要哪些 skill，然后只加载被选中 skill 的完整内容。

这个"按需加载"是关键。它直接解决了上下文污染问题——没被选中的 skill，它的详细指令根本不会进入上下文。同时也解决了复用问题——一个 skill 就是一个文件夹，可以打包、可以分享、可以放进版本控制。

我用一个生活化的类比：大提示词模式就像你请了一个管家，然后把家里所有电器的说明书全塞给他，让他自己翻。Skills 模式则是你把说明书分门别类放进抽屉，管家需要开洗衣机的时候，只去拿洗衣机那一本。显然第二种方式更靠谱。

2.3 和传统"函数调用"的区别在哪

有人会问：这不就是 function calling 吗？还真不太一样。

Function calling 解决的是"模型如何调用一个外部函数"的问题，它关注的是输入输出的结构化。而 Agent Skills 解决的是"模型如何获得一套完整的工作方法论"的问题，它关注的是知识和流程的封装。

举个具体例子。你要让 Agent 帮你做代码审查。用 function calling，你会定义一个review_code(file_path)函数，模型调用它，函数返回结果。但"怎么审、审什么、什么算严重问题"这些方法论，还是得写在提示词里。

用 skill 的方式，你会写一个code-reviewskill，里面包含审查清单、常见反模式、严重性分级标准、输出格式模板。Agent 加载这个 skill 后，就"学会"了怎么审代码，而不只是"能调用一个审查函数"。这两者是互补的，不是替代关系。

3. 一个 Skill 的解剖：目录结构与字段含义

3.1 标准目录长什么样

不同平台的 skill 目录结构略有差异，但主流形态高度相似。以最常见的约定为例，一个 skill 通常是一个独立文件夹，核心文件是SKILL.md：

my-skill/ ├── SKILL.md # 必需：元数据 + 指令主体 ├── scripts/ # 可选：可执行脚本 │ └── process.py ├── resources/ # 可选：模板、参考文档 │ └── template.md └── examples/ # 可选：示例输入输出 └── sample.json

SKILL.md是整个 skill 的入口。它由两部分组成：顶部的 YAML frontmatter（元数据），和下面的 Markdown 正文（指令）。

3.2 元数据字段逐个拆解

元数据决定了 Agent 会不会"选中"这个 skill，所以字段设计非常关键。常见的字段有这么几个：

这里我要重点说description。它是整个 skill 里最容易被低估、也最影响效果的字段。Agent 判断"要不要用这个 skill"，主要就是看 description。如果你写"处理文档"，那几乎所有跟文档沾边的任务它都会尝试调用，结果就是误触发。正确的写法是写清楚触发场景 + 能力边界，比如"当用户需要从 PDF 中提取表格数据并转换为 CSV 时使用；不适用于扫描件 OCR"。

3.3 指令主体的写法原则

指令主体就是 Markdown 正文，写的是"加载这个 skill 之后该怎么做"。我的经验是遵循三条原则。

第一，用步骤化而非描述化。不要写"你应该仔细分析代码质量"，而要写"1. 检查是否有未处理的异常；2. 检查是否有硬编码的密钥；3. 检查函数是否超过 50 行"。模型对步骤的遵循度远高于对形容词的理解。

第二，给出正反例。光说"输出要简洁"没用，直接给一个"好的输出"和一个"差的输出"对比，模型立刻就能对齐。

第三，明确边界。写清楚"如果遇到 X 情况，不要自行处理，而是返回提示"。这能大幅减少模型在能力范围外瞎编的情况。

提示：指令主体不要写得太长。我见过有人把整个团队规范几千字塞进一个 skill，结果加载后反而稀释了重点。单个 skill 的指令控制在 500 到 1500 字比较合适，超出的部分拆成多个 skill 或用 resources 引用。

4. 从零写一个能用的 Skill：完整实操

4.1 先想清楚"这个 skill 的触发边界"

动手写之前，先回答一个问题：什么情况下该用这个 skill，什么情况下不该用？这个边界想不清楚，后面全是白费。

我拿一个真实需求举例：我需要一个 skill，把会议记录文本整理成结构化的行动项列表。触发边界是"输入是会议记录/讨论纪要，输出是待办事项"，不适用于"输入是代码、输出是文档"这类任务。

边界定好之后，description就自然出来了：

--- name: meeting-to-actions description: 当输入是会议记录、讨论纪要或对话转录文本，需要提取结构化的行动项（负责人、任务、截止时间）时使用。不适用于代码审查、文档翻译或纯摘要任务。 version: 1.0.0 ---

4.2 指令主体怎么写才不跑偏

接着写正文。我的写法是先给"输入假设"，再给"处理步骤"，最后给"输出格式"。

## 输入假设 输入是一段非结构化的会议记录文本，可能包含多人发言、口语化表达、重复内容。 ## 处理步骤 1. 通读全文，识别所有表示"待办"的语句，关键词包括"需要""负责""跟进""下周前"等。 2. 对每条待办，提取三个字段：负责人（若未明确，填"待定"）、任务描述（动词开头）、截止时间（若未明确，填"未指定"）。 3. 合并语义重复的条目。 4. 按截止时间从近到远排序。 ## 输出格式 以 Markdown 表格输出，列为：负责人 | 任务 | 截止时间。 ## 边界处理 如果全文没有任何待办语句，返回"未识别到行动项"，不要编造。

你看，这样写下来，模型的行为就非常可预测了。它不会自由发挥，因为每一步都有明确指令。

4.3 用脚本处理确定性逻辑

有些逻辑用自然语言描述给模型，既浪费 token 又不稳定。比如日期格式转换、正则匹配、文件读写。这些应该放进scripts/目录，用代码实现。

我的原则是：能用代码确定性完成的，绝不交给模型。模型擅长的是理解、判断、生成，不擅长精确计算和格式转换。把这两类工作分开，整个 skill 的可靠性会提升一个档次。

比如上面那个会议记录 skill，如果截止时间格式五花八门（"下周三""3月5号""月底"），我会写一个normalize_date.py脚本，让模型先调用脚本把日期标准化，再做后续处理。

4.4 本地测试与迭代

写完不是就完事了，必须测试。我的测试方法是准备一组"边界样本"：正常输入、空输入、超长输入、格式混乱输入、包含干扰信息的输入。逐个跑，看输出是否符合预期。

这里有个经验：第一次跑几乎一定会发现 description 写得太宽或太窄。太宽就误触发，太窄就漏触发。根据测试结果反复调整 description，通常要改三到五轮才能稳定。

5. 在 Google Cloud 与 GKE 上部署 Skills 的实践

5.1 为什么要把 skill 放到云端

本地跑 skill 适合开发和调试，但一旦要团队协作或者对外提供服务，就得考虑部署。把 skill 放到 Google Cloud 上，好处有三个：统一版本管理、集中权限控制、按需弹性伸缩。

尤其是当你的 Agent 需要处理大量并发请求时，本地环境根本扛不住。这时候 GKE（Google Kubernetes Engine）就成了一个自然的选择——它能把 skill 的执行环境容器化，按负载自动扩缩容。

5.2 容器化一个 Skill 服务

思路很简单：把 skill 文件夹和一个轻量的 HTTP 服务打包进同一个镜像。服务负责接收请求、加载对应 skill、调用模型、返回结果。

一个最小化的 Dockerfile 大概是这样：

FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY skills/ ./skills/ COPY server.py . EXPOSE 8080 CMD ["python", "server.py"]

server.py里做的事情就是：根据请求里的 skill 名称，读取对应的SKILL.md，拼装成提示词，调用模型 API，返回结果。注意 skill 文件夹要一起打进镜像，这样版本就和镜像绑定了，回滚镜像就等于回滚 skill。

5.3 用 Genkit 编排多 skill 流程

如果你的场景需要多个 skill 协同（比如先解析、再分类、再生成），Google 的 Genkit 框架能帮上忙。它提供了 flow 的概念，可以把多个步骤串起来，每一步可以绑定一个 skill。

我实际用下来的感受是：Genkit 的价值主要在于可观测性。每个 flow 的执行链路、每步的输入输出、耗时、token 消耗都能追踪到。这在调试多 skill 协作时非常有用，否则出了问题你根本不知道是哪一步崩的。

部署到 GKE 时，把 Genkit 服务打成容器，配一个 Deployment 和 Service，再挂一个 HorizontalPodAutoscaler 按 CPU 或请求量扩缩容，基本就能跑起来了。

5.4 部署时容易忽略的三个细节

第一个细节是冷启动。skill 文件如果放在镜像里，容器启动时读取很快；但如果放在外部存储（比如 Cloud Storage）按需拉取，第一次请求会有明显延迟。我的做法是启动时预热，把常用 skill 加载进内存。

第二个细节是密钥管理。模型 API 的密钥绝对不能硬编码在镜像里。用 Secret Manager 或者 GKE 的 Workload Identity，让容器以最小权限访问。

第三个细节是超时设置。Agent 调用模型可能耗时较长，GKE 的负载均衡默认超时时间可能不够。要显式调大 timeout，否则会出现"请求还在处理但连接已被断开"的情况。

6. 那些文档里不会写的踩坑记录

6.1 description 写太泛导致的"技能乱触发"

这是我踩的第一个大坑。早期我写了一个>