企业官网建设流程全解析

1. 为什么你的 Agent 越写越乱：从一次真实踩坑说起

如果你正在用 Claude 做自动化，大概率遇到过这种场景：一开始只是让模型读个文件、跑个脚本，几周之后项目里塞满了工具函数、提示词模板、外部 API 调用，改一处崩三处。我试过在一个客户洞察项目里同时堆了 20 多个工具定义，结果模型开始"忘记"关键指令，输出格式飘忽不定，排查半天才发现是上下文被工具描述挤爆了。

这就是 Claude Agent Skills 要解决的核心问题。简单说，Skills 是一套用 Markdown 加脚本封装"怎么做一件事"的标准格式，它让 Agent 按需加载工作流，而不是把所有能力一次性塞进上下文。MCP 则是连接外部系统的协议，负责"拿到数据"和"推出去"；Subagents 是独立上下文的执行单元，负责"并行干活"和"隔离污染"。三者不是替代关系，而是分层协作。

这篇内容适合三类人：正在做 Agent 技术选型、纠结该用哪种机制的开发者；已经上手 Skills 但搞不清和 MCP 边界的中级用户；以及想把预构建技能库落地到实际业务的团队。我会给出可复制的目录结构、配置片段和调用示例，每一步都配验证动作，让你判断什么时候该用哪种机制。全程围绕 Claude Agent Skills、MCP、Subagents 的职责边界展开，不空谈概念。

先说结论：Skills 管流程，MCP 管连接，Subagents 管执行，主 Agent 管编排。记住这句话，后面所有决策都从它推导。

2. 前置准备：用 TaoToken 打通 Claude Agent Skills 的调用链路

在动手写 Skill 之前，得先有一个能稳定调用 Claude 的入口。很多人在这一步卡住，要么是密钥管理混乱，要么是 Base URL 配错导致 401。我用 TaoToken 作为统一接入层，它兼容 Anthropic 的接口格式，配置简单，适合做 Skills 和 MCP 的调试底座。

第一步，去官网注册并拿到 API Key。地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台创建密钥。注意密钥只显示一次，复制后存到环境变量里，别硬编码进代码。

第二步，配置环境变量。Linux 或 macOS 下写入 shell 配置文件：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的密钥"

Windows PowerShell 用：

$env:ANTHROPIC_BASE_URL="https://taotoken.net/api" $env:ANTHROPIC_API_KEY="sk-你的密钥"

第三步，验证连通性。用 curl 发一个最小请求，确认返回正常：

curl https://taotoken.net/api/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "max_tokens": 64, "messages": [{"role": "user", "content": "回复 OK"}] }'

如果返回里能看到content字段和文本内容，说明链路通了。如果报 401，检查密钥是否有多余空格；如果报连接失败，确认 Base URL 没有多写斜杠。

这里有个关键点：Skills 本身是本地文件，不需要网络就能定义，但 Agent 执行 Skill 里的步骤时，往往要调用模型，所以模型入口必须先通。MCP 服务器则可能需要额外的外部服务凭证，那是另一层配置，别和模型密钥混在一起。

拿到 Key 之后，建议先去模型对话页面做一次交互测试，确认模型能正常响应，再进入 Skills 的目录搭建。这一步花五分钟，能省掉后面半小时的排障。

3. 可复制配置：Skills 目录结构、MCP 与 Subagents 三件套

这一节是全文最硬的部分，直接给可落地的配置。先讲 Skills 的目录结构，再讲 MCP 的 JSON 配置，最后讲 Subagents 的定义方式。三者放在一起对照，你就能看清边界。

3.1 Skills 的标准目录结构

一个 Skill 就是一个文件夹，核心是SKILL.md，可选带脚本和参考文档。结构如下：

~/.claude/skills/ └── customer-feedback-analysis/ ├── SKILL.md ├── scripts/ │ ├── clean_data.py │ └── sentiment.py └── references/ └── category_rules.md

