谷歌 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+ 点赞。文章提出了五种设计模式:

  1. Tool Wrapper:让 Agent 按需加载某个库的最佳实践
  2. Generator:用模板驱动结构化文档生成
  3. Reviewer:用外部 checklist 对代码进行分级评审
  4. Inversion:Agent 先采访你,再执行
  5. Pipeline:多步骤工作流 + 检查点

这五个模式确实概括了 SKILL.md 的主流用法。但一个关键问题被忽略了:这些"模式"在 adk-python 的源码中到底实现了多少?哪些有框架级保障,哪些只是靠提示词"许愿"?

2. SkillToolset 的三层按需加载架构

ADK 的 skills 体系围绕 SkillToolset 类构建,实现了一套三层 progressive disclosure(渐进式披露):

层级
工具
加载内容
token 成本
L1
list_skills
仅 frontmatter(name + description)
极低
L2
load_skill
SKILL.md 的 instructions 全文
中等
L3
load_skill_resource
references/assets/scripts 中的具体文件
按需

核心初始化代码(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…
— 以上为试看内容(约 40%),开通会员后阅读全文 —