从 Claude Code 到 Web API：解构 AI Agent 的技能体系

困惑的起点

我在 Claude Code 中构建了一套完整的内容创作工具链：写文章、生成配图、制作播客、抓取网页内容、生成绘图提示词，甚至一键发布到公众号。这些 skills 在 Claude Code 环境中配合得天衣无缝，我只需要用自然语言描述需求，它们就能自动协同工作。

但这套能力有个致命局限：它只能在我的 Claude Code 环境中运行。我不可能让每个想用这些功能的人都去安装 Claude Code、配置 skills、学习命令行操作。更重要的是，如果我想实现自动化，比如定时抓取内容、批量生成文章、自动发布，总不能一直守着 Claude Code 手动操作吧？

真正的需求是：让这些能力可以通过 Web 界面访问，可以通过 API 被其他系统调用，可以自动化运行，可以开放给更多人使用。

这篇文章就是要解决这个问题。我会先带你理解 Claude Code 的 SDK 体系，Skills、Agents、Subagents 的本质和协作方式，然后给出具体可行的解耦方案，让你也能把自己的 skills 从 Claude Code 中解放出来。

Skills、Agents、Subagents：一个做菜的比喻

要解耦 skills，首先要理解它们的本质。我用一个做菜的比喻来解释：

Skills（技能）就像菜谱。比如我用的 brainstorming skill，就像一份"头脑风暴菜谱"，上面写着：什么时候用这个菜谱（开始做新功能前）、具体步骤是什么（先问一个问题、再提几个方案、最后分段呈现设计）。重点是：Skills 不是代码，而是一份 Markdown 文档，就像菜谱是文字而不是食材。

举个实际例子：我的"写文章 skill"里写着："先理解用户想写什么主题 → 问清楚目标读者是谁 → 提出 3 种文章结构 → 用户选择后，分段写作并逐段确认"。这就是一份"菜谱"。

Agents（代理）就像请来的专业厨师。比如 code-reviewer agent 就像一位专门负责品鉴的大厨，他有自己的评判标准、专业术语、沟通方式。你把做好的菜交给他，他会按照自己的专业标准给出反馈。Agent 和主 Claude 是分开的，就像主厨和品鉴师是两个人。

Subagents（子代理）就像临时工。比如你要做 10 道菜，每道菜都叫一个新的临时厨师来做，做完这道菜他就走了，下一道菜再叫一个新的。为什么这样？因为每个临时工只专注做一道菜，不会被之前的菜影响判断，也不会把上一道菜的调料带到下一道菜里。

它们怎么配合？你（Claude Code 主实例）手里拿着菜谱（Skills），决定今天做什么菜。需要专业意见时，请来大厨（Agent）。需要批量做菜时，雇一堆临时工（Subagents），每人做一道。

Claude Code 在背后做了什么？

现在你可能会问：既然 Skills 只是 Markdown 文档，为什么它们在 Claude Code 中能自动工作，离开就不行了？答案是：Claude Code 在背后做了大量"脏活累活"。

第一件事：自动加载和触发。你把 skill 文件放到 .claude/skills/ 目录，Claude Code 会自动扫描、解析、在合适的时机触发。就像你把菜谱放进菜谱架，厨房系统会自动识别"哦，今天要做新菜，应该先看看这份'准备工作菜谱'"。

举例：我的 brainstorming skill 文件开头写着 `description: "You MUST use this before any creative work"`，Claude Code 看到我要创建新功能，就自动把这份 skill 的内容注入到对话中。我不需要手动说"请使用 brainstorming skill"。

第二件事：提供工具箱。Claude Code 内置了一堆工具：读文件（Read）、写文件（Edit）、执行命令（Execute）、搜索代码（Grep）等等。我的"发布公众号 skill"能工作，是因为它可以调用这些工具——读取文章内容、调用发布 API、保存结果。

第三件事：管理上下文。所有 skills 共享同一个"工作台"：同样的文件系统、同样的 git 仓库、同样的对话历史。我的"写文章 skill"生成的内容，"生成配图 skill"可以直接读取，"发布公众号 skill"可以直接使用。就像所有厨师在同一个厨房工作，食材、调料、工具都共享。

Claude Agent SDK：给 Claude 一台计算机

Claude Agent SDK 是 Anthropic 官方提供的 Agent 开发框架。它的核心理念很简单：给 Claude 一台计算机。

什么意思？就像程序员工作需要终端、文件系统、代码编辑器，Claude 也需要这些工具才能真正"干活"。SDK 就是提供这些能力的框架。

整个系统分三层，每层干不同的事：

用户层：这是你和系统交互的地方。可以是网页、可以是 API、可以是命令行。你在这里提需求，系统在这里给你结果。

