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 Servers，Model Context Protocol 的缩写，是 Agent 连接外部世界的桥梁，数据库、API、文件系统、Notion、Slack 都通过 MCP 接入。第四层就是 Skills Library，装着某个领域的专业知识，告诉 Agent 这个任务该怎么做、有哪些步骤、注意什么。
四层协同的逻辑是：Skills 提供专业指导，Agent Loop 根据指导做决策，Agent Runtime 执行具体操作，MCP 连接外部工具和数据。缺一层都跑不通。光有 Skills 没有 MCP，攻略落不了地；光有 MCP 没有 Skills，Agent 就是个无头苍蝇，工具一堆但不知道先干啥。
这里有个关键机制叫“渐进式披露”（Progressive Disclosure）。上下文窗口有限，不能把所有技能一股脑塞进去。Anthropic 的做法分三层加载：第一层是 Metadata，约 50 个 token，只有技能名字、简介、适用场景，Agent 先扫一眼判断哪个可能有用；第二层是 SKILL.md，约 500 个 token，Agent 觉得某个技能有用才读这个文件，了解具体怎么做；第三层是 References，2000 个 token 以上，详细文档、模板、代码示例，需要深入时才加载。就像查字典，先看目录，再翻到那一页细读，不会把整本字典背下来。
3. 前置准备：TaoToken 统一 Key 与 Claude Code 环境
要把这套机制在本地跑起来，你需要两样东西：一个能稳定调用的 API 通道，以及 Claude Code 的本地配置。这里用 TaoToken 做统一 Key 接入，官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。
先去控制台创建一个 API Key，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite 。创建完把 Key 复制出来，后面配置里要用。如果你还没决定用哪个模型，可以先到模型对话页面 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 试一下连通性，确认 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 里配了两个常用 MCP：filesystem 让 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/logs"base_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 Code：
claude --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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite ，里面有适合长期编码场景的配置建议。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。Claude Code 相关的 Anthropic 配置参考在 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecodeanthropic&utm_campaign=rewrite 。
我自己的习惯是，每做一个新类型的任务，就先写一个 SKILL.md，把步骤和注意事项固化下来。跑几次之后，Agent 的行为会越来越稳定，你也不用每次重复解释“我要什么格式”。这套机制的核心价值就在这：把专业经验从人脑里搬到文件里，让 Agent 能复用。
