Agent Skills 实战：用 SKILL.md 管理 Claude 的 Context Window 与 MCP 调用

1. 为什么你的 Claude 越用越“健忘”Context Window 与 MCP 调用的真实冲突如果你最近在 Claude Code 或 Claude Desktop 里挂了三五个 MCP Server又习惯把项目规范、接口文档、代码风格一股脑塞进系统提示词大概率会遇到一个很具体的现象前几轮对话还挺聪明聊到第十轮左右它开始忘记你半小时前强调过的命名规则或者把已经调用过的 MCP 工具又调一遍。这不是模型变笨了而是 Context Window 被塞满了。Context Window 可以理解成 Claude 的“工作台面”。台面就这么大你放的东西越多它能同时盯住的就越少。传统做法是把所有规则、所有工具描述、所有参考资料都写进系统提示词结果是每次请求都要把这些内容重新送进上下文token 消耗高而且真正需要精细推理时留给“思考”的空间被挤没了。Agent Skills 想解决的就是这件事。它把能力拆成一个个独立的技能包每个技能包的核心是一个SKILL.md文件。Claude 启动时只加载每个技能的元数据name description大概 100 tokens 左右相当于只看“目录”。只有当你的请求真的匹配某个技能时它才会去读SKILL.md的正文再按需读取脚本和参考文档。这套机制叫渐进式披露本质上是把 Context Window 当成稀缺资源来管理。而 MCP 解决的是另一个维度的问题让 Claude 能调用外部工具和服务。MCP 的痛点在于每个 Server 的工具描述都会占用上下文挂多了同样会挤爆窗口。所以真正合理的架构是用 Skills 管理“知识和流程”用 MCP 管理“外部动作”两者配合而不是把所有东西都堆进提示词。这篇文章面向的是已经在用 Claude Code、Cline 或者自建 Agent 的开发者。我会给出可直接复制的SKILL.md模板、MCP 配置片段以及验证技能加载和上下文消耗的具体命令。你不需要从头理解 Anthropic 的规范文档跟着做就能跑起来。先说清楚一个边界Skills 不是让 Claude 替代你的编辑器也不是什么黑魔法。它就是一个 Markdown 文件加一套目录约定把“什么时候用什么知识”这件事工程化。理解这一点后面的配置就不会觉得神秘。2. TaoToken 前置准备Base URL、API Key 与 Model ID 三件套在写SKILL.md之前得先让 Claude 能稳定跑起来。如果你用的是官方直连网络和额度问题会频繁打断调试节奏。我自己的做法是通过 TaoToken 这类兼容 Anthropic 协议的中转服务来统一管理请求好处是 Base URL、Key、Model ID 三件套配一次Claude Code、Cline、Codex 都能复用。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个新的 API Key复制出来。这个 Key 只在创建时完整显示一次建议直接存进密码管理器。Base URL 用https://taotoken.net/api注意这里不加任何查询参数。Model ID 根据你的场景选做 Agent Skills 调试我一般用claude-sonnet-4-5-20250929这类带日期的稳定版本避免行为漂移。如果你用的是 Claude Code配置写在~/.claude/settings.json里。这个文件是 Claude Code 读取模型和端点配置的地方格式如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929 } }注意ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY的区别。Claude Code 走的是AUTH_TOKEN这条路径如果你只填了API_KEY可能会遇到 401。这是我在排查时踩过的坑后面第五节会详细说。如果你用的是 Cline 或者 Roo Code 这类 VS Code 插件配置在插件的设置面板里选择 “Anthropic” 作为 Provider然后填 Base URL、API Key、Model ID。Cline 的 MCP 配置是单独的cline_mcp_settings.json路径通常在~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/macOS或%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\Windows。如果你用的是 Codex配置在~/.codex/auth.json格式是{ OPENAI_API_KEY: sk-你的TaoToken密钥, OPENAI_BASE_URL: https://taotoken.net/api }这里有个细节Codex 默认走 OpenAI 协议而 TaoToken 同时兼容 Anthropic 和 OpenAI 两套接口。如果你在 Codex 里调 Claude 模型需要确认端点路径是/v1/chat/completions还是/v1/messages。实测下来Codex 用 OpenAI 兼容模式更顺Model ID 填claude-sonnet-4-5-20250929也能正常返回。配好之后先用一条最简单的请求验证连通性curl https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5-20250929, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回里能看到content字段且文本是 “OK”说明三件套没问题。这一步别跳过后面 Skills 加载失败时你至少能确定不是网络层的问题。关于 Coding Plan如果你打算长期跑 Agent 任务比如让 Claude 自动重构代码、批量处理文档按量计费可能会比预期高。TaoToken 的 Coding Plan 是包月形式适合高频调用场景具体额度可以在 https://taotoken.net/coding-plan 看。我自己的用法是调试阶段用按量稳定跑批任务时切到 Coding Plan。3. 可复制配置SKILL.md 模板与 MCP 调用片段现在进入核心部分。一个 Skill 的最小结构就是一个目录加一个SKILL.mdmy-skill/ └── SKILL.md完整结构会长这样my-skill/ ├── SKILL.md ├── scripts/ │ └── process.py ├── references/ │ └── api-spec.md └── assets/ └── template.htmlSKILL.md分两段开头的 YAML 元数据和下面的 Markdown 正文。元数据里name和description是必填的description尤其重要因为 Claude 就是靠它判断“这个请求要不要用这个技能”。下面是一个可以直接复制的模板我把它设计成“Python 代码审查”技能--- name: python-code-review description: 当用户要求审查、重构或编写 Python 代码时使用。检查命名规范、类型注解、异常处理和测试覆盖。 allowed-tools: Read, Grep, Bash --- # Python 代码审查技能 ## 指令 1. 检查所有内部辅助函数是否以 _internal_ 前缀命名。 2. 检查函数是否有类型注解缺失时给出补充建议。 3. 检查异常处理是否捕获了具体异常类型禁止裸 except:。 4. 检查是否有对应的单元测试文件没有则提示用户。 ## 工作流程 1. 先用 Grep 找到目标文件。 2. 用 Read 读取文件内容。 3. 按上述四条逐项检查输出问题列表。 4. 如果用户要求修复生成修改后的代码块。 ## 参考示例 正确 python def _internal_calculate_risk(score: int) - float: try: return score / 100.0 except ZeroDivisionError: return 0.0错误def _calculate_risk(score): try: return score / 100.0 except: return 0.0注意事项不要自动修改文件只输出建议。如果项目有pyproject.toml读取其中的 lint 配置作为补充规则。把这个文件放到项目的 .claude/skills/python-code-review/SKILL.mdClaude Code 启动时会自动扫描。 接下来是 MCP 配置。假设你要挂一个文件系统 MCP Server让 Claude 能读写指定目录。Claude Desktop 的配置在 ~/Library/Application Support/Claude/claude_desktop_config.jsonmacOSClaude Code 的 MCP 配置在 ~/.claude.json 或项目级 .mcp.json。 json { mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects ] }, fetch: { command: npx, args: [-y, modelcontextprotocol/server-fetch] } } }这里的关键点是MCP Server 的工具描述也会占用 Context Window。如果你挂了 10 个 Server每个 Server 暴露 5 个工具光工具描述就可能吃掉几千 tokens。所以我的建议是只挂当前任务真正需要的 Server用完就注释掉。Skills 和 MCP 的配合方式是这样的在SKILL.md里通过allowed-tools声明这个技能允许调用哪些工具然后在正文里写清楚“什么情况下调用哪个 MCP 工具”。比如## 数据获取流程 1. 如果需要读取本地文件使用 filesystem MCP 的 read_file 工具。 2. 如果需要获取网页内容使用 fetch MCP 的 fetch 工具。 3. 获取到的内容先摘要再决定是否写入上下文。这样 Claude 在加载这个技能时就知道工具边界在哪不会乱调。还有一个进阶用法context: fork。在元数据里加上这一行技能会在独立的子上下文中执行不污染主对话的 Context Window。适合那种“读一大堆文档然后只返回结论”的场景。--- name: doc-summarizer description: 当用户要求总结长文档时使用。 context: fork agent: general-purpose ---agent字段指定 fork 时用哪个子代理。这个配置在 Claude Code 里生效Claude Desktop 目前支持有限。4. 验证请求确认技能加载与上下文消耗配置写完不代表生效。你需要一套验证流程确认三件事技能被扫描到了、请求匹配时被加载了、上下文消耗在预期范围内。第一步检查技能目录结构。在项目根目录执行find .claude/skills -name SKILL.md -exec echo --- {} --- \; -exec head -5 {} \;这条命令会列出所有SKILL.md文件并打印前 5 行你能快速确认 YAML 元数据格式对不对。如果name或description缺失Claude 会跳过这个技能而且不会报错这是最容易踩的坑。第二步启动 Claude Code 并观察加载日志claude --debug--debug会输出技能扫描过程。你应该能看到类似Loaded skill: python-code-review的行。如果没有检查目录层级是.claude/skills/技能名/SKILL.md不是.claude/skills/SKILL.md。多一层少一层都不行。第三步发一个能触发技能的请求帮我审查 src/utils.py 里的代码如果技能生效Claude 会先调用 Read 工具读取文件然后按SKILL.md里的四条规则逐项检查。你可以在输出里看到它引用了“内部辅助函数命名”这类规则说明正文被加载了。第四步量化上下文消耗。Claude Code 里可以用/cost命令查看当前会话的 token 使用情况。更精确的做法是在请求前后对比# 记录初始 token claude -p 当前上下文使用了多少 token --output-format json | jq .usage实测下来一个只有元数据的技能常驻开销约 100 tokens。加载正文后根据正文长度增加 500 到 5000 tokens 不等。如果你发现某个技能一加载就吃掉 8000 tokens说明正文写太长了该拆到references/里按需读取。第五步验证 MCP 工具是否可用。在 Claude Code 里输入列出当前可用的 MCP 工具它会返回所有已连接 Server 的工具列表。如果某个 Server 没出现检查.mcp.json的 JSON 格式以及npx命令是否能在终端里独立跑通。常见问题是 Node 版本太低modelcontextprotocol/server-filesystem需要 Node 18 以上。第六步做一个上下文压力测试。连续发 10 轮对话每轮都涉及不同的技能然后用/cost看总消耗。如果第 10 轮的响应明显变慢或开始遗忘早期规则说明 Context Window 接近上限。这时候的优化方向是把不常用的技能从项目目录移到全局目录或者给技能加context: fork。我试过在一个中型项目里挂 6 个技能加 3 个 MCP Server初始上下文约 1200 tokens跑 20 轮后涨到 15000 左右。把其中 3 个低频技能改成 fork 模式后同样 20 轮只涨到 9000。这个差距在长会话里非常明显。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。你在配 Skills 和 MCP 的过程中大概率会遇到下面几类问题。401 Unauthorized这是最常见的。表现是请求直接返回 401Claude Code 里提示authentication_error。原因通常有三个Key 填错、Base URL 带了多余路径、或者用了ANTHROPIC_API_KEY而不是ANTHROPIC_AUTH_TOKEN。排查顺序先用第 2 节的 curl 命令独立测试 Key 是否有效。如果 curl 能通但 Claude Code 不通检查settings.json里的字段名。Claude Code 读的是ANTHROPIC_AUTH_TOKEN不是ANTHROPIC_API_KEY。另外 Base URL 必须是https://taotoken.net/api结尾不要加/v1Claude Code 会自己拼路径。local proxy failed这个报错通常出现在 MCP Server 启动阶段。表现是 Claude 提示MCP server filesystem failed to start: local proxy failed。原因是npx命令在 Claude 的运行环境里找不到或者网络问题导致包下载失败。解决办法先在终端里手动跑一遍npx -y modelcontextprotocol/server-filesystem /你的路径确认能启动。如果终端能跑但 Claude 里不行把command从npx改成绝对路径比如/usr/local/bin/npx。Windows 上则是C:\\Program Files\\nodejs\\npx.cmd。reading choices of undefined这个报错一般出现在用 OpenAI 兼容协议调 Claude 模型时。表现是返回体里没有choices字段代码里访问response.choices[0]就崩了。原因是端点返回的是 Anthropic 格式content数组而你的代码按 OpenAI 格式解析。解决方式有两种要么把请求打到/v1/chat/completions走 OpenAI 兼容层要么改代码解析content字段。如果你用的是 Cline 这类插件在 Provider 设置里选对协议就行。Codex 的auth.json里如果同时配了OPENAI_BASE_URL和 Anthropic 端点容易混建议只保留一套。OAuth 相关报错Claude Code 某些版本会尝试 OAuth 流程报OAuth token exchange failed。如果你用的是 API Key 模式不需要 OAuth。检查settings.json里有没有残留的oauth字段删掉。另外确认没有设置CLAUDE_CODE_USE_OAUTH这类环境变量。技能不生效没有报错但 Claude 就是不按SKILL.md里的规则来。九成是description写得太模糊。description要写清楚“什么时候用”而不是“这是什么”。对比一下差的写法description: Python 代码审查工具好的写法description: 当用户要求审查、重构或编写 Python 代码时使用。检查命名规范、类型注解、异常处理和测试覆盖。后者包含了触发场景和具体检查项Claude 匹配得更准。MCP 工具调用超时表现是 Claude 说“正在调用工具”然后卡住。原因是 MCP Server 的响应时间超过了 Claude 的等待阈值。排查方法是看 Server 的日志通常在~/Library/Logs/Claude/mcp-server-xxx.log。如果是网络类工具比如 fetch检查目标 URL 是否可达。如果是文件系统工具检查路径权限。上下文消耗异常高用/cost发现每轮消耗远超预期。检查是不是某个SKILL.md正文写了几千字。正文建议控制在 5000 tokens 以内超出的内容拆到references/目录在正文里用相对路径引用比如“详细 API 规范见references/api-spec.md”。Claude 只会在需要时读取那个文件。6. 把 Skills 和 MCP 用成一套工程化流程走到这里你已经有了可运行的SKILL.md、配好的 MCP Server、以及一套验证和排障方法。最后说几个我在实际项目里沉淀下来的用法。第一技能目录按“领域”分不按“工具”分。比如code-review、doc-writing、data-analysis各一个目录而不是read-tool、grep-tool这种。因为 Claude 匹配的是任务意图不是工具名。第二description里带上“反触发”条件。比如“当用户要求审查 Python 代码时使用不适用于 JavaScript 或 TypeScript”。这样能减少误触发省上下文。第三MCP Server 按需挂载。日常开发只挂 filesystem 和 git需要抓网页时临时加 fetch用完注释掉。Claude Code 支持在.mcp.json里用注释语法JSON5临时禁用 Server。第四长任务用context: fork。凡是“读大量资料然后输出结论”的技能都加 fork。主对话只保留结论中间过程不占窗口。第五定期用/cost做基线对比。我一般每周跑一次标准测试会话记录 token 消耗。如果某周突然涨了 30%说明新加的技能或 MCP 有问题及时排查。如果你还没配好 Key回到 https://taotoken.net/api-keys 拿一个然后按第 2 节的 JSON 片段填进对应文件。接入文档在 https://taotoken.net/doc 里面有各客户端的详细步骤。想先感受一下模型对话效果可以直接用 https://taotoken.net/chat 。长期跑 Agent 任务的话Coding Plan 在 https://taotoken.net/coding-plan 。最后一步把你项目里最常用的那条规则写成SKILL.md放到.claude/skills/下启动 Claude Code发一个能触发它的请求。看到它按你写的流程执行这套机制就算真正跑通了。