SKILL.md的头部是 YAML 元数据，只有name和description会在会话开始时加载，正文按需加载。这是 Skills 省上下文的关键机制：

--- name: customer-feedback-analysis description: 分析客户反馈，提取情感倾向、主题分类和改进建议 version: 1.0.0 --- ## 分析流程 1. 读取反馈数据，清洗空值和重复项 2. 按情感分为正面、中性、负面三类 3. 提取主题：产品功能、用户体验、价格、客服 4. 按紧急程度排序 5. 输出结构化 JSON 报告 ## 输出格式 ```json { "total": 0, "sentiment": {"positive": 0, "neutral": 0, "negative": 0}, "topics": [], "actions": [] }

注意 `description` 要写清楚"什么时候用这个 Skill"，模型靠它判断是否加载。写得太模糊，模型就不会触发。 ### 3.2 MCP 的 JSON 配置 MCP 负责连接外部系统。以配置文件形式挂载，路径通常在 `~/.claude/mcp.json` 或项目根目录的 `.mcp.json`： ```json { "mcpServers": { "notion": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-notion"], "env": { "NOTION_API_TOKEN": "${NOTION_API_TOKEN}" } }, "slack": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-slack"], "env": { "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}" } } } }

三件套对照：Base URL 用https://taotoken.net/api，Key 用环境变量ANTHROPIC_API_KEY，Model ID 用claude-sonnet-4-20250514。MCP 服务器自己的凭证是独立的，别和模型密钥混用。

3.3 Subagents 的定义

Subagent 是一个带独立上下文的执行单元，定义时指定它能用的 Skills 和 Tools：

name: feedback-analyzer description: 专门分析客户反馈的子智能体 skills: - customer-feedback-analysis tools: - read_file - write_file instructions: | 读取指定目录下的反馈文件， 应用 customer-feedback-analysis 技能， 输出结构化报告到 output.json

主 Agent 通过 Task 工具派发任务给 Subagent，Subagent 在独立上下文里跑完，只把结果摘要返回。这样主上下文不会被中间过程污染。

三者边界一句话总结：Skills 是"怎么做"的说明书，MCP 是"连哪里"的插头，Subagents 是"谁来做"的工人。配置时各管各的，别把流程写进 MCP，也别把外部连接写进 Skill。

4. 逐项验证：从 Skill 加载到 Subagent 并行的成功结果

配置写完不算完，得逐项验证。这一节给出每一步的验证动作和预期结果，你照着做就能确认链路是否正常。

4.1 验证 Skill 是否被正确加载

启动 Claude Code 后，输入/skills查看已加载的技能列表。如果看到customer-feedback-analysis出现在列表里，说明元数据加载成功。如果没出现，检查目录是否在~/.claude/skills/下，以及SKILL.md的 YAML 头部格式是否正确，冒号后面要有空格。

然后发一条触发指令：

请用 customer-feedback-analysis 技能分析 data/feedback.csv

预期结果是模型先声明"我将加载该技能"，然后按 SKILL.md 里的流程逐步执行。如果模型直接开始瞎分析，说明description没写清楚触发条件。

4.2 验证 MCP 连接

输入/mcp查看已连接的服务器。正常状态下每个服务器显示为 connected。如果显示 failed，先单独跑一次服务器命令：

npx -y @modelcontextprotocol/server-notion

看报错信息。常见的是 token 没设置或权限不足。连接成功后，让模型调用一次：

从 Notion 读取数据库 xxx 的记录

预期返回记录列表。这一步通了，说明 MCP 层没问题。

4.3 验证 Subagent 并行执行

派发一个需要并行的任务：

并行分析 data/ 下的三个反馈文件，每个文件用一个 Subagent

预期结果是主 Agent 创建三个 Subagent，各自独立跑完，最后汇总。你可以在日志里看到三个独立的上下文，互不干扰。如果发现它们串行执行，检查框架是否支持并行 Task 调用。

