构建智能体的安全技能树 - Claude 环境下 Agent Skills 的多元实践（下篇）

本文作为实战收官之作，将聚焦于如何在 Claude API、Claude Code、Claude Agent SDK 三大平台上真正上手使用 Skills，完成从理论到落地的最后一公里。

人工智能小豪

236人浏览 · 2026-03-31 11:11:24

人工智能小豪 · 2026-03-31 11:11:24 发布

一、概述

本文作为实战收官之作，将聚焦于如何在 Claude API、Claude Code、Claude Agent SDK 三大平台上真正上手使用 Skills，完成从理论到落地的最后一公里。

二、在 Claude API 中使用 Skills

上篇文章已经介绍了 Skills 在 Claude AI 中的运作机制。本节我们将以 Claude Messages API 为切入点，展开 API 层面的实操讲解。

要在 Claude API 中正常使用 Skills，我们需要依赖两个核心组件：代码执行工具和 Files API。这两个组件共同赋予 Claude 访问文件系统的能力，使其能够读写文件，并通过 Bash 执行代码。

1 两个重要注意事项

第一：Skills 不跨环境共享。你在 Claude AI 和 Claude Desktop 中创建的 Skills 不会在 Claude API 或 Claude Code 中共享。这意味着我们需要在不同环境之间手动迁移 Skills。建议把常用的 Skills 保存到一个 Git 仓库里，这样在不同环境中都能快速部署，还能做版本控制。

第二：功能需要手动配置。为了让 Skills 正常工作，我们需要让 Claude 具备执行代码、创建和编辑文档、演示文稿、PDF 以及数据报告，并且能与文件系统交互的能力。在使用 Claude API 时，这些功能都需要我们手动配置，而在使用 Claude AI 和 Claude Desktop 时，这些功能会直接为你配置好。

2 代码执行工具：给 Claude 一个代码执行环境

在使用 Claude Code 和 Claude Agent 这类工具时，可以直接访问文件系统。而使用 Claude API 时则无法直接访问，我们需要一个容器来执行代码，并搭配一个文件系统来完成交互。

代码执行工具允许 Claude 运行 Bash 或 Shell 命令，从而实现我们在使用 skills 时看到的种种操作：创建、查看、编辑文件，以及编写代码——所有这些都在一个沙箱环境中进行。

当我们集成代码执行工具时，相当于为 Claude 提供了一个执行沙箱或容器。该环境对内存、磁盘、CPU 等资源都设置了明确的限制。更重要的是，它默认没有互联网连接，但预装了一些开箱即用的基础库。

⚠️ 注意：这种无互联网连接的限制是 Messages API 特有的。当我们在 Claude AI 或 Claude Desktop 中使用代码执行工具时，是可以正常访问互联网，并下载和安装各类依赖包的。

3 Files API：文件的上传下载通道

代码执行工具与 Claude API 提供的 Files API 形成了良好的配合关系。Files API 负责上传和下载那些可以在容器内运行和处理的文件。

你可以设想这样一个场景：用户要求对某些输入内容进行总结，并将总结结果保存到一个文本文件中。我们首先使用 Files API 上传输入文件，将其发送到容器中处理，最后再通过这个Files API 将生成的结果文件下载回来。

在 Claude AI 等工具中开箱即用的 skills 库，或者通过 API 自行添加的 skills，都统一存储在容器内的一个特定目录中。

当我们开始从这个skills目录中读取内容，向skills中添加信息，或者利用这些底层技能创建新的、可供下载或上传的文件时，技能目录就真正发挥出了它的价值。

关键发现：在使用 API 时，如果想要使用skills，必须同时启用代码执行工具。技能本身的格式和定义不会因环境而变化，但不同环境下使用skills的具体方式会略有差异。

5 示例

这里使用上一篇文章中的练习题生成 Skill的案例，来对 Claude API 下 skill 的使用方法行讲解。

整体流程如下：先将编写好的 Skill 上传至容器，再上传讲义笔记，将内容发送给 API 处理；处理完成后，将生成的练习题从容器下载到本地。

代码如下：

from dotenv import load_dotenv
import anthropic
from anthropic.lib import files_from_dir

_ = load_dotenv()

client = anthropic.Anthropic()

# 上传自定义的skill到容器中
skill = client.beta.skills.create(
    display_title="Practice Question Generator",
    files=files_from_dir("./custom_skills/generating-practice-questions"),
    betas=["skills-2025-10-02"]
)

print(f"Skill ID: {skill.id}")

# 查看加载的所有自定义skill
skills = client.beta.skills.list(source="custom")
for custom_skill in skills:
    print(f"ID: {skill.id}. Display Title: {skill.display_title}")

# 上传要分析的文件    
file_object = client.beta.files.upload(
    file=open("./lecture_notes/notes04.tex", "rb"),
)

