Anthropic 官方揭秘：Agent 和 Skills 如何配合工作？来自官方的机制拆解｜TaoToken 统一 Key 接入 Claude Code 实战

1. 从一次“Agent 不听话”说起Skills 到底解决了什么如果你最近在折腾 Claude Code大概率遇到过这种场景你让它“帮我做一份竞品分析”它洋洋洒洒写了一大段但维度不对、格式不对、数据来源也不对。你心里想的是“这货明明很聪明怎么就是不按套路出牌”。问题不在模型智商而在于它缺一份“专业攻略”。Anthropic 官方在《Building Agents with Skills: Equipping Agents for Specialized Work》里把这件事讲透了Agent 有推理能力但没有领域经验。就像数学天才不一定能报税Claude 再强也不知道你们团队做竞品分析时习惯先看哪几个维度、数据从哪来、最后输出到哪个文档系统。Skills 就是把这些“隐性经验”打包成可加载的文件让 Agent 按攻略行事。这篇文章不聊虚的直接拆解官方那套四层协同架构然后落到实操怎么在本地用 Claude Code 把 Skills 跑起来怎么通过 TaoToken 统一 Key 接入最后给出 settings.json 和 config.toml 的可复制骨架以及连通性验证动作。适合已经在用 Claude Code、想搞明白 Agent 和 Skills 配合机制、并且希望有一套稳定 API 通道的开发者。2. 官方四层架构拆解Agent Loop、Runtime、MCP、Skills 各干什么Anthropic 把 Agent 的工作机制拆成四层理解这四层后面配环境才不会懵。第一层是 Agent Loop也就是推理循环。它负责理解需求、规划下一步、做决策。你可以把它想成一个不断“观察→思考→行动”的循环体。第二层是 Agent Runtime负责执行 Loop 规划出来的动作跑代码、调工具、读写文件。第三层是 MCP ServersModel Context Protocol 的缩写是 Agent 连接外部世界的桥梁数据库、API、文件系统、Notion、Slack 都通过 MCP 接入。第四层就是 Skills Library装着某个领域的专业知识告诉 Agent 这个任务该怎么做、有哪些步骤、注意什么。四层协同的逻辑是Skills 提供专业指导Agent Loop 根据指导做决策Agent Runtime 执行具体操作MCP 连接外部工具和数据。缺一层都跑不通。光有 Skills 没有 MCP攻略落不了地光有 MCP 没有 SkillsAgent 就是个无头苍蝇工具一堆但不知道先干啥。这里有个关键机制叫“渐进式披露”Progressive Disclosure。上下文窗口有限不能把所有技能一股脑塞进去。Anthropic 的做法分三层加载第一层是 Metadata约 50 个 token只有技能名字、简介、适用场景Agent 先扫一眼判断哪个可能有用第二层是 SKILL.md约 500 个 tokenAgent 觉得某个技能有用才读这个文件了解具体怎么做第三层是 References2000 个 token 以上详细文档、模板、代码示例需要深入时才加载。就像查字典先看目录再翻到那一页细读不会把整本字典背下来。3. 前置准备TaoToken 统一 Key 与 Claude Code 环境要把这套机制在本地跑起来你需要两样东西一个能稳定调用的 API 通道以及 Claude Code 的本地配置。这里用 TaoToken 做统一 Key 接入官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。先去控制台创建一个 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。创建完把 Key 复制出来后面配置里要用。如果你还没决定用哪个模型可以先到模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 试一下连通性确认 Key 能用再往下走。Claude Code 这边确保你已经装好 CLI 工具。如果你还没装官方文档里有安装步骤这里不展开。重点是把 API 通道指向 TaoToken而不是默认的 Anthropic 端点。这一步做完后面 Skills 加载和 MCP 调用都会走这条通道。4. 可复制配置settings.json 与 config.toml 骨架Claude Code 的配置分两块settings.json 管项目级行为config.toml 管模型和 API 通道。下面给出可复制骨架你按自己环境改路径和 Key。先看 settings.json放在项目根目录的 .claude 文件夹下{ skills: { enabled: true, libraryPath: ./.claude/skills, progressiveDisclosure: { metadataOnly: true, maxSkillTokens: 500, maxReferenceTokens: 2000 } }, mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./workspace] }, web-search: { command: npx, args: [-y, modelcontextprotocol/server-brave-search], env: { BRAVE_API_KEY: 你的搜索Key } } }, agent: { loop: { maxIterations: 15, timeoutMs: 120000 }, runtime: { allowCodeExecution: true, allowFileWrite: true } } }这里 skills.libraryPath 指向你放 SKILL.md 的目录progressiveDisclosure 三个参数对应官方那三层加载机制。mcpServers 里配了两个常用 MCPfilesystem 让 Agent 能读写工作区文件web-search 让 Agent 能搜公开信息。agent.loop 控制推理循环的最大迭代次数和超时agent.runtime 控制是否允许执行代码和写文件。再看 config.toml放在用户目录的 .claude 文件夹下[api] provider taotoken base_url https://taotoken.net/api api_key 你的TaoToken Key model claude-sonnet-4-20250514 max_tokens 8192 temperature 0.7 [api.retry] max_attempts 3 backoff_ms 1000 [logging] level info output ./.claude/logsbase_url 指向 TaoToken 的 API 入口api_key 填你刚才在控制台创建的那个。model 按你实际用的填max_tokens 和 temperature 按需调。retry 段控制失败重试logging 段方便排障。两个文件配完目录结构大概是这样项目根/ ├── .claude/ │ ├── settings.json │ └── skills/ │ └── competitive-analysis/ │ └── SKILL.md └── workspace/SKILL.md 就是你的技能说明书里面写清楚这个技能叫什么、什么时候用、具体步骤是什么。比如竞品分析的 SKILL.md 可以写先确定分析维度产品功能、定价、用户评价从公开渠道收集数据整理成标准格式输出到 Notion。Agent 在 Metadata 阶段扫到这个名字和简介判断相关后才会读这个文件。5. 验证请求确认 Skills 被 Agent 正确调度配置写完先别急着跑复杂任务做一次最小连通性验证。打开终端进到项目目录启动 Claude Codeclaude --config ./.claude/settings.json启动后先问一个简单问题确认 API 通道通 列出当前可用的 skills如果配置正确Agent 会返回 skills 目录下扫描到的技能列表包括名字和简介。这一步验证的是 Metadata 层加载是否正常。接着验证 SKILL.md 是否被正确读取 用 competitive-analysis 技能帮我分析一下 Notion 和 Obsidian 的差异观察 Agent 的行为它应该先读取 SKILL.md然后按里面写的步骤走——确定维度、收集数据、整理格式。如果它直接开始瞎写说明 SKILL.md 没被加载回去检查 libraryPath 和文件命名。再验证 MCP 是否连通 用 filesystem 工具在 workspace 目录下创建一个 test.md写入 hello如果 workspace 下出现了 test.md说明 MCP Server 正常。如果报错检查 npx 是否可用、MCP Server 包是否装好。最后验证渐进式披露是否生效。你可以在 SKILL.md 里放一个 References 链接指向一个详细文档然后问一个需要深入的问题观察 Agent 是否只在需要时才加载那个文档。如果它一上来就把所有内容都读进来说明 progressiveDisclosure 配置没生效。6. 本篇常见错排查配置过程中最容易踩的几个坑这里集中说一下。第一个坑是 API Key 没生效。表现是启动后报 401 或 403。检查 config.toml 里 api_key 是否填对base_url 是否是 https://taotoken.net/api 注意不要多加斜杠或路径。如果 Key 刚创建确认没有复制错字符。第二个坑是 Skills 目录路径不对。表现是 Agent 说“没有可用技能”。检查 settings.json 里 libraryPath 是相对路径还是绝对路径相对路径是相对于项目根目录还是 .claude 目录。建议先用绝对路径测试确认能加载后再改相对路径。第三个坑是 MCP Server 启动失败。表现是调用工具时报“command not found”或超时。检查 npx 是否在 PATH 里MCP Server 包名是否正确。如果是网络问题导致 npx 拉包慢可以提前全局安装。第四个坑是渐进式披露没生效。表现是 Agent 一次性加载太多内容响应变慢。检查 progressiveDisclosure 三个参数是否写对metadataOnly 设为 true 时Agent 应该只先读 Metadata。如果 SKILL.md 文件本身太大也会导致加载慢建议控制在 500 token 左右。第五个坑是模型名写错。表现是 API 返回“model not found”。去 TaoToken 模型对话页面确认可用模型名填到 config.toml 的 model 字段。7. 下一步把 Skills 用进真实编码流配置跑通之后你可以开始把 Skills 用到真实场景里。比如给团队做一个“代码审查 Skill”里面写清楚审查维度、常见问题清单、输出格式然后让 Agent 在每次提交前自动跑一遍。或者做一个“API 文档生成 Skill”把接口定义、参数说明、示例代码的模板放进去Agent 就能按统一格式输出文档。如果你打算长期用 Claude Code 做编码和 Agent 任务可以看一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里面有适合长期编码场景的配置建议。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。Claude Code 相关的 Anthropic 配置参考在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeanthropicutm_campaignrewrite 。我自己的习惯是每做一个新类型的任务就先写一个 SKILL.md把步骤和注意事项固化下来。跑几次之后Agent 的行为会越来越稳定你也不用每次重复解释“我要什么格式”。这套机制的核心价值就在这把专业经验从人脑里搬到文件里让 Agent 能复用。