4.4 完整链路验证

把三者串起来跑一次：MCP 从外部拉数据，Skill 定义分析流程，Subagent 并行执行。预期输出是一份结构化报告，同时通过 MCP 推送到目标系统。整个过程主上下文只保留最终结果，中间过程被隔离。

实测下来，这套组合能把一个原本需要 15 分钟串行处理的任务压到 5 分钟左右，而且输出格式稳定，不会因为上下文膨胀而漂移。

5. 常见报错排查：401、local proxy failed 与 reading choices

这一节对照真实报错，给出排查路径。这些坑我基本都踩过，按顺序查能快速定位。

5.1 401 Unauthorized

最常见。原因通常是密钥错误或没带上。检查三处：环境变量ANTHROPIC_API_KEY是否设置；请求头是否用x-api-key而不是Authorization；密钥是否有多余空格或换行。用echo $ANTHROPIC_API_KEY确认值正确。

如果用的是 TaoToken，确认 Base URL 是https://taotoken.net/api，不要多加/v1之外的路径。401 基本就是凭证问题，和 Skills 本身无关。

5.2 local proxy failed

这个报错通常出现在 MCP 服务器启动阶段。含义是本地代理进程没起来。排查步骤：先手动运行 MCP 命令看是否报错；检查npx是否能正常拉包；确认env里的变量都已设置。如果是网络问题导致 npx 拉不到包，换用本地已安装的包路径。

注意：这里说的代理是 MCP 服务器进程本身，不是网络代理。别混淆。

5.3 reading choices 报错

这个报错出现在模型返回格式不符合预期时，通常是 Skill 的输出格式定义和实际返回不一致。比如 SKILL.md 里要求返回 JSON，但模型返回了 Markdown。解决办法是在 Skill 里明确写"只返回 JSON，不要额外解释"，并在验证时检查返回结构。

如果报错信息里带choices字段，说明调用的是 OpenAI 格式的接口，但 Anthropic 格式不返回choices。检查 Base URL 是否指向了错误的端点。Anthropic 格式的返回是content数组，不是choices。

5.4 OAuth 相关报错

MCP 服务器如果走 OAuth 授权，token 过期会报错。重新走一次授权流程，或者用长期 token 替代。检查env里的 token 是否过期，刷新后重启 MCP 服务器。

5.5 Skill 不触发

模型不加载 Skill，八成是description写得太泛。改成具体的触发场景描述，比如"当用户要求分析客户反馈情感时使用"，而不是"分析数据"。描述越具体，触发越准。

排查顺序建议：先确认模型入口通（401 类），再确认 MCP 通（proxy 类），最后确认 Skill 逻辑（格式类）。分层排查，别一上来就改 Skill。

6. 技术选型决策与后续接入路径

讲完配置和排障，回到选型本身。给你一个可以直接用的决策框架。

需要访问外部数据或系统，用 MCP。数据处理有标准流程，MCP 加 Skills。没有外部依赖但有可重复流程，用 Skills。任务能独立完成且需要并行或隔离，加 Subagents。三者可以叠加，但别为了用而用。

成本上，Prompt 最低，Skills 次之，MCP 和 Subagents 依次升高。收益上，Skills 的复用性最高，MCP 提供持续数据能力，Subagents 提升效率。个人开发者从预构建 Skills 起步，团队建立统一命名和版本规范，企业再考虑平台化治理。

如果你要长期做编码类 Agent，建议直接上 Coding Plan，把 Skills 和 Subagents 的组合用起来，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。需要先验证模型效果，去模型对话页面试几条指令，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API Key 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

最后给一个实用技巧：先把一个重复性任务写成 Skill，跑通之后再考虑要不要拆 Subagent。很多人一上来就搞多 Agent，结果调试成本远超收益。从单 Skill 起步，按需扩展，是最稳的路径。