编排层：这是"大脑"。主 Agent 在这里工作，它的任务是：听懂你要什么、决定该调用哪些 skills、协调它们的执行顺序、管理整个过程的上下文（记住之前发生了什么）。Skills 也在这一层，它们是"工作手册"，告诉 Agent 该怎么做事。

执行层：这是"手脚"。Subagents 在这里干具体的活：写文件、调用 API、生成图片、发布内容。Tools（工具函数）也在这里，它们是具体的能力。还有文件系统，作为工作空间存放中间结果。

简单说：用户层接需求，编排层做决策，执行层干活。就像你去餐厅点菜（用户层），经理安排厨师和流程（编排层），厨师做菜（执行层）。

一个完整例子：写文章并发布

让我用一个完整的例子来说明 Skills、Agents、Subagents 是如何协作的。

场景：你要写一篇文章并发布到公众号。

Skills 是"剧本"，定义了整个工作应该怎么做。比如你有一个"内容创作 skill"，它的剧本是这样的：

1. 先问用户：写什么主题？目标读者是谁？

2. 提出 3 种文章结构让用户选择

3. 分段写作，每段写完确认一次

4. 文章完成后，生成配图

5. 最后发布到公众号

Skills 不干活，它只告诉 Agent"该做什么、按什么顺序做"。就像菜谱告诉你先切菜、再炒菜、最后装盘，但菜谱本身不会动手。

Agent 是"项目经理"，它拿着 Skills 这份剧本，负责执行和调度。当你说"我要写一篇关于 AI 的文章"，主 Agent 会：

- 理解你的需求

- 找到"内容创作 skill"这份剧本

- 按照剧本的步骤，开始工作

- 决定什么时候该派发 Subagent 去干具体的活

- 收集所有结果，最终交付给你

Agent 做决策，但不亲自干重活。就像项目经理规划任务、分配工作，但不会自己去写代码。

Subagents 是"临时工"，专门负责某一个具体任务。在这个例子中，主 Agent 会派发多个 Subagents：

- 写作 Subagent：负责写文章的某一段

- 配图 Subagent：负责调用图片生成 API，生成配图

- 发布 Subagent：负责调用公众号 API，完成发布

每个 Subagent 只关注自己的任务，完成后就消失。为什么要这样？因为上下文隔离。写作 Subagent 不需要知道配图的细节，配图 Subagent 不需要知道发布的逻辑。这样每个任务都是"干净"的，不会互相干扰。

三者的协作关系：Skills 定义流程 → Agent 执行调度 → Subagents 完成任务。这种分工让系统既灵活又可控。你可以随时修改 Skills（换菜谱），Agent 会按新流程执行。你可以增加新的 Tools 给 Subagents 用（添加新厨具）。整个系统是模块化的。

解耦的挑战：你需要自己做什么？

现在问题来了：如果你想把 skills 搬到 Web 或 API 环境，Claude Code 帮你做的那些事，你都得自己做。具体来说四件事：

1.Skill 加载和触发：读取 skill 文件，判断什么时候用哪个 skill

2.工具函数：实现图片生成、公众号发布等具体功能

3.上下文管理：让不同 skills 之间能传递数据和结果

4.Agent 管理：派发和协调多个 AI 实例

听起来很复杂？确实如此。但好消息是：有办法解决。

三种解耦方案

理解了 Claude Agent SDK 的架构和分工，"如何解耦"的答案就呼之欲出了。关键在于编排层。执行层相对简单（调用 API、操作文件），用户层也好办（做个网页或 API 接口）。难的是编排层：如何让主 Agent 理解需求、选择 skills、协调执行？

有三种方案：

方案一：直接使用 Claude Agent SDK

最直接的方式：用 Anthropic 官方的 Agent SDK 来构建你的系统。

- 把你的 skills 改造成 SDK 能识别的格式

- 用 SDK 提供的 Agent 作为编排层

- 你的工具（生成图片、发布公众号）封装成 Tools 或 MCP Server

- 通过 API 或 Web 界面暴露给用户

优点：官方支持，功能完整，有 Subagents、上下文管理、工具调用等能力。

缺点：需要学习 SDK 的使用方式，有一定改造成本。

适合场景：skills 已经很成熟，想快速上线，追求长期稳定。

方案二：自建轻量级编排层

如果你的 skills 不太复杂，可以自己实现一个简化版的编排层。

- 用 Anthropic API 创建主 Agent

- 通过精心设计的 prompt，让它理解你的 skills 体系

- 主 Agent 根据用户需求，决定调用哪些工具（你的 skills）

- 工具调用通过 Anthropic 的 tool use 功能实现

优点：轻量、灵活、完全可控。

缺点：需要自己处理上下文管理、错误处理、Subagent 派发等复杂逻辑。

