在 Google ADK 中使用 Anthropic Skills：四种加载模式实战

本课讲什么：这是一份 Google ADK 中文教程，聚焦一个具体场景——ADK 如何消费 Anthropic 的 Agent Skills 开放标准。Google 的 Agent Development Kit（ADK）原生支持 SKILL.md 格式，本课跟着官方示例 google/adk-samples/agent-skills-tutorial 一行行拆解它是怎么实现的。

学习目标：读完这一课，你会能够：

1. 理解 ADK 的 SkillToolset 如何把 Anthropic Skills 标准翻译成三层工具（元数据 / 指令 / 资源）
2. 掌握 Skills 的四种加载模式：Inline、File-based、External、Meta
3. 自己复现一个 Blog 写作 Agent：用 ADK 装配 SEO、写作、研究、技能生成四种 Skill
4. 搞清楚什么时候用哪种模式

阅读前提：需要对 Python + LLM Agent 概念有基本了解。不需要读过其他 Skills 教程——本文独立成章。

📦 配套代码：google/adk-samples · agent-skills-tutorial 📅 发布日期：2026-04-25

本课目录

• 开篇故事：为什么 Google 也在做 Skills？
• 第 1 节：问题场景——一个 Blog 写作 Agent 该长什么样？
• 第 2 节：ADK 的 SkillToolset 做了什么？
• 第 3 节：四种 Skill 加载模式逐一拆解
• 第 4 节：四种模式怎么选？
• 第 5 节：动手跑起来
• 第 6 节：和 Anthropic Claude Agent SDK 对比

开篇故事：为什么 Google 也在做 Skills？

你可能会疑惑——Agent Skills 不是 Anthropic 发布的开放标准吗？为什么 Google Cloud 自家的 Agent 框架 ADK，也专门做了一个示例叫 agent-skills-tutorial？

答案很简单：Skills 赢了。

Anthropic 把 Skills 设计成一个开放标准，意思是”这个格式任何模型厂商、任何 Agent 框架都能用”。Google 认可这套设计——它简洁（一个 SKILL.md 文件就够）、它解决真问题（上下文窗口膨胀）、它可组合（多个 Skill 按需加载）。于是 ADK 在自己的工具系统里原生支持 Skills 格式，跑的模型是 Gemini、Claude 还是其他都无所谓。

这意味着什么？同一份 SKILL.md，既能用在 Claude 上，也能用在基于 ADK 构建的任何 Agent 上。写一次，多处落地。

这一课就是要把这件事讲透。我们跟着官方源码 agent-skills-tutorial/app/agent.py 一行行拆，看 ADK 是怎么消费 Anthropic Skills 的。

第 1 节：问题场景——一个 Blog 写作 Agent 该长什么样？

我们要构建的 Agent 有三个常见需求：

1. 写博客：用户扔一个主题，Agent 写出结构清晰的文章
2. 做 SEO：用户扔一篇草稿，Agent 按清单挨个检查优化
3. 做研究：用户扔一个陌生领域，Agent 给出带引用的调研笔记

如果不用 Skills，你会怎么做？

三条路，每一条都别扭：

路线 A：塞进系统提示词。把”SEO 检查清单 + 写作规范 + 研究方法论”全堆进 system prompt。结果：每次对话都要把这坨几千 token 的文本带上，浪费上下文、响应变慢、费用涨。

路线 B：写成 Tools。为 SEO 检查、写作、研究各写一个 Python 函数。结果：这些”技能”的本质不是执行代码，而是给模型一套详细指令。硬塞成函数，指令被锁死在代码里，改一行要重新部署。

路线 C：用 Skills。把每个能力做成一个 SKILL.md 风格的对象：有名字、有简短描述（给 LLM 判断用）、有详细指令（只在被选中时加载）。LLM 默认只看见几行元数据；需要时才拉完整内容。这就是 Anthropic Skills 标准的核心机制——渐进式披露（Progressive Disclosure）。

ADK 的 SkillToolset 就是路线 C 的实现。

第 2 节：ADK 的 SkillToolset 做了什么？

打开官方源码的 app/agent.py，最后那段是整个 Agent 的装配：

from google.adk import Agent
from google.adk.tools.skill_toolset import SkillToolset

skill_toolset = SkillToolset(
    skills=[
        seo_skill,
        blog_writer_skill,
        content_researcher_skill,
        skill_creator,
    ]
)