# 发送请求
response = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    betas=["code-execution-2025-08-25","skills-2025-10-02", "files-api-2025-04-14"],  
    container={
        "skills": [{
            "type": "custom", 
            "skill_id": skill.id, 
            "version": "latest"}]
    },
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Generate practice questions in Markdown format from these lecture notes"},
            {"type": "container_upload", "file_id": file_object.id}
        ]
    }],
    tools=[{
        "type": "code_execution_20250825",
        "name": "code_execution"
    }]
)

# 查看响应类型
for block in response.content:
    print(block.type)
    
# 定义颜色代码
BOLD = "/033[1m"
RESET = "/033[0m"
BLUE = "/033[94m"
GREEN = "/033[92m"
YELLOW = "/033[93m"
CYAN = "/033[96m"

# 详细打印响应内容
for block in response.content:
    if block.type == "text":
        print(f"{BOLD}{BLUE}[TEXT]{RESET}")
        print(block.text, "/n")
    
    if block.type == "server_tool_use":
        print(f"{BOLD}{GREEN}[SERVER_TOOL_USE]{RESET}")
        input_preview = block.input.copy()  
        if"file_text"in input_preview:
            text = input_preview["file_text"]
            if len(text) > 100:
                input_preview["file_text"] = text[:100] + " ..."
        print(input_preview, "/n")
    
    if block.type == "text_editor_code_execution_tool_result":
        print(f"{BOLD}{YELLOW}[TOOL_RESULT]{RESET}")
        content_str = str(block.content)
        preview = content_str[:100]
        if len(content_str) > 100:
            preview += " ..."
        print(preview, "/n")
    
    if block.type == "bash_code_execution_tool_result":
        print(f"{BOLD}{CYAN}[BASH_RESULT]{RESET}")
        print(block.content, "/n")
        
    
# 从容器中下载最终分析后的结论文件
file_id = None
for block in response.content:
    if block.type == 'bash_code_execution_tool_result':
        if hasattr(block, 'content') and hasattr(block.content, 'content'):
            for result_block in block.content.content:
                if hasattr(result_block, 'file_id'):
                    file_id = result_block.file_id
                    break
if file_id:
    file_content = client.beta.files.download(
        file_id=file_id,
        betas=["files-api-2025-04-14"]
    )
    with open("notes04.md", "wb") as f:
        file_content.write_to_file(f.name)

三、在 Claude Code 中使用 Skills

==================================

Claude Code 是一个强大的智能体助手，它运行在终端中，不仅擅长编码，也能处理通过命令行完成的几乎所有任务。

1 Claude Code 工作原理

当向 Claude Code 下达一个任务时，它会经历三个阶段：收集上下文 → 采取行动 → 验证结果。

Claude 在整个过程中会不断调用各类工具，无论是搜索文件以理解代码，编辑文件以进行修改，还是运行测试以检查工作成果。这个循环会根据具体需求灵活调整：

对于代码库的提问，可能只需要收集上下文即可完成
对于修复错误的任务，则需要反复经历所有三个阶段
对于重构工作，往往需要广泛的验证环节

智能体循环由两个核心组件驱动：

组件	职责
模型（Model）	负责推理——理解代码、分析任务、制定计划
工具（Tools）	负责行动——读写文件、执行命令、搜索网页

2 扩展 Claude Code

Claude Code 的核心是内置工具（文件操作、搜索执行、Web 访问），但在这一核心之上，还构建了一个扩展层，提供更丰富的定制能力：

功能	作用	何时使用
CLAUDE.md	每个对话都会加载的持久上下文	项目约定，"总是做 X"规则
Skills	指令、知识和可调用的工作流	可重用内容、参考文档、可重复任务
MCP	连接到外部服务	外部数据或操作
Subagents	在隔离上下文中运行自己的循环	上下文隔离、并行任务
Hooks	在事件上运行的确定性脚本	可预测的自动化，不需要 LLM

3 Skills 是最灵活的扩展

一个 Skill 本质上是一个包含知识、工作流程或指令的 Markdown 文件。可以使用斜杠命令（例如 /deploy）调用 Skill，也可以让 Claude 在相关场景下自动加载它们。

Skills 有两种类型：

参考型（Reference）：提供 Claude 在整个会话中持续使用的知识（例如 API 样式指南）
行动型（Action）：告诉 Claude 做一些特定的操作（例如 /deploy 运行部署工作流程）

4 Skill和子智能体功能对比

Skill和子智能体有些功能可能看起来相似，以下是区分它们的方法：

Skills 是可加载到任何上下文的可重用内容
子智能体是与主对话分开运行的隔离工作者
子智能体可以预加载特定 Skills（skills: 字段）
Skills 可以使用 context: fork 在隔离上下文中运行
它们可以结合使用——当需要上下文隔离或上下文窗口即将填满时，使用子智能体

5 上下文成本管理

添加的每一个功能都会消耗 Claude 的上下文资源。过多的功能不仅可能填满上下文窗口，还可能引入噪音，降低 Claude 的工作效率。

按功能划分的上下文成本：

功能	加载时机	上下文成本
CLAUDE.md	会话开始时完整加载	高（建议 500 行以下）
Skills 描述	会话开始时加载描述	低（名称+描述）
Skills 内容	触发时加载	按需
MCP 服务器	连接时加载工具定义	中
子智能体定义	配置时加载	中

