1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个招聘网站上的技能标签或者是一份简历里的能力清单。但结合热搜词里反复出现的 Agent Skills、Google Cloud、GKE、Genkit、codex skills、claude agent skills 这些词基本可以判断这里说的 skills 不是人类职场技能而是给 AI Agent 使用的可复用能力模块。简单说一个 Agent 本身只是一个会调用大模型的程序它能聊天、能推理但它不知道怎么查数据库、怎么调接口、怎么按公司规范写周报。skills 就是把这些“具体怎么做”封装成一个个独立的小包Agent 需要的时候加载进来就能从“只会说”变成“能动手”。这有点像给一个刚入职的聪明新人发了一本岗位操作手册手册里每一页就是一个 skill。这个项目适合谁看如果你正在用 Claude、Codex 这类工具做自动化或者你在 Google Cloud 上跑 GKE 集群、用 Genkit 编排 AI 工作流又或者你只是好奇“为什么别人家的 Agent 能自动挖洞、自动写论文、自动做分镜”那这篇内容就是写给你的。我会从设计思路、核心细节、实操过程到踩坑排查完整拆一遍 skills 这套东西到底怎么玩。2. 整体设计思路为什么要把能力拆成 skills2.1 从“一个大提示词”到“一堆小能力包”的转变早期做 Agent最常见的做法是写一个巨长的系统提示词把能想到的规则、示例、工具说明全塞进去。我试过那种方式提示词写到八千字模型开始丢三落四改一个功能要动全身调试起来像在拆炸弹。skills 的思路完全相反把能力按职责切分每个 skill 只干一件事用的时候按需加载。这个转变背后的逻辑很实在。大模型的上下文窗口是有限资源你塞进去的无关内容越多它真正需要关注的指令就越容易被稀释。把能力拆成 skills 之后Agent 在规划阶段只需要知道“我有哪些 skill 可用”真正执行某个任务时才把对应 skill 的详细说明读进来。这就像你不需要背下整本菜谱只需要知道冰箱里有什么食材做哪道菜时再翻哪一页。另一个好处是复用。一个“读取 GKE 集群状态”的 skill既可以用在巡检 Agent 里也可以用在故障排查 Agent 里还可以用在成本分析 Agent 里。如果全写在一个大提示词里每换一个场景就得复制粘贴改一遍维护成本高得离谱。2.2 skills 和普通函数调用、工具调用的区别有人会问这不就是 function calling 吗不完全是。普通的工具调用通常只描述“这个函数叫什么、参数是什么”而一个 skill 除了工具定义还包含使用场景说明、操作步骤、注意事项、输出格式要求甚至示例对话。它更像一份写给 Agent 看的 SOP而不是一个冷冰冰的 API 签名。举个例子一个“查询 GKE 集群节点状态”的工具函数定义可能只有三行。但对应的 skill 会告诉 Agent什么时候该查节点状态比如用户抱怨服务变慢时查出来之后怎么解读Ready 为 False 意味着什么发现异常后下一步该做什么是重启节点还是先看日志。这些“软知识”才是 skills 真正值钱的地方。2.3 为什么 Google Cloud、GKE、Genkit 会出现在热搜里这三个词和 skills 绑在一起不是偶然。GKE 是 Google Cloud 的托管 Kubernetes 服务Genkit 是 Google 推出的 AI 应用开发框架。当你在 Genkit 里编排一个 Agent让它去操作 GKE 集群时你不可能把 kubectl 的所有命令都写进提示词。合理的做法就是写一组 skills一个负责查 Pod 状态一个负责看事件日志一个负责扩缩容一个负责回滚部署。Google Cloud 生态里这类需求特别密集因为云上操作步骤多、状态复杂、出错代价高。一个没经验的 Agent 乱删资源账单能让你心跳加速。所以 skills 在这里不仅是效率工具更是安全护栏——把危险操作封装成需要确认的 skill把只读查询封装成可自动执行的 skill用结构来约束行为。3. 核心细节解析一个 skill 到底长什么样3.1 skill 的基本结构拆解虽然不同平台的具体格式有差异但一个完整的 skill 通常包含这几个部分。我用一个“查询 GKE 集群节点状态”的例子来说明这样更直观。元信息部分负责标识这个 skill 是谁、干什么用的。包括名称、版本、适用场景的一句话描述。名称要短且唯一比如gke-node-status不要叫check-cluster这种含糊的名字否则 Agent 在多个 skill 之间选择时容易懵。触发条件部分告诉 Agent 什么时候该用这个 skill。这里要写具体的用户意图而不是技术描述。比如“当用户询问集群是否健康、节点是否正常、服务为什么变慢时使用”而不是“当需要调用 Kubernetes API 时使用”。前者是 Agent 能理解的语义后者是给程序员看的。执行步骤部分是核心通常是一段自然语言指令告诉 Agent 按什么顺序做什么。比如先获取集群凭证再列出节点再检查每个节点的状态字段最后汇总成表格。步骤要写得像给新人交代任务一样具体不能有歧义。输出格式部分规定结果怎么呈现。是返回 JSON 还是 Markdown 表格异常节点要不要高亮这些都要明确否则每次输出格式都不一样下游处理起来很痛苦。注意事项部分是经验沉淀。比如“如果节点状态是 NotReady不要直接建议删除节点先检查节点上的 Pod 是否有本地存储”“查询前确认当前上下文指向正确的集群避免误操作生产环境”。这些坑都是踩过才知道的。3.2 触发条件怎么写才不让 Agent 选错 skill这是实操中最容易出问题的地方。我见过一个项目里有两个 skill一个叫“查询日志”一个叫“查询指标”触发条件都写的是“当用户想了解系统状态时”。结果 Agent 每次都在两个之间随机选用户问“服务为什么慢”它有时候查日志有时候查指标体验很差。正确的做法是让触发条件互斥且具体。查询日志的 skill 触发条件写成“当用户提到错误、异常、报错、堆栈、日志关键字时使用”查询指标的 skill 写成“当用户提到延迟、QPS、CPU、内存、趋势、曲线时使用”。这样 Agent 根据用户措辞就能做出稳定选择。还有一个技巧是在触发条件里加入反例。比如“本 skill 不适用于查询历史归档日志那种情况请使用 log-archive skill”。明确排除边界能大幅降低误触发。3.3 执行步骤的颗粒度怎么把握步骤写太粗Agent 自由发挥空间太大结果不可控写太细又变成硬编码脚本失去灵活性。我的经验是按“决策点”来切分步骤而不是按“操作”来切分。举个例子查询节点状态这个任务决策点在于集群凭证是否已配置如果没配置是报错还是自动获取节点列表为空时是返回空还是提示可能选错集群每个决策点写清楚判断条件和分支走向中间的具体命令调用反而可以交给 Agent 自己发挥。这样写出来的步骤既有约束又不死板。Agent 知道在关键路口该怎么走但具体开车动作它自己会。3.4 输出格式为什么要强制约定很多人忽略这一点觉得 Agent 返回自然语言就行了。但如果你要把多个 skill 的输出串起来做后续处理格式不统一就是灾难。比如一个 skill 返回“节点正常”另一个返回“所有节点状态为 Ready”第三个返回 JSON你的下游代码根本没法写。强制约定输出格式还有一个好处是便于人工检查。当 Agent 输出一个固定结构的表格时你一眼就能看出哪个字段缺失或异常。如果是一段散文你得逐字读才能发现问题。我通常要求所有查询类 skill 输出 Markdown 表格所有操作类 skill 输出“操作前状态、执行动作、操作后状态、是否成功”四段式。这样无论多少个 skill结果都能拼在一起看。4. 实操过程从零搭一个可用的 skill4.1 环境准备与基础配置假设我们要在 Genkit 框架下做一个操作 GKE 的 Agent并给它配几个 skills。第一步是确认基础环境。你需要一个能访问 Google Cloud 的项目本地装好 gcloud CLI 和 kubectl并且有一个可用的 GKE 集群用于测试。不要拿生产集群练手这是铁律。Genkit 的安装按官方文档走就行通常是 Node.js 环境下用 npm 装。装完之后初始化一个项目你会得到一个基本的 AI 工作流骨架。这时候 Agent 还什么都不会只有一个大模型在背后撑着。接下来要决定 skills 的存放方式。常见有两种一种是每个 skill 一个独立文件放在skills/目录下另一种是集中在一个配置文件里。我推荐前者因为独立文件便于版本管理和复用而且当 skill 数量涨到几十个时集中配置会变成一坨难以维护的巨型 JSON。4.2 编写第一个 skill查询 GKE 节点状态我们从头写一个gke-node-statusskill。文件放在skills/gke-node-status.md内容大致如下。元信息部分写明名称gke-node-status、版本1.0、描述“查询指定 GKE 集群的节点列表及健康状态”。触发条件写“当用户询问集群节点是否正常、节点数量、节点资源使用情况或抱怨服务变慢需要排查基础设施时使用。不适用于查询 Pod 状态或服务配置。”执行步骤分四步。第一步确认当前 kubectl 上下文指向目标集群如果用户未指定集群名称先列出所有可用集群让用户选择。第二步执行节点列表查询获取每个节点的名称、状态、角色、年龄、版本。第三步对状态不是 Ready 的节点进一步查询其详细条件和最近事件。第四步汇总成表格异常节点单独标注。输出格式约定为 Markdown 表格列包括节点名称、状态、角色、版本、异常说明。如果全部正常表格后附一句“所有节点状态正常”。注意事项写三条查询前务必确认集群上下文避免查错集群NotReady 节点不要直接建议删除先看事件如果节点列表为空提示用户可能选错了集群或没有权限。4.3 把 skill 接入 Agent 的加载逻辑skill 文件写好了但 Agent 不会自动知道它的存在。你需要在 Agent 的初始化逻辑里加一段扫描skills/目录的代码把所有 skill 的元信息和触发条件读进来形成一个“skill 索引”注入到系统提示词里。注意这里只注入索引不注入完整内容完整内容等真正要用时再读。这个设计很关键。假设你有 50 个 skill每个平均 500 字全量注入就是 25000 字上下文直接爆掉。只注入索引的话每个 skill 的索引大概 50 字50 个也才 2500 字完全可控。当 Agent 判断用户意图匹配某个 skill 的触发条件时它输出一个“加载 skill”的指令你的框架捕获这个指令把对应 skill 的完整内容读出来追加到上下文里然后 Agent 再按步骤执行。这个过程对用户是透明的用户只看到 Agent 在干活。4.4 实测让 Agent 排查一个节点异常我在测试集群里故意把一个节点的 kubelet 停掉制造 NotReady 状态。然后问 Agent“我的集群好像有点问题帮我看看节点。”Agent 先加载了gke-node-statusskill然后按步骤执行。它先确认了当前上下文列出节点发现一个节点状态是 NotReady。接着它自动触发了第三步查询该节点的详细条件和事件发现 kubelet 停止的报错。最后输出一个表格异常节点被标注出来并附上事件摘要。整个过程没有人工干预从提问到出结果大概十几秒。如果是我手动敲命令至少也要两三分钟还得记得查事件那一步。这就是 skill 的价值把老手的排查路径固化下来让 Agent 照着走。4.5 参数选择与阈值设定的经验在写 skill 时有些地方需要设定阈值。比如“节点年龄超过多少天算老旧”“CPU 使用率超过多少算高”。这些阈值不要拍脑袋定最好从实际运维数据里来。我的做法是先在 skill 里写一个保守的默认值比如 CPU 超过 80% 算高然后在注意事项里注明“此阈值可根据集群实际情况调整”。等跑一段时间后观察 Agent 的告警是否准确再回头修正。不要一开始就追求完美阈值先跑起来再迭代。另一个经验是给阈值加单位。写“80”不如写“80%”写“7”不如写“7天”。Agent 对单位的理解有时候会出偏差写清楚能减少歧义。5. 常见问题与排查技巧实录5.1 Agent 不加载 skill 怎么办最常见的原因是触发条件写得太抽象Agent 没认出来。排查方法是把用户的原话和 skill 的触发条件放在一起对比看语义是否匹配。如果用户说“集群卡了”而触发条件写的是“查询节点健康状态”中间差了一层语义转换Agent 可能就跳过了。解决办法是在触发条件里补充同义表达。比如加上“卡顿、变慢、响应慢、超时”这些词。另一个办法是在系统提示词里加一句“如果不确定用哪个 skill先列出所有可用 skill 让用户确认”给 Agent 一个兜底路径。5.2 skill 执行到一半失败怎么处理skill 的步骤是自然语言不是代码所以没有 try-catch。但你可以在步骤里写异常处理分支。比如“如果查询命令返回权限错误提示用户检查账号权限不要重试”。这样 Agent 遇到错误时知道该停下来报告而不是傻傻重试或者编造结果。我还会在注意事项里写“任何步骤失败后先输出已完成的步骤和失败点再给出建议不要继续执行后续步骤”。这条规则能避免错误累积也方便人工介入。5.3 多个 skill 输出格式冲突怎么统一当你有十几个 skill 时格式很容易走样。我的做法是抽出一个公共的输出规范文件在每个 skill 里引用它。比如规定所有表格必须包含“项目、状态、说明”三列所有操作类输出必须包含“操作前、动作、操作后、结果”四段。然后在每个 skill 的输出格式部分写“遵循公共输出规范 v1”。这样改规范时只需要改一个文件不用逐个 skill 去改。实测下来格式一致性提升非常明显。5.4 常见问题速查表问题现象可能原因排查动作解决方向Agent 不加载 skill触发条件不匹配对比用户原话与触发条件补充同义表达或兜底逻辑加载了错误的 skill触发条件重叠检查是否有语义交叉增加反例排除边界执行中途卡住步骤有歧义看 Agent 停在哪一步细化该步骤的判断条件输出格式混乱未引用公共规范检查 skill 输出部分统一引用公共输出规范操作类 skill 误执行缺少确认环节检查是否有确认步骤危险操作强制加确认查询结果为空上下文选错确认集群/项目/区域在步骤开头加确认环节5.5 几个我踩过的坑第一个坑是skill 名称太相似。我写过get-pod和get-pods两个 skill结果 Agent 经常选错。后来改成pod-single-query和pod-list-query问题就没了。名称要让人一眼看出区别Agent 也一样。第二个坑是在 skill 里写死具体命令。比如直接写kubectl get nodes --contextprod-cluster结果换一个集群就失效。正确做法是写“获取当前上下文对应的节点列表”让 Agent 自己根据上下文决定命令参数。第三个坑是忘记写输出为空的情况。有一次查询返回空列表Agent 不知道该怎么呈现就编了一段“未发现异常”的假话。后来我在输出格式里加了一条“如果结果为空明确输出‘查询结果为空’并提示可能原因”就再没出现过编造。第四个坑是skill 版本没有管理。改了一个 skill 之后旧版本的 Agent 还在用缓存行为不一致。后来我在元信息里加了版本号并且每次加载时检查版本确保用的是最新版。6. 进阶玩法让 skills 组合起来干活6.1 skill 链式调用从排查到修复单个 skill 只能干一件事但真实任务往往是多步的。比如“服务变慢”这个需求完整路径是查节点状态 → 查 Pod 状态 → 查服务指标 → 查日志 → 给出结论。如果每个 skill 都要用户手动触发那和手动敲命令没区别。进阶做法是写一个编排型 skill它的步骤里引用其他 skill。比如diagnose-slow-service这个 skill 的步骤写“第一步加载并执行 gke-node-status第二步如果节点正常加载并执行 pod-status-query第三步如果 Pod 正常加载并执行 service-metrics-query……”这样 Agent 就能自动串起整条链路。注意编排型 skill 本身不包含具体操作只包含调度逻辑。具体操作还是由被引用的 skill 负责。这样职责清晰改一个子 skill 不影响编排逻辑。6.2 用 skills 做安全护栏前面提过skills 可以约束 Agent 的行为。具体做法是把操作分成三类只读类、可自动执行类、需确认类。只读类 skill 比如查询状态Agent 可以直接跑。可自动执行类比如重启一个无状态 Pod可以设定重试次数后自动执行。需确认类比如删除节点、修改集群配置必须在 skill 里写明“执行前输出操作计划并等待用户确认”。这个分类不要写在代码里而是写在 skill 的元信息里比如加一个risk-level字段。Agent 加载 skill 时读取这个字段决定是否需要确认。这样调整风险等级只需要改 skill 文件不用动框架代码。6.3 skills 的版本管理与团队协作当团队多人维护 skills 时版本管理就很重要。我的做法是每个 skill 文件头部写清楚作者、最后修改时间、变更摘要。然后用 Git 管理整个skills/目录每次修改走合并请求至少一个人审核。审核重点看三样触发条件是否和现有 skill 冲突执行步骤是否有歧义注意事项是否覆盖了已知坑。这三样过了基本就不会出大问题。另外建议建一个skills-index.md列出所有 skill 的名称、用途、负责人。新人进来先看这个索引知道有哪些能力可用再去看具体 skill 的实现。6.4 从 skills 到 Agent 能力矩阵当 skill 积累到一定数量你可以画一张能力矩阵横轴是任务类型查询、操作、分析、报告纵轴是资源类型计算、存储、网络、数据库。每个格子里的 skill 数量代表这个领域的能力覆盖度。空白格子就是下一步要补的方向。这张矩阵还能帮你发现冗余。如果查询类计算资源的 skill 有三个功能高度重叠就该合并了。我一般保持每个格子最多两个 skill一个主用一个备用超过就整理。7. 关于 skills 开发的一些个人体会写 skill 这件事技术含量不在代码而在把隐性经验显性化。一个老运维排查问题脑子里有很多“如果这样就看那里”的判断这些判断平时说不出来但写 skill 的时候必须一条条写清楚。这个过程本身就是对经验的梳理写完你会发现自己对业务的理解也深了一层。另一个体会是不要追求一次写完美。我最早的几个 skill 现在回头看写得很粗糙但正是它们跑起来之后暴露了问题我才知道该怎么改。先写一个能用的版本让 Agent 跑起来观察它在哪卡住、在哪选错然后针对性优化。迭代三五轮之后skill 的质量会有质的提升。还有一点是控制 skill 的数量。不是越多越好。skill 太多Agent 选择成本高维护成本也高。我现在的做法是定期清理把三个月没被触发过的 skill 归档把功能重叠的合并。保持一个精简、高命中率的 skill 集合比堆一大堆没人用的强得多。最后分享一个小技巧在 skill 的注意事项里除了写“不要做什么”也写“遇到什么情况时应该向用户提问”。Agent 不是万能的有些模糊需求它猜不出来与其瞎猜不如问。把该问的情况写进 skill能减少很多误解和返工。这个技巧是我在实际使用中慢慢摸索出来的一开始总觉得 Agent 应该自己搞定后来发现明确边界反而让整体体验更好。