root_agent = Agent(
    model="gemini-2.5-flash",
    name="blog_skills_agent",
    description="A blog-writing agent powered by reusable skills.",
    instruction="...",
    tools=[skill_toolset],   # ← 关键：整个 toolset 只占 tools 里的一格
)

关键洞察：SkillToolset 不是”把每个 Skill 暴露成一个 tool”。它向 LLM 暴露的是三个通用工具——不管你塞进去几个 Skill：

这三个工具对应的就是渐进式披露三层模型：默认只暴露元数据、按需加载指令、再按需加载参考资源。不管你装 4 个 Skill 还是 40 个，LLM 每次对话看到的只是 list_skills 返回的那点元数据——上下文占用是恒定的。

流程演示

用户问：“帮我审一下这篇博客的 SEO”。

1. LLM 看到的初始信息：工具列表里只有 list_skills、load_skill、load_skill_resource 三个（每个几十字描述）
2. LLM 第一步：调用 list_skills()，拿到 4 个 Skill 的 name + description
3. LLM 判断：看到 seo-checklist 的 description 说”blog 的 SEO 优化清单”，匹配任务
4. LLM 第二步：调用 load_skill("seo-checklist")，拿到完整 9 条检查项
5. LLM 第三步：按清单逐项审查博客

对比传统做法：如果把 4 个 Skill 的全文（加起来几千 tokens）一次性塞进 system prompt，每次无关对话都要承担这笔成本。用 SkillToolset，只有真正需要时才加载。

第 3 节：四种 Skill 加载模式逐一拆解

这也是本课最有价值的部分。官方 agent.py 里四个 Skill 用了四种不同的加载方式，对应四种真实场景。

模式 1：Inline Skill（内联 Skill）

直接在 Python 代码里写出来：

from google.adk.skills import models

seo_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="seo-checklist",
        description=(
            "SEO optimization checklist for blog posts. Covers title tags,"
            " meta descriptions, heading structure, keyword placement,"
            " and readability best practices."
        ),
    ),
    instructions=(
        "When optimizing a blog post for SEO, check each item:\n\n"
        "1. **Title**: 50-60 chars, primary keyword near the start\n"
        "2. **Meta description**: 150-160 chars, includes a call-to-action\n"
        "3. **Headings**: H2/H3 hierarchy, keywords in 2-3 headings\n"
        "... (共 9 条)"
    ),
)

什么时候用？

• 规则简单稳定（SEO 清单这种短期内几乎不变）
• 不需要引用外部文件
• 希望 Skill 的版本和代码一起走 Git 管理

不适合：需要附带模板、脚本、大块参考文档的 Skill。

模式 2：File-Based Skill（文件 Skill）

import pathlib
from google.adk.skills import load_skill_from_dir

blog_writer_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "blog-writer"
)

这一行加载的是磁盘上的一个目录，结构就是 Anthropic Skills 标准规定的样子：

skills/blog-writer/
├── SKILL.md              ← 必须：frontmatter + 指令
├── references/           ← 可选：详细参考文档
│   └── tone-guide.md
├── assets/               ← 可选：模板、数据
│   └── post-template.md
└── scripts/              ← 可选：可执行脚本

关键规则（踩坑警告）：目录名必须和 SKILL.md 里 name 字段完全一致。目录叫 blog-writer，frontmatter 里 name: 也必须是 blog-writer。不一致会直接加载失败。

什么时候用？

• Skill 包含大量文档、模板、脚本
• 希望非程序员也能编辑 Skill（直接改 markdown）
• 同一个 Skill 要在多个 Agent 间共用

这就是 Anthropic Skills 标准的标准形态——一个目录、一个 SKILL.md、可选的 references / assets / scripts。ADK 原生支持这个格式，说明 Skills 标准的设计是对的。

模式 3：External Skill（外部仓库 Skill）

content_researcher_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "content-research-writer"
)

乍一看和模式 2 一样。差别在于 content-research-writer 这个目录不是你自己写的——它是从外部仓库（比如社区开源的 Skills 集合、或者公司内部的共享 Skills 库）下载或 clone 来的。

工作流：

# 你在项目根目录拉一个社区 Skill
cd app/skills/
git clone https://github.com/some-org/content-research-writer.git

之后代码引用方式和模式 2 完全一样。这就是 Skills 开放标准最大的好处：Skill 可以独立分发、版本化、社区共建。

什么时候用？

• 想复用社区共享的高质量 Skill
• 公司内部有共享 Skills 仓库
• Skill 的维护者不一定是你这个 Agent 的作者

