Claude Code官方文档Agent SDKSkillsHooks

Agent SDK 中使用 Claude Code 功能 - 项目说明、Skills、Hooks 加载

将项目说明、skills、hooks 和其他 Claude Code 功能加载到您的 SDK 代理中。

发布于 2025年5月1日 · 阅读约 21 分钟

在 SDK 中使用 Claude Code 功能

将项目说明、skills、hooks 和其他 Claude Code 功能加载到您的 SDK 代理中。

Agent SDK 建立在与 Claude Code 相同的基础之上，这意味着您的 SDK 代理可以访问相同的基于文件系统的功能：项目说明（CLAUDE.md 和规则）、skills、hooks 等。

当您省略 settingSources 时，query() 读取与 Claude Code CLI 相同的文件系统设置：用户、项目和本地设置、CLAUDE.md 文件以及 .claude/ skills、代理和命令。要在没有这些的情况下运行，请传递 settingSources: []，这会将代理限制为您以编程方式配置的内容。无论此选项如何，都会读取托管策略设置和全局 ~/.claude.json 配置。请参阅 settingSources 不控制的内容。

有关每个功能的概念概述以及何时使用它，请参阅扩展 Claude Code。

使用 settingSources 控制文件系统设置

设置源选项（Python 中的 setting_sources、TypeScript 中的 settingSources）控制 SDK 加载哪些基于文件系统的设置。传递显式列表以选择加入特定源，或传递空数组以禁用用户、项目和本地设置。

此示例通过将 settingSources 设置为 ["user", "project"] 来加载用户级和项目级设置：

Python：

from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async for message in query(
    prompt="Help me refactor the auth module",
    options=ClaudeAgentOptions(
        # "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
        # Together they give the agent access to CLAUDE.md, skills, hooks, and
        # permissions from both locations.
        setting_sources=["user", "project"],
        allowed_tools=["Read", "Edit", "Bash"],
    ),
):
    if isinstance(message, AssistantMessage):
        for block in message.content:
            if hasattr(block, "text"):
                print(block.text)
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(f"\nResult: {message.result}")

TypeScript：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Help me refactor the auth module",
  options: {
    // "user" loads from ~/.claude/, "project" loads from ./.claude/ in cwd.
    settingSources: ["user", "project"],
    allowedTools: ["Read", "Edit", "Bash"]
  }
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "text") console.log(block.text);
    }
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log(`\nResult: ${message.result}`);
  }
}

每个源从特定位置加载设置，其中 <cwd> 是您通过 cwd 选项传递的工作目录，或者如果未设置则为进程的当前目录。

源	加载的内容	位置
`"project"`	项目 CLAUDE.md、`.claude/rules/*.md`、项目 skills、项目 hooks、项目 `settings.json`	`<cwd>/.claude/` 以及每个父目录直到文件系统根目录（当找到 `.claude/` 或不再有父目录时停止）
`"user"`	用户 CLAUDE.md、`~/.claude/rules/*.md`、用户 skills、用户设置	`~/.claude/`
`"local"`	CLAUDE.local.md（gitignored）、`.claude/settings.local.json`	`<cwd>/`

省略 settingSources 等同于 ["user", "project", "local"]。

cwd 选项确定 SDK 查找项目设置的位置。如果 cwd 及其任何父目录都不包含 .claude/ 文件夹，则项目级功能将不会加载。

settingSources 不控制的内容

settingSources 涵盖用户、项目和本地设置。无论其值如何，都会读取一些输入：

输入	行为	禁用方式
托管策略设置	主机上存在时始终加载	删除托管设置文件
`~/.claude.json` 全局配置	始终读取	使用 `env` 中的 `CLAUDE_CONFIG_DIR` 重新定位
`~/.claude/projects/<project>/memory/` 处的自动内存	默认加载到系统提示中	在设置中设置 `autoMemoryEnabled: false`，或在 `env` 中设置 `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`

⚠️ 不要依赖默认 query() 选项进行多租户隔离。因为上述输入无论 settingSources 如何都会被读取，SDK 进程可能会获取主机级配置和按目录内存。对于多租户部署，在自己的文件系统中运行每个租户，并设置 settingSources: [] 加上 env 中的 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。请参阅安全部署。

项目说明（CLAUDE.md 和规则）

