谷歌 ADK 的 5 类 Agent Skill 设计模式
TL;DR:结合 adk-python 源码,讨论下 Google Cloud Tech 发布的 5 类 Agent Skill 设计模式。
1. Agent Skill 设计讨论
2026 年 3 月 18 日,Google Cloud Tech 官方推文发布了一篇长文: "5 Agent Skill design patterns every ADK developer should know" ,by @Saboo_Shubham_ 和 @lavinigam。48 小时内收获 99 万+查看、2800+ 点赞。文章提出了五种设计模式:
Tool Wrapper:让 Agent 按需加载某个库的最佳实践 Generator:用模板驱动结构化文档生成 Reviewer:用外部 checklist 对代码进行分级评审 Inversion:Agent 先采访你,再执行 Pipeline:多步骤工作流 + 检查点
这五个模式确实概括了 SKILL.md 的主流用法。但一个关键问题被忽略了:这些"模式"在 adk-python 的源码中到底实现了多少?哪些有框架级保障,哪些只是靠提示词"许愿"?
2. SkillToolset 的三层按需加载架构
ADK 的 skills 体系围绕 SkillToolset 类构建,实现了一套三层 progressive disclosure(渐进式披露):
list_skills | |||
load_skill | |||
load_skill_resource |
核心初始化代码(skill_toolset.py):
class SkillToolset(BaseToolset):
def __init__(
self,
skills: list[models.Skill],
*,
code_executor: Optional[BaseCodeExecutor] = None,
script_timeout: int = 300,
additional_tools: list[ToolUnion] | None = None,
):
# 去重校验:同名 skill 直接 raise ValueError
self._skills = {skill.name: skill for skill in skills}
process_llm_request 方法在每次大模型调用前注入 system instruction 和可用 skills 的 XML 摘要:
async def process_llm_request(self, tool_context, llm_request):
# 注入默认 system instruction(告知大模型如何使用 skills)
llm_request.config.system_instruction += _DEFAULT_SKILL_SYSTEM_INSTRUCTION
# 注入 <available_skills> XML(仅 name + description)
llm_request.config.system_instruction += format_skills_as_xml(skills)
这套设计的核心价值在于:Agent 在对话开始时只"看到" skill 的名字和描述(L1),只有当大模型判断需要某个 skill 时才加载完整指令(L2),再按需加载具体资源(L3)。这确实能有效控制上下文消耗。
3. 逐一拆解:5 个 Pattern 的源码
3.1 Tool Wrapper:references/ 按需加载——最扎实的 Pattern ✅
Tool Wrapper 是五个模式中实现最完整的。它的核心是 LoadSkillResourceTool:
# skill_toolset.py - LoadSkillResourceTool.run_async()
async def run_async(self, *, args, tool_context):
path = args["path"]
if path.startswith("references/"):
content = skill.resources.get_reference(rel_path)
elif path.startswith("assets/"):
content = skill.resources.get_asset(rel_path)
elif path.startswith("scripts/"):
content = skill.resources.get_script(rel_path)
当 SKILL.md 中写着 Load 'references/conventions.md',LLM 会调用 load_skill_resource(skill_name="api-expert", path="references/conventions.md"),触发上述代码加载对应文件。
官方示例 contributing/samples/skills_agent/ 中的 weather-skill 完整演示了这个模式:
skills/weather-skill/
├── SKILL.md # 指令:按步骤加载 references 和执行 scripts
├── references/
│ └── weather_info.md # 天气相关的知识文档
└── scripts/
└── get_humidity.py # 可执行脚本
评价:有框架级代码支撑。references/ 的按需加载是 LoadSkillResourceTool 的核心路径,经过测试。企业可以放心使用。
3.2 Generator:assets/ 模板引擎——有基础,缺校验 ✅
Generator 模式在源码中同样由 LoadSkillResourceTool 支撑——path.startswith("assets/") 分发到 get_asset()。SKILL.md 中写 Load 'assets/report-template.md',Agent 就能拿到模板。
但关键差距在于:模板"填充"逻辑完全由大模型执行 instructions 完成。框架不会校验输出是否包含模板中的所有 section,也不会检查格式一致性。
SKILL.md 写的: "Every section in the template must be present"
源码做的: 把 assets/report-template.md 的文本返回给 LLM,然后...就没了
评价:资源加载有代码支撑,但输出质量保障依赖大模型的指令遵循度。对于格式要求严格的企业场景(如合规报告),建议在 skill 外层加 Pydantic 校验。
3.3 Reviewer:checklist 即 references——同一机制的语义变体 ✅
Reviewer 模式在源码层面与 Tool Wrapper 完全共享同一套代码。references/review-checklist.md 被加载的方式和 references/conventions.md 一模一样。
区别仅在于 SKILL.md 的 instructions 赋予了不同语义:
Tool Wrapper:「按 conventions 写代码」 Reviewer:「按 checklist 逐条评分」
评分逻辑(error/warning/info 分级)、结构化输出(Summary/Findings/Score)——这些全部由 instructions 中的自然语言驱动,源码不参与。
评价:和 Tool Wrapper 一样可靠。但企业若需要稳定的 JSON 格式评审结果,请在 Agent 外层加 output parser。
3.4 Inversion:多轮门控——框架级空白 ⚠️
这是第一个需要警惕的 Pattern。
文章中 Inversion 的核心是"阶段门控":
"DO NOT start building until all phases are complete"
但在 adk-python 源码中,没有任何代码实现阶段状态管理或门控逻辑。我们搜索了整个 skills 模块和 SkillToolset:
无 phase或stage状态无 "gate" 或 "checkpoint" 拦截器 tool_context.state中唯一与 skill 相关的 key 是_adk_activated_skill_{agent_name},仅记录哪个 skill 被激活,不记录执行到哪个阶段
这意味着 "DO NOT proceed" 的约束完全依赖大模型对自然语言的遵守。实测表明:
GPT-4…