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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建密钥。注意密钥只显示一次复制后存到环境变量里别硬编码进代码。第二步配置环境变量。Linux 或 macOS 下写入 shell 配置文件export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥Windows PowerShell 用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的密钥第三步验证连通性。用 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.mdSKILL.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/apiKey 用环境变量ANTHROPIC_API_KEYModel ID 用claude-sonnet-4-20250514。MCP 服务器自己的凭证是独立的别和模型密钥混用。3.3 Subagents 的定义Subagent 是一个带独立上下文的执行单元定义时指定它能用的 Skills 和 Toolsname: feedback-analyzer description: 专门分析客户反馈的子智能体 skills: - customer-feedback-analysis tools: - read_file - write_file instructions: | 读取指定目录下的反馈文件 应用 customer-feedback-analysis 技能 输出结构化报告到 output.json主 Agent 通过 Task 工具派发任务给 SubagentSubagent 在独立上下文里跑完只把结果摘要返回。这样主上下文不会被中间过程污染。三者边界一句话总结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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要先验证模型效果去模型对话页面试几条指令地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后给一个实用技巧先把一个重复性任务写成 Skill跑通之后再考虑要不要拆 Subagent。很多人一上来就搞多 Agent结果调试成本远超收益。从单 Skill 起步按需扩展是最稳的路径。