1. 从skills这个标题说起我为什么决定深挖它第一次看到skills这个标题时我的直觉是——这词太泛了。泛到几乎没法直接下手。但把热搜词铺开一看方向立刻清晰了Agent Skills、Google Cloud、GKE、Genkit、codex skills、claude agent skills、skills开发、skills安装、skills市场……这些词拼在一起指向的其实是一个非常具体的领域——面向AI Agent的能力扩展机制也就是给智能体装技能这件事。说白了skills就是一套让AI Agent从什么都能聊一点变成某件事真能干的模块化能力包。它可能是一段提示词模板、一组工具调用封装、一段可复用的工作流也可能是一个带元数据的目录结构。你把它挂到Agent上Agent就多会一件事你把它摘下来Agent就回到通用状态。这个思路在2024年下半年到2025年迅速铺开从Claude的Agent Skills到OpenAI Codex的skills体系再到Google Cloud上通过Genkit和GKE部署的Agent能力扩展整个生态都在往技能可插拔这个方向走。这篇文章适合谁看三类人。第一类是想给自己的Agent加能力但不知道从哪下手的开发者第二类是已经在用codex、claude等工具想搞清楚skills到底怎么装、怎么调、怎么自己写的人第三类是把Agent往生产环境推、需要考虑在GKE这类云原生平台上做技能编排和治理的工程团队。我会从设计思路讲到实操细节再到踩坑记录尽量把为什么这么设计和具体怎么做都讲透。需要先说明一点下面涉及的具体配置、目录结构、参数选择一部分来自公开资料的整理一部分是我在实际搭建Agent技能体系时的合理推断和补全。凡是推断的部分我会明确标注避免误导。2. Agent Skills到底是什么核心概念与设计逻辑拆解2.1 一句话定义与它解决的问题Agent Skills本质上是把Agent的某类专项能力从主逻辑里剥离出来做成独立、可描述、可加载、可卸载的单元。它解决的核心问题是通用大模型什么都会一点但在具体任务上不够稳、不够专、不够可控。举个生活化的类比。通用大模型像一个刚毕业的通才沟通能力不错但你让他直接上手做财务报表他大概率会出错。Skills就像给他配的一本岗位操作手册专用工具包手册告诉他这类任务的标准流程是什么工具包给他计算器、模板、校验规则。他照着做成功率立刻上一个台阶。从工程角度看skills带来的价值有三层。第一层是复用一个写好的技能包可以在多个Agent、多个项目里反复用不用每次重写提示词。第二层是隔离技能出问题影响范围被限制在技能内部不会污染Agent的主逻辑。第三层是可治理每个技能有版本、有描述、有权限声明团队协作时能审计、能回滚。2.2 一个Skill通常包含哪些部分不同平台的skills格式不完全一样但核心构件高度相似。我把它归纳成四个部分你可以对照自己用的平台看。构件作用常见形式元数据描述技能名称、版本、适用场景、触发条件YAML/JSON 头部指令体告诉Agent这类任务该怎么做Markdown 或结构化提示词工具声明技能需要调用哪些外部工具或API函数签名、工具清单资源文件模板、示例、参考数据、脚本目录内的附属文件元数据里最关键的是触发条件。这是很多人第一次写skill时最容易忽略的地方。你写了一个生成周报的技能但如果没有清晰的触发描述Agent在用户说帮我整理下这周的工作时可能根本不会去调用它。触发条件要写得像给新同事交代任务什么情况下用这个技能什么情况下不要用。2.3 为什么是技能而不是插件或函数这里有个设计哲学的问题值得说清楚。传统的插件或函数调用是确定性的输入A执行B返回C。但Agent面对的任务往往是模糊的用户说帮我看看这份合同有没有风险这句话没有明确的函数签名。Skills的设计恰好卡在中间它比纯提示词更结构化、更可复用又比硬编码函数更灵活、更能处理模糊输入。它本质上是给Agent的一套软性程序——不是强制它必须走某条路径而是给它一个高质量的默认路径同时保留它根据实际情况调整的空间。这也是为什么skills在codex、claude这类工具里特别受欢迎。这些工具的用户经常需要处理半结构化任务比如写论文、做分镜、挖漏洞、整理资料这些任务既需要专业性又没法完全用固定流程覆盖。Skills正好补上了这块。3. Skills的目录结构与编写规范从零写一个能用的技能3.1 标准目录长什么样虽然各平台有差异但一个可移植性好的skill目录通常长这样my-skill/ ├── SKILL.md # 主文件元数据 指令体 ├── tools/ # 工具声明与封装 │ └── tools.json ├── resources/ # 模板、示例、参考数据 │ ├── template.md │ └── examples/ └── scripts/ # 可选辅助脚本 └── validate.pySKILL.md是入口几乎所有平台都认这个文件名。它的头部用YAML写元数据下面用Markdown写指令。我见过不少人把指令写得又长又散结果Agent执行时抓不住重点。指令体的写法有讲究后面单独讲。3.2 元数据字段怎么填以常见的字段为例我列一个我实际用过的模板--- name: weekly-report-generator version: 1.2.0 description: 根据本周的工作记录生成结构化周报 trigger: 当用户要求生成周报、整理本周工作、汇总进展时使用 tools: - read_file - write_file - format_markdown ---这里有几个细节值得说。description要写做什么trigger要写什么时候用两者不要混。我早期偷懒把两者合并结果Agent经常在不该调用的时候调用比如用户只是随口说这周好累它就开始生成周报。分开写之后误触发率明显下降。version字段别省。技能是要迭代的没有版本号出了问题你都不知道回滚到哪一版。我建议用语义化版本小改动加patch位新增能力加minor位破坏性变更加major位。3.3 指令体的写法像写SOP不像写作文指令体是skill的灵魂。我的经验是把它当成给一个新员工的SOP来写而不是当成一篇说明文。SOP的特点是步骤明确、判断条件清晰、异常处理有交代。一个反例是这样的这个技能可以帮助你生成周报。周报应该包含本周完成的工作、遇到的问题和下周计划。请根据用户提供的信息生成。这段话看着没毛病但Agent执行时会飘。因为它不知道本周完成的工作要写几条、格式是什么、信息不全时怎么办。正例应该是生成周报时按以下结构输出本周完成从用户提供的工作记录中提取已完成事项每条一行格式为- [事项][结果]遇到的问题提取阻塞项或风险项若无则写无下周计划从用户记录中提取待办若无明确待办则基于本周未完成项推断 若用户未提供工作记录先询问请提供本周的工作记录不要自行编造。对比一下正例里每一步都有明确的输入来源、输出格式和异常分支。Agent照着做稳定性完全不一样。3.4 工具声明与权限边界工具声明这块很多人会忽略权限最小化原则。你的技能只需要读文件就别给它写文件的权限。这不是洁癖是安全底线。Agent一旦被注入恶意指令权限越大破坏越大。工具声明通常是一个清单列出技能会调用的工具名。有些平台还支持声明必需工具和可选工具必需工具缺失时技能直接不可用可选工具缺失时降级运行。这个设计很实用建议用上。注意写工具声明时不要声明可能用到的工具只声明确定会用的。声明越多Agent的决策空间越大越容易跑偏。4. 在主流平台上安装与调用Skills的实操流程4.1 本地安装目录放哪、怎么加载大多数支持skills的工具加载逻辑都是扫描指定目录读取SKILL.md注册到Agent。所以第一步是搞清楚你的工具从哪个目录读技能。常见的位置有三类工具安装目录下的skills/子目录、用户主目录下的配置目录比如~/.config/xxx/skills/、以及项目根目录下的.skills/。优先级通常是项目级 用户级 全局级这样项目可以覆盖全局配置。安装一个技能的基本步骤从技能市场或仓库下载技能包通常是一个压缩包或一个目录解压后检查SKILL.md是否存在、元数据是否完整把技能目录放到工具的skills扫描路径下重启工具或执行重载命令让Agent重新扫描用一句触发语测试确认技能被正确加载第5步很多人跳过结果技能明明装了却没生效排查半天。测试方法很简单说一句明确匹配trigger的话看Agent的响应里有没有体现技能的逻辑。如果响应和没装技能时一样说明没加载成功。4.2 云端部署GKE Genkit这条链路把Agent Skills放到生产环境Google Cloud这条链路是绕不开的。核心组合是Genkit做技能编排GKE做运行时承载。Genkit是Google出的Agent开发框架它的定位是帮你把提示词、工具调用、技能编排串成一条可测试、可部署的流水线。你可以把每个skill理解成Genkit里的一个flow节点节点之间通过明确定义的输入输出连接。GKE则是把这些flow跑起来的地方。为什么用GKE而不是简单的函数计算因为Agent技能往往需要长连接、状态保持、多技能协同函数计算的无状态模型不太适配。GKE的Pod可以常驻技能之间的调用延迟更低也方便做灰度发布和版本管理。一个典型的部署链路是这样的# 1. 本地用Genkit定义技能flow genkit flow:run weeklyReport --input {records: ...} # 2. 构建容器镜像 docker build -t my-agent-skills:v1.2.0 . # 3. 推送到镜像仓库 docker push registry.example.com/my-agent-skills:v1.2.0 # 4. 部署到GKE kubectl apply -f deployment.yaml kubectl rollout status deployment/agent-skillsdeployment.yaml里要重点配置的是资源限制和健康检查。技能执行可能耗时较长健康检查的超时时间要给够否则Pod会被误杀。我一般把initialDelaySeconds设成30秒以上timeoutSeconds设成10秒。4.3 技能市场与下载渠道的甄别热搜里skills下载平台有哪些skills大全skills推荐这类词很多说明大家最关心的是去哪找现成的技能。我的建议是分三类渠道对待。第一类是官方市场比如各工具自带的技能仓库。这类渠道的优点是格式规范、有审核、更新及时缺点是数量有限。优先用这类。第二类是社区仓库比如GitHub上的开源技能集合。这类渠道数量多、覆盖广但质量参差不齐。下载前一定要看三样东西最近更新时间、issue区的反馈、SKILL.md里有没有可疑的工具声明。一个技能如果声明了网络请求权限又没说明用途直接跳过。第三类是个人分享。这类渠道风险最高因为技能本质上是可执行的指令恶意技能可能诱导Agent泄露信息或执行危险操作。我的做法是个人分享的技能先在一个隔离环境里跑一遍确认行为符合预期再正式用。注意任何要求你提供API密钥、账号密码才能激活的技能一律不要用。正规技能不需要这些。5. 高频场景实战写论文、做分镜、自动挖洞的Skills怎么配5.1 写论文类Skills结构化输出是关键codex写论文的skills是热搜里的高频词说明这个场景需求很集中。写论文类技能的核心难点不是写而是结构和引用。一个可用的论文技能指令体里至少要包含三块章节骨架、引用规范、查重规避提示。章节骨架告诉Agent论文该分几部分、每部分写多少字引用规范告诉它引用格式比如APA、MLA查重规避提示则是提醒它不要大段照搬要改写。我实际配过的一个版本指令体开头是这样的生成论文时按以下结构输出摘要150-250字包含研究问题、方法、结论引言说明研究背景与问题引用至少3篇文献方法描述数据来源与分析方法结果呈现分析结果配合表格或数据讨论解释结果含义指出局限参考文献按APA格式列出 每处引用必须标注来源不得编造文献。最后那句不得编造文献很重要。不加这句Agent很容易生成看起来像真的、实际不存在的参考文献。这是写论文类技能最常见的坑。5.2 分镜类Skills把视觉语言翻译成文字指令分镜skills下载这个词说明做视频、做动画的人也在用Agent。分镜技能的本质是把一段文字脚本翻译成镜头语言。一个分镜技能的指令体需要定义镜头的基本要素景别远、全、中、近、特、机位平、俯、仰、运动推、拉、摇、移、时长、画面内容、音效提示。Agent拿到脚本后按这些要素逐镜输出。我见过效果比较好的分镜技能会要求Agent先输出一个镜头表再逐镜展开。镜头表是概览逐镜展开是细节。这样用户可以先看整体节奏再调单个镜头效率高很多。5.3 自动挖洞类Skills安全边界必须写死自动挖洞skills这个需求比较特殊涉及安全测试。这类技能在配置时授权范围必须写死在指令体里。具体做法是在指令体开头明确声明仅对用户明确授权的目标执行测试并在工具声明里限制只能访问用户提供的目标列表。同时技能应该拒绝执行任何超出授权范围的请求哪怕用户后续追加要求。这不是技术问题是责任问题。Agent技能一旦被滥用后果比普通脚本严重得多因为它能自主决策。所以这类技能的指令体里拒绝逻辑要和执行逻辑一样详细。6. 踩坑记录与常见问题速查6.1 技能不生效的排查顺序技能装了没反应是最常见的问题。我整理了一个排查顺序按这个走基本能定位。排查项检查方法常见原因目录位置确认技能在扫描路径下放错目录工具没扫到文件命名确认入口文件名正确大小写错误如skill.md元数据格式用YAML校验工具检查缩进错误、冒号后缺空格触发条件用明确匹配的话测试trigger写得太模糊工具依赖确认声明的工具都存在声明了未安装的工具加载日志查看工具启动日志技能被跳过日志有提示我遇到最多的是元数据格式问题。YAML对缩进极其敏感一个tab和一个空格的区别就能让整个技能加载失败。建议写完用在线YAML校验器过一遍。6.2 技能之间互相干扰怎么办当你装了多个技能可能会出现该调用A却调用了B的情况。这通常是触发条件重叠导致的。解决办法有两个。一是把trigger写得更具体加入排除条件比如当用户要求生成周报时使用但用户只是闲聊工作感受时不要使用。二是给技能加优先级字段有些平台支持priority数值高的优先匹配。如果两个技能确实功能相近考虑合并成一个技能用内部分支处理不同情况。技能不是越多越好维护成本会随数量上升。6.3 技能更新后行为变了技能迭代后行为变化往往是因为指令体改动影响了Agent的判断。我的经验是每次改指令体都要重新跑一遍回归测试。回归测试不用很复杂准备5-10个典型输入覆盖正常情况、边界情况、异常情况每次改动后跑一遍对比输出。如果某个输入的输出和预期不符就定位到具体是哪句指令改动导致的。版本号在这里就派上用场了。发现新版本有问题直接回滚到上一个版本先恢复可用再慢慢排查。6.4 几个我踩过的具体坑第一个坑指令体里用了尽量最好这类模糊词。Agent对这类词的理解很不稳定有时当强制要求有时当建议。后来我全部改成必须应当禁止行为立刻稳定了。第二个坑技能里写了示例但示例和指令矛盾。Agent会优先学示例导致行为偏离指令。教训是示例必须和指令一致不一致就删掉示例。第三个坑技能依赖的外部工具超时没处理。技能调用一个APIAPI挂了技能就卡住。后来在指令体里加了若工具调用失败重试一次仍失败则告知用户并终止健壮性好了很多。7. 技能体系的扩展方向与个人体会Skills这套机制真正有意思的地方在于它把能力变成了可组合的积木。单个技能解决单点问题多个技能组合起来就能覆盖一整条工作流。比如资料检索技能 摘要技能 结构化输出技能串起来就是一个完整的研究助手。往后看我觉得技能体系会往三个方向走。一是技能编排的自动化Agent自己判断该调用哪些技能、按什么顺序调用而不是靠用户手动指定。二是技能的版本治理像管理代码依赖一样管理技能依赖有锁文件、有兼容性检查。三是技能的评测标准化每个技能带一套基准测试用户装之前能看它在标准任务上的表现。我个人的体会是写技能这件事七分靠对任务的理解三分靠对Agent行为的理解。你对任务理解得越透指令体写得越像SOP技能就越好用。反过来如果你自己都没想清楚这个任务的标准流程是什么指望Agent帮你理清基本不现实。最后分享一个小技巧写新技能时先别急着写指令体先用自然语言跟Agent对话把任务跑通一遍把有效的对话过程记录下来再从中提炼指令体。这样写出来的技能比凭空构思的靠谱得多。我现在的技能基本都是这么来的返工率低很多。