Skill 技能开发与应用 · 编写与封装 · 2026-03-23

谷歌出品,Agent Skill的5种设计模式

谷歌揭秘Agent Skill设计的5大黄金法则,开发者必看!

核心内容:

  1. SKILL.md标准化趋势与当前设计挑战
  2. 五大核心设计模式详解(工具包装器/生成器/审查器等)
  3. 工程化实践:渐进加载与校验机制保障技能可靠性

Agent Skill一经推出,便迅速在技术圈走红。更因为使用起来极为简单方便,使得它早已抄超越技术门槛,为越来越多得人所使用。

Skill的大量使用,也催生了一些提示词标准化使用的新范式。比如"把提示词工程做成可复用的技能包(SKILL.md)"这种范式,已在开发者圈里快速升温。

一方面,Gemini CLI 等工具已经把 SKILL.md + YAML 元数据 + references/assets 目录固化成标准化的技能封装方式;另一方面,围绕技能能否跨工具复用、如何渐进加载、怎样避免把一堆脆弱指令塞进系统提示等讨论也在各种社区持续发酵。

甚至有人开始做 SKILL.md 的 lint/校验工具,来解决跨工具不兼容与引用路径失效等问题。

Google Cloud Tech发布的这篇名为《5 Agent Skill design patterns every ADK developer should know》文章,正是从这股热潮切入的。该文指出"格式之争"基本结束,真正的胜负手在内容设计:同样的外壳(SKILL.md),内部逻辑却可能千差万别。

文章作者根据生态实践提炼出 5 种可复用的技能结构模式,并配套 ADK 代码示例,帮助团队把经验沉淀为可执行、可审计、可组合的智能体工作流。

文章要点:

以下是正文。

每个ADK开发者都应该知道的5种Agent Skill设计模式

在 SKILL.md 文件方面,开发者往往过度关注格式问题:确保 YAML 格式正确、合理组织目录结构以及遵循规范。但随着超过 30 种智能体工具(如 Claude Code、Gemini CLI 和 Cursor)都标准化采用相同的布局,格式问题实际上已成历史。

现在的挑战在于内容设计。规范说明了如何打包技能,但对如何构建其内部逻辑却没有提供任何指导。例如,一个封装 FastAPI 约定的技能与一个四步文档管道的运作方式完全不同,尽管它们的 SKILL.md 文件从外部看起来完全相同。

从 Anthropic 的代码库到 Vercel 和 Google 的内部指南,通过研究整个生态系统中技能的构建方式,我们可以发现五种反复出现的设计模式,它们可以帮助开发者构建更可靠的智能体。

作者:@Saboo_Shubham_ 和 @lavinigam

本文通过可运行的 ADK 代码介绍每种模式:

模式 1:工具包装器

工具包装器为您的智能体提供特定库的按需上下文。与其将 API 约定硬编码到系统提示中,不如将它们打包成一个技能,您的智能体仅在实际使用该技术时才加载此上下文。

这是最简单的实现模式。SKILL.md 文件监听用户提示中的特定库关键词,从 references/ 目录动态加载内部文档,并将这些规则作为绝对准则应用。这正是将团队内部编码指南或特定框架最佳实践直接分发到开发者工作流中的标准机制。

以下是一个工具包装器示例,用于教导智能体如何编写 FastAPI 代码。注意指令如何明确告知智能体:仅在开始审查或编写代码时,才加载 conventions.md 文件:

## skills/api-expert/SKILL.md---name:api-expertdescription:FastAPI开发最佳实践和约定。在构建、审查或调试FastAPI应用程序、RESTAPI或Pydantic模型时使用。metadata:pattern:tool-wrapperdomain:fastapi---您是FastAPI开发专家。将这些约定应用于用户的代码或问题。## 核心约定加载'references/conventions.md'以获取完整的FastAPI最佳实践列表。## 审查代码时1.加载约定参考文档2.根据每个约定检查用户的代码3.对于每个违规,引用具体规则并建议修复方案## 编写代码时1.加载约定参考文档2.严格遵循每个约定3.为所有函数签名添加类型注解4.使用Annotated 风格进行依赖注入
## skills/api-expert/SKILL.md---name: api-expertdescription: FastAPI development best practices and conventions. Use when building, reviewing, or debugging FastAPI applications, REST APIs, or Pydantic models.metadata: pattern: tool-wrapper domain: fastapi---You are an expert in FastAPI development. Apply these conventions to the user's code or question.## Core ConventionsLoad 'references/conventions.md' for the complete list of FastAPI best practices.## When Reviewing Code1. Load the conventions reference2. Check the user's code against each convention3. For each violation, cite the specific rule and suggest the fix## When Writing Code1. Load the conventions reference2. Follow every convention exactly3. Add type annotations to all function signatures4. Use Annotated style for dependency injection

模式 2:生成器

工具包装器负责应用知识,而生成器则负责强制输出一致性。如果您的智能体在每次运行时生成不同的文档结构,生成器通过协调填空式流程来解决这一问题。

生成器利用两个可选目录:assets/ 存放输出模板,references/ 存放样式指南。指令充当项目经理的角色,告知智能体加载模板、阅读样式指南、向用户询问缺失变量并填充文档。这对于生成可预测的 API 文档、标准化提交消息或搭建项目脚手架尤为实用。

在以下技术报告生成器示例中,技能文件本身不包含实际的布局规则或语法规则,而是仅负责协调各类资产的调取,并强制智能体逐步执行:

## skills/report-generator/SKILL.md---name:report-generatordescription:生成结构化的Markdown技术报告。当用户要求编写、创建或起草报告、摘要或分析文档时使用。metadata:pattern:generatoroutput-format:markdown---您是技术报告生成器。严格按照以下步骤执行:步骤1:加载'references/style-guide.md'以获取语气和格式规则。步骤2:加载'assets/report-template.md'以获取所需的输出结构。步骤3:向用户询问填充模板所需的任何缺失信息:-主题或主旨-关键发现或数据点-目标受众(技术人员、管理层、普通用户)步骤4:按照样式指南规则填充模板。模板中的每个部分都必须出现在输出中。步骤5:以单个Markdown 文档的形式返回已完成的报告。
## skills/report-generator/SKILL.md---name: report-generatordescription: Generates structured technical reports in Markdown. Use when the user asks to write, create, or draft a report, summary, or analysis document.metadata: pattern: generator output-format: markdown---You are a technical report generator. Follow these steps exactly:Step 1: Load 'references/style-guide.md' for tone and formatting rules.Step 2: Load 'assets/report-template.md' for the required output structure.Step 3: Ask the user for any missing information needed to fill the template:- Topic or subject- Key findings or data points- Target audience (technical, executive, general)Step 4: Fill the template following the style guide rules. Every section in the template must be present in the output.Step 5: Return the completed report as a single Markdown document.

模式 3:审查器

审查器模式将"检查什么"与"如何检查"分离开来。与其在冗长的系统提示中逐一列举每种代码坏味道,不如将模块化的评审标准存储在 references/review-checklist.md 文件中。

当用户提交代码时,智能体加载此检查清单并系统地对提交内容评分,按严重程度对发现结果进行分组。只需将 Python 风格检查清单替换为 OWASP 安全检查清单,使用完全相同的技能基础设施,即可获得一套截然不同的专项安全审计。这是自动化 PR 审查或在人工介入之前主动捕获漏洞的高效方法。

以下代码审查器技能展示了这种分离架构。指令部分保持静态不变,但智能体从外部检查清单动态加载具体的审查标准,并强制输出按严重程度分类的结…

— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/tishicikuangjia/2026032369814.html