可以通过在 Skills 的 frontmatter 中设置 disable-model-invocation: true 来完全隐藏 Skill，直到手动调用——这样可以将上下文成本降至零。

6 插件与市场

插件是打包层。插件将 Skills、Hooks、子智能体和 MCP 服务器捆绑到一个可安装的单元中。插件中的 Skills 采用命名空间机制（例如 /my-plugin:review），因此多个插件可以共存而不会冲突。当希望在多个代码仓库中复用同一套配置，或通过市场分发给其他用户时，使用插件是最佳选择。

7 会话管理

Claude Code 的会话有几个重要特性：

会话是短暂的：与 claude.ai 不同，Claude Code 在会话之间没有持久内存
每个新会话从头开始：Claude 不会"记住"上周处理过什么
持久信息放入 CLAUDE.md：这是唯一的跨会话记忆载体

四、用 Claude Agent SDK 构建研究智能体

在本章节中，将脱离网页版 Claude 和命令行界面（CLI），深入讲解如何使用 Claude Agent SDK 以编程方式构建复杂的智能体应用。

这里将从零开始构建一个通用研究智能体（Research Agent）。该智能体模拟了一个高效的工程团队：由一个"指挥官"利用标准流程（Skills）制定计划，并行调度三个"专家"（Sub-agents）进行分工协作，最终通过 MCP 将成果交付到外部系统（Notion）。

1 核心架构：指挥官与专家团队

使用 SDK 构建的系统架构可以映射为传统的企业组织结构：

架构层级	概念隐喻	代码组件	具体实现
The Brain	指挥官/编排者	Main Agent + TaskTool	负责理解需求，加载技能制定计划，分派任务，最后合成报告
The Arms	专家/执行者	AgentDefinition（子智能体）	Docs Researcher（查文档）、Repo Analyzer（跑代码）、Web Researcher（搜视频）
Process	标准作业程序	SkillTool	`learning-a-tool` ：定义"如何学习新工具"的标准流程技能
Connectivity	外部连接器	MCP Server	Notion MCP：将生成的报告写入云端 Notion 页面

关键区别：在本案例中，技能（Skill）是专门给主智能体用的，作为其规划的指导手册；而子智能体（Sub-agents）则是去执行具体脏活累活的。

2 环境搭建与工程结构

为了让 SDK 正确加载技能和智能体定义，文件结构必须遵循特定的规范：

research-agent/
├── .env                  # 🔑 存放 ANTHROPIC_API_KEY, NOTION_API_TOKEN
├── agent.py              # 🧠 主程序入口 (The Brain)
├── agents/               # 🤖 子智能体定义 (The Arms)
│   ├── docs_researcher.md
│   ├── repo_analyzer.md
│   └── web_researcher.md
└── .claude/              # 📚 技能库 (Infrastructure)
    └── skills/           # ⚠️ 必须命名为 'skills'（复数）
        └── learning-a-tool/
            ├── SKILL.md
            └── progressive_learning.md

初始化项目并安装 Python 依赖：

# 初始化 uv 项目
uv init

# 安装 Claude Agent SDK 及相关工具
uv add claude-agent-sdk python-dotenv asyncio

3 代码实现核心逻辑

agent.py 是整个系统的控制中心。

第一步：导入与工具配置

SDK 默认是只读且安全的。为了让智能体能写代码和上网，必须显式授权：

from claude_agent_sdk.tools import Bash, Write, WebSearch, WebFetch

allowed_tools = [
    Write,      # 允许写文件 (生成 README.md 等)
    Bash,       # 允许执行 Shell 命令 (如 git clone)
    WebSearch,  # 允许联网搜索
    WebFetch    # 允许抓取网页内容
]

第二步：集成 MCP（Notion）

mcp_servers = {
    "notion": {
        "command": "uv",
        "args": ["run", "mcp-server-notion"],
        "env": {"NOTION_API_TOKEN": os.getenv("NOTION_API_TOKEN")}
    }
}

# 必须将 MCP 工具加入允许列表
allowed_tools.append("mcp_notion_*")

第三步：加载技能与任务调度

from claude_agent_sdk.tools import SkillTool, TaskTool

# 配置 SkillTool
skill_tool = SkillTool(setting_sources=["project", "user"])

# 配置 TaskTool（需要先加载子智能体定义）
task_tool = TaskTool(agents=sub_agent_definitions)

allowed_tools.extend([skill_tool, task_tool])

4 角色定义与分工

角色	核心职责	关键工具配置
Main Agent	编排与合成。加载技能制定计划，分派任务，汇总结果并写入 Notion	TaskTool, SkillTool, mcp_notion_*
Docs Researcher	文档研究。查找和阅读官方文档	WebSearch, WebFetch
Repo Analyzer	代码分析。克隆 GitHub 仓库，分析文件结构和代码逻辑	Bash（执行 git clone）, Read, Grep
Web Researcher	广泛搜索。查找教程、视频（YouTube）和社区讨论	WebSearch, WebFetch