模式 4：Meta Skill（会生成 Skill 的 Skill）

这是最酷的一种。我们做一个 Skill，它的任务是生成新的 SKILL.md 文件：

skill_creator = models.Skill(
    frontmatter=models.Frontmatter(
        name="skill-creator",
        description=(
            "Creates new ADK-compatible skill definitions from requirements."
            " Generates complete SKILL.md files following the Agent Skills"
            " specification at agentskills.io."
        ),
    ),
    instructions=(
        "When asked to create a new skill, generate a complete SKILL.md file.\n\n"
        "Read `references/skill-spec.md` for the format specification.\n"
        "Read `references/example-skill.md` for a working example.\n\n"
        "Follow these rules:\n"
        "1. Name must be kebab-case, max 64 characters\n"
        "2. Description must be under 1024 characters\n"
        "3. Instructions should be clear, step-by-step\n"
        "..."
    ),
    resources=models.Resources(
        references={
            "skill-spec.md": "# Agent Skills Specification ...",
            "example-skill.md": "# Example: Code Review Skill ...",
        }
    ),
)

注意 resources= 这一块——它挂了两个参考文档（skill-spec.md 和 example-skill.md）。当 Agent 真正开始生成 Skill 时，会调用 load_skill_resource("skill-creator", "skill-spec.md") 去读这些材料。这是 L3 资源层的用法。

真实用户对话：

用户：“我想要一个 Python 代码安全审查的 Skill，你帮我写个 SKILL.md 吧。”

Agent：

1. list_skills() → 看到 skill-creator 匹配
2. load_skill("skill-creator") → 拿到生成指令
3. load_skill_resource("skill-creator", "skill-spec.md") → 读规范
4. load_skill_resource("skill-creator", "example-skill.md") → 看示例
5. 输出完整 SKILL.md 供用户保存

这就是”自我扩展的 Agent”——Agent 能根据需求生成新能力。这套模式最早来自社区 obra/superpowers 项目。

第 4 节：四种模式怎么选？

决策树：

• 规则就几行？→ Inline
• 有文档/模板/脚本？→ File-based
• 社区已有现成的？→ External
• 想让 Agent 自己扩展自己？→ Meta

生产项目里，四种经常混用。本课的示例 Agent 就是四种全都用一点的设计。

第 5 节：动手跑起来

跟着官方 README 走，5 分钟能跑起来：

# 1. 克隆仓库
git clone https://github.com/google/adk-samples.git
cd adk-samples/python/agents/agent-skills-tutorial

# 2. 建虚拟环境 + 装依赖
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 3. 配 API Key
cp .env.example app/.env
# 编辑 app/.env，填入 GOOGLE_API_KEY（从 aistudio.google.com/apikey 免费获取）

# 4. 启动 ADK Web UI
adk web

浏览器打开 http://localhost:8000，选 blog_skills_agent，挨个试这些查询：

每次对话观察 ADK Web UI 左侧的工具调用序列——你会清楚看到 list_skills → load_skill → load_skill_resource 这个 L1→L2→L3 的渐进式披露过程。

第 6 节：和 Anthropic Claude Agent SDK 对比

学完这课有个自然的问题：Google ADK 的 SkillToolset 和 Anthropic Claude Agent SDK 的 Skills 支持有什么不同？

一句话总结：SKILL.md 格式是跨平台的。你写的 Skill 放到 ADK 能用，放到 Claude Agent SDK 也能用，放到 Claude Code 也能用。这就是开放标准的价值——学一次、处处落地。

本课总结

1. ADK 的 SkillToolset 向 LLM 暴露三个工具：list_skills（L1）/ load_skill（L2）/ load_skill_resource（L3），完美对应 Anthropic Skills 标准的三层渐进式披露。
2. 四种 Skills 加载模式各有定位：Inline 最快、File-based 最标准、External 走社区复用、Meta 让 Agent 自我扩展。
3. SKILL.md 是跨框架通用的。同一份 SKILL.md 写完，放 Claude 能用，放 ADK 也能用。
4. 动手是最好的老师：克隆官方 agent-skills-tutorial，跑 5 个测试查询，你会彻底搞懂渐进式披露。

资源

• 📦 google/adk-samples · agent-skills-tutorial 源码
• 📘 ADK 官方文档
• 🌐 Agent Skills 开放标准 · agentskills.io
• 🎨 obra/superpowers · Meta Skill 灵感来源