Skills 与 Agent SDK

最后一课，我们用 Claude Agent SDK 构建一个研究型 Agent。它使用 Skill 指导研究方法论，调度三个 Subagents 分别从文档、GitHub 仓库和网络搜索中提取信息，最终合成一份完整的学习指南。

Claude Agent SDK 简介

Claude Agent SDK 是一种程序化构建 Agentic 应用的方式，使用的底层 Harness 与 Claude Code 相同。区别在于你完全控制 Agent 的定义、工具权限和运行环境。

系统架构

Main Agent（编排器）
├── docs_researcher     → 分析官方文档
├── repo_analyzer       → 克隆并分析 GitHub 仓库
├── web_researcher      → 搜索文章、视频、社区内容
└── Notion MCP Server   → 将结果写入 Notion

Main Agent 负责编排：调度 Subagents、收集结果、按 Skill 指令合成输出。

三个 Subagents 各有专职：

Subagent工具职责
docs_researcherWebSearch, WebFetch定位并提取官方文档内容
repo_analyzerWebSearch, Bash, Read, Glob, Grep克隆仓库，分析代码结构
web_researcherWebSearch, WebFetch搜索教程、视频、社区资源

每个 Subagent 的 Prompt 中定义了：处理流程、输入格式、执行指南和输出格式。

Skill：learning-a-tool

这个 Skill 不是给 Subagents 使用的，而是指导 Main Agent 的研究方法论和输出结构：

研究阶段：为每个 Subagent 指定具体要寻找的信息——官方文档要提取什么、仓库要分析什么、社区资源要搜索什么。

组织阶段：使用渐进式披露加载 progressive-learning.md，定义学习路径的分级结构：

  1. Overview & Motivation — 工具解决什么问题
  2. Installation & Setup — 安装和核心概念
  3. Practical Patterns — 实际使用模式
  4. Where to Go Next — 进阶资源

输出阶段：指定精确的目录结构和文件格式——README、resources、learning path、code examples。

Skill 确保无论研究什么工具，输出格式都是一致且可预测的。

搭建 Agent

基础结构

import asyncio
from dotenv import load_dotenv
from claude_agent_sdk import Agent

load_dotenv()

async def main():
    agent = Agent(
        system_prompt="You are a helpful assistant.",
        allowed_tools=[]
    )

    while True:
        user_input = input("You: ")
        response = await agent.run(user_input)
        print(response)

asyncio.run(main())

添加工具权限

Read、Grep、Glob 等只读工具默认可用。需要显式添加的工具：

allowed_tools=[
    "Write",        # 写文件
    "Bash",         # 执行命令（git clone 等）
    "WebSearch",    # 搜索网络
    "WebFetch",     # 获取网页内容
    "mcp_notion_*", # Notion MCP 所有工具
    "Task",         # 调度 Subagents
    "Skill",        # 读取和使用 Skills
]

重要：allowed_tools 必须包含 Main Agent 和所有 Subagents 需要的工具。即使你在 Subagent 定义中指定了工具，如果 allowed_tools 中没有，Subagent 也无法使用。

连接 MCP Server

import os

agent = Agent(
    system_prompt=main_agent_prompt,
    allowed_tools=allowed_tools,
    mcp_servers={
        "notion": {
            "command": "npx",
            "args": ["-y", "@notionhq/notion-mcp-server"],
            "env": {"NOTION_TOKEN": os.getenv("NOTION_TOKEN")}
        }
    }
)

MCP 工具通过 mcp_<server>_<tool> 格式引用。mcp_notion_* 表示使用 Notion 提供的所有工具。

定义 Subagents

from claude_agent_sdk import AgentDefinition

agents = {
    "docs_researcher": AgentDefinition(
        description="Researches official documentation for a tool",
        prompt=docs_researcher_prompt,
        tools=["WebSearch", "WebFetch"]
    ),
    "repo_analyzer": AgentDefinition(
        description="Analyzes GitHub repositories",
        prompt=repo_analyzer_prompt,
        tools=["WebSearch", "Bash", "Read", "Glob", "Grep"]
    ),
    "web_researcher": AgentDefinition(
        description="Searches for tutorials, articles, and community content",
        prompt=web_researcher_prompt,
        tools=["WebSearch", "WebFetch"]
    )
}

加载 Skills

需要两个配置：

  1. 在 allowed_tools 中添加 "Skill" 工具
  2. 通过 setting_sources 指定 Skills 搜索路径
agent = Agent(
    system_prompt=main_agent_prompt,
    allowed_tools=allowed_tools,
    agents=agents,
    mcp_servers=mcp_servers,
    setting_sources=["user", "project"]  # 搜索 ~/.claude/skills/ 和 .claude/skills/
)

Skills 的存放位置与 Claude Code 一致：.claude/skills/<skill-name>/SKILL.md。

实战：为 MinerU 生成学习指南

MinerU 是一个开源 PDF 提取库——Claude 训练数据中可能了解不多，非常适合测试研究型 Agent。

步骤 1：展示计划

Help me get started with MinerU. Create a learning guide. Show me your plan first.

Agent 识别到 learning-a-tool Skill，生成研究计划：

  • 并行调度三个 Subagents
  • 按 Skill 定义的结构组织内容
  • 输出预期的目录结构

步骤 2：执行研究

确认计划后，三个 Subagents 并行执行：

  • docs_researcher → 前往官方文档站
  • repo_analyzer → 克隆 GitHub 仓库，分析代码结构
  • web_researcher → 搜索教程、YouTube 视频、社区资源

步骤 3：合成输出

Subagents 完成后，Main Agent 按 Skill 定义的结构合成：

learning-mineru/
├── README.md              # 学习指南总览、时间估算
├── resources.md           # 文档、教程、视频、社区链接
├── learning-path.md       # 分级学习路径
└── code-examples/
    ├── 01-hello-world/    # 安装、首次提取
    ├── 02-core-concepts/  # 核心概念、后端对比
    └── 03-patterns/       # 生产级使用模式

步骤 4：写入 Notion（可选）

Write ./learning-mineru/resources.md to the "Resources" subpage
under Learning in Notion. Use rich formatting.

Agent 通过 Notion MCP Server 将 Markdown 内容转换为 Notion blocks，写入指定页面。

Main Agent Prompt 设计要点

Main Agent 的 Prompt 中需要处理 Skill 可能存在或不存在的情况：

If a skill is provided and matches the user's request,
follow that skill's instructions precisely.

因为这是一个通用研究 Agent，不是所有请求都会匹配到 Skill。有 Skill 时按 Skill 流程走，没有时按通用研究方法执行。

安全注意事项

课程中为了简化演示，Write 和 Bash 等工具无需用户确认即可执行。生产环境中应该：

  • 构建权限确认界面，类似 Claude Code 的工具审批机制
  • 添加 Interrupt 机制，允许用户中断 Agent 和 Subagent 执行
  • 对 Bash 工具执行的命令做安全审查

关键要点

  • Agent SDK 使用与 Claude Code 相同的底层 Harness
  • Skills 存放在 .claude/skills/，通过 setting_sources 指定搜索路径
  • allowed_tools 必须包含所有 Agent 和 Subagents 需要的工具
  • Subagents 通过 AgentDefinition 定义，用 Task 工具调度
  • MCP Server 通过 mcp_servers 参数配置，工具用 mcp_<server>_* 引用
  • Skill 可以指导 Main Agent 的编排策略，不一定要给 Subagents
  • 三个 Subagents 并行执行，大幅提升研究效率

课程资料