适合场景：快速验证想法，skills 还在迭代，需要高度灵活性。

方案三：基于 MCP 协议

把你的每个 skill 封装成独立的 MCP Server，用支持 MCP 的 Agent 来调用。

- 每个 skill 是一个 MCP Server（标准化接口）

- 主 Agent 通过 MCP 协议调用这些 skills

- 可以和其他支持 MCP 的系统互通

优点：标准化、可复用、生态丰富。

缺点：需要运行多个服务进程，架构相对重。

适合场景：构建开放生态，让其他人也能用你的 skills，追求标准化。

方案一实施指南

让我详细说说方案一的实施步骤。

第一步：改造 Skills

你现在的 skills 是为 Claude Code 设计的 Markdown 文件。要用 Agent SDK，需要把它们转换成 SDK 能理解的格式。

改造重点：

-Skills 变成 System Prompt：你的 skill 文件内容会成为 Agent 的 system prompt 的一部分，告诉 Agent 该如何工作。

-工具函数变成 Tools：你的"生成图片"、"发布公众号"等能力，需要封装成 SDK 的 Tools 格式，让 Agent 可以调用。

-触发逻辑变成编排逻辑：原来 Claude Code 自动触发 skills，现在你需要在主 Agent 的 prompt 中定义"什么情况下用哪个 skill"。

第二步：搭建基础架构

你需要准备的环境：

- 安装 Claude Agent SDK（Python 版本）

- 准备一个工作目录（作为 Agent 的文件系统）

- 配置 Anthropic API Key

- 搭建 Web 服务（如 FastAPI）作为用户接口

核心组件：

-主 Agent：负责理解用户需求、选择 skills、协调执行

-Tools 注册表：存放你所有的工具函数（生成图片、发布公众号等）

-Skills 加载器：读取你的 skill 文件，转换成 prompt

-上下文管理器：保存对话历史和中间结果

第三步：封装工具函数

你的每个能力都要变成一个 Tool：

- `generate_image`：调用图片生成 API

- `publish_to_wechat`：调用公众号 API

- `fetch_url_content`：抓取网页内容

- `create_podcast`：生成播客

Tool 的定义包括：名称和描述（让 Agent 知道这个工具是干什么的）、输入参数（需要什么信息）、执行逻辑（实际调用你的 API）。

第四步：实现编排逻辑

主 Agent 的核心 Prompt 设计：你需要告诉主 Agent：

- 你有哪些 skills 可用（写文章、生成图片、发布公众号等）

- 每个 skill 的使用场景和流程

- 如何组合使用这些 skills（比如：写完文章 → 生成配图 → 发布）

- 什么时候需要派发 Subagent

关键点：主 Agent 要能理解用户的意图，自动选择合适的 skills 组合。

第五步：暴露 Web/API 接口

用户通过 Web 或 API 访问：

- 用户发送请求："帮我写一篇关于 AI 的文章并发布到公众号"

- 你的 Web 服务接收请求，传递给主 Agent

- 主 Agent 执行整个流程（调用 skills、派发 Subagents、使用 Tools）

- 返回结果给用户

关键点：你需要管理会话状态，让用户可以多轮对话（比如 Agent 问"目标读者是谁"，用户回答后继续）。

从困惑到清晰

这篇文章从一个实际困惑出发：我在 Claude Code 中构建了丰富的 skills 生态，但如何让它们脱离 Claude Code 环境，实现自动化和开放使用？

答案的关键在于理解 Claude Agent SDK 的架构：

-三层架构：用户层接收需求，编排层做决策，执行层干活。

-三个角色：Skills 定义流程，Agent 执行调度，Subagents 完成任务。

理解了这些，解耦的路径就清晰了：重建编排层，让主 Agent 能够在 Web/API 环境中调度你的 skills。

三种方案的选择：

-方案一（Claude Agent SDK）：适合 skills 成熟、追求稳定的场景。改造成本有，但长期最可靠。

-方案二（自建轻量级）：适合快速验证、灵活迭代的场景。开发自由度高，但需要自己处理复杂逻辑。

-方案三（MCP 协议）：适合构建开放生态、追求标准化的场景。未来趋势，但架构相对重。

无论选择哪种方案，核心都是：

-Skills 是知识：定义工作流程和最佳实践

-Agent 是大脑：理解需求、做决策、协调资源

-Tools 是手脚：执行具体操作

-编排层是关键：这是从 Claude Code 解耦的核心挑战

从 Claude Code 的"温室"走出来，虽然需要自己搭建更多基础设施，但换来的是真正的自由：你的 skills 可以被任何人使用，可以通过 API 自动化调用，可以和其他系统无缝集成。这才是 AI Agent 技能体系的终极形态。