CLAUDE.md 文件和 .claude/rules/*.md 文件为您的代理提供关于您的项目的持久上下文：编码约定、构建命令、架构决策和说明。当 settingSources 包含 "project"（如上面的示例）时，SDK 在会话开始时将这些文件加载到上下文中。然后代理遵循您的项目约定，而无需在每个提示中重复它们。

CLAUDE.md 加载位置

级别	位置	加载时间
项目（根）	`<cwd>/CLAUDE.md` 或 `<cwd>/.claude/CLAUDE.md`	`settingSources` 包含 `"project"`
项目规则	`<cwd>/.claude/rules/*.md`	`settingSources` 包含 `"project"`
项目（父目录）	`cwd` 上方目录中的 `CLAUDE.md` 文件	`settingSources` 包含 `"project"`，在会话开始时加载
项目（子目录）	`cwd` 子目录中的 `CLAUDE.md` 文件	`settingSources` 包含 `"project"`，当代理读取该子树中的文件时按需加载
本地（gitignored）	`<cwd>/CLAUDE.local.md`	`settingSources` 包含 `"local"`
用户	`~/.claude/CLAUDE.md`	`settingSources` 包含 `"user"`
用户规则	`~/.claude/rules/*.md`	`settingSources` 包含 `"user"`

所有级别都是累加的：如果项目和用户 CLAUDE.md 文件都存在，代理会看到两者。级别之间没有硬优先级规则；如果说明冲突，结果取决于 Claude 如何解释它们。编写不冲突的规则，或在更具体的文件中明确说明优先级（“这些项目说明覆盖任何冲突的用户级默认值”）。

💡 您也可以通过 systemPrompt 直接注入上下文，而无需使用 CLAUDE.md 文件。请参阅修改系统提示。当您希望在交互式 Claude Code 会话和 SDK 代理之间共享相同的上下文时，使用 CLAUDE.md。

有关如何构建和组织 CLAUDE.md 内容，请参阅管理 Claude 的内存。

Skills

Skills 是 markdown 文件，为您的代理提供专业知识和可调用的工作流。与 CLAUDE.md（每个会话都加载）不同，skills 按需加载。代理在启动时接收 skill 描述，并在相关时加载完整内容。

Skills 通过 settingSources 从文件系统中发现。当 query() 上的 skills 选项被省略时，发现的用户和项目 skills 会被启用，Skill 工具可用，与 CLI 行为相匹配。要控制启用哪些 skills，请将 skills 作为 "all"、skill 名称列表或 [] 传递以禁用所有。SDK 在设置 skills 时会自动启用 Skill 工具，因此您无需将其添加到 allowedTools。

Python：

from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

# Skills in .claude/skills/ are discovered automatically
# when settingSources includes "project"
async for message in query(
    prompt="Review this PR using our code review checklist",
    options=ClaudeAgentOptions(
        setting_sources=["user", "project"],
        skills="all",
        allowed_tools=["Read", "Grep", "Glob"],
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

TypeScript：

import { query } from "@anthropic-ai/claude-agent-sdk";

// Skills in .claude/skills/ are discovered automatically
for await (const message of query({
  prompt: "Review this PR using our code review checklist",
  options: {
    settingSources: ["user", "project"],
    skills: "all",
    allowedTools: ["Read", "Grep", "Glob"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

ℹ️ Skills 必须创建为文件系统工件（.claude/skills/<name>/SKILL.md）。SDK 没有用于注册 skills 的编程 API。有关完整详情，请参阅 SDK 中的 Agent Skills。

有关创建和使用 skills 的更多信息，请参阅 SDK 中的 Agent Skills。

Hooks

SDK 支持两种定义 hooks 的方式，它们并行运行：

文件系统 hooks： 在 settings.json 中定义的 shell 命令，当 settingSources 包含相关源时加载。这些与您为交互式 Claude Code 会话配置的 hooks 相同。
编程 hooks： 直接传递给 query() 的回调函数。这些在您的应用程序进程中运行，可以返回结构化决策。请参阅使用 hooks 控制执行。

两种类型在相同的 hook 生命周期中执行。如果您已经在项目的 .claude/settings.json 中有 hooks，并且您设置 settingSources: ["project"]，那些 hooks 会在 SDK 中自动运行，无需额外配置。

Hook 回调接收工具输入并返回决策字典。返回 {}（空字典）意味着允许工具继续。返回 {"decision": "block", "reason": "..."} 会阻止执行，原因会作为工具结果发送给 Claude。有关完整的回调签名和返回类型，请参阅 hooks 指南。

Python：

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, ResultMessage


# PreToolUse hook callback. Positional args:
#   input_data: HookInput dict with tool_name, tool_input, hook_event_name
#   tool_use_id: str | None, the ID of the tool call being intercepted
#   context: HookContext, carries session metadata
async def audit_bash(input_data, tool_use_id, context):
    command = input_data.get("tool_input", {}).get("command", "")
    if "rm -rf" in command:
        return {"decision": "block", "reason": "Destructive command blocked"}
    return {}  # Empty dict: allow the tool to proceed


# Filesystem hooks from .claude/settings.json run automatically
# when settingSources loads them. You can also add programmatic hooks:
async for message in query(
    prompt="Refactor the auth module",
    options=ClaudeAgentOptions(
        setting_sources=["project"],  # Loads hooks from .claude/settings.json
        hooks={
            "PreToolUse": [
                HookMatcher(matcher="Bash", hooks=[audit_bash]),
            ]
        },
    ),
):
    if isinstance(message, ResultMessage) and message.subtype == "success":
        print(message.result)

TypeScript：

import { query, type HookInput, type HookJSONOutput } from "@anthropic-ai/claude-agent-sdk";

const auditBash = async (input: HookInput): Promise<HookJSONOutput> => {
  if (input.hook_event_name !== "PreToolUse") return {};
  const toolInput = input.tool_input as { command?: string };
  if (toolInput.command?.includes("rm -rf")) {
    return { decision: "block", reason: "Destructive command blocked" };
  }
  return {}; // Empty object: allow the tool to proceed
};

for await (const message of query({
  prompt: "Refactor the auth module",
  options: {
    settingSources: ["project"], // Loads hooks from .claude/settings.json
    hooks: {
      PreToolUse: [{ matcher: "Bash", hooks: [auditBash] }]
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

何时使用哪种 hook 类型

Hook 类型	最适合
文件系统（`settings.json`）	在 CLI 和 SDK 会话之间共享 hooks。支持 `"command"`（shell 脚本）、`"http"`（POST 到端点）、`"mcp_tool"`（调用连接的 MCP 服务器的工具）、`"prompt"`（LLM 评估提示）和 `"agent"`（生成验证器代理）。这些在主代理和它生成的任何子代理中触发。
编程（`query()` 中的回调）	应用程序特定的逻辑；返回结构化决策；进程内集成。仅限于主会话。

ℹ️ TypeScript SDK 支持超出 Python 的其他 hook 事件，包括 SessionStart、SessionEnd、TeammateIdle 和 TaskCompleted。有关完整的事件兼容性表，请参阅 hooks 指南。

有关编程 hooks 的完整详情，请参阅使用 hooks 控制执行。有关文件系统 hook 语法，请参阅 Hooks。

选择正确的功能

Agent SDK 为您提供了多种方式来扩展代理的行为。如果您不确定使用哪种，此表将常见目标映射到正确的方法。

您想要…	使用	SDK 表面
设置代理始终遵循的项目约定	CLAUDE.md	`settingSources: ["project"]` 自动加载它
为代理提供它在相关时加载的参考材料	Skills	`settingSources` + `skills` 选项
运行可重用的工作流（部署、审查、发布）	用户可调用的 skills	`settingSources` + `skills` 选项
将隔离的子任务委托给新的上下文（研究、审查）	子代理	`agents` 参数 + `allowedTools: ["Agent"]`
协调多个 Claude Code 实例，具有共享任务列表和直接的代理间消息传递	代理团队	不直接通过 SDK 选项配置。代理团队是一个 CLI 功能，其中一个会话充当团队负责人，协调独立队友之间的工作
在工具调用上运行确定性逻辑（审计、阻止、转换）	Hooks	`hooks` 参数带回调，或通过 `settingSources` 加载的 shell 脚本
为 Claude 提供对外部服务的结构化工具访问	MCP	`mcpServers` 参数

💡 子代理与代理团队： 子代理是临时的和隔离的：新对话、一个任务、摘要返回给父代理。代理团队协调多个独立的 Claude Code 实例，这些实例共享任务列表并直接相互消息传递。代理团队是一个 CLI 功能。

您启用的每个功能都会增加代理的上下文窗口。有关每个功能的成本以及这些功能如何分层组合，请参阅扩展 Claude Code。

在 SDK 中使用 Claude Code 功能

使用 settingSources 控制文件系统设置

settingSources 不控制的内容

项目说明（CLAUDE.md 和规则）

CLAUDE.md 加载位置

Skills

Hooks

何时使用哪种 hook 类型

选择正确的功能

相关资源