1. 从一次抓包说起Agent Skill 到底藏在 HTTP 的哪一层很多人第一次接触 Agent Skill会下意识以为它是模型协议里的一个新字段就像tools、tool_choice那样服务端能直接识别。我一开始也这么想直到把 Cline 接上 TaoToken 统一 Key 通道用抓包工具把/v1/chat/completions的请求体完整 dump 下来才发现请求里根本没有skill这个键。Agent Skill 能做什么简单说它让模型在需要时自己去读一份技能说明书然后按说明书里的步骤调用已有工具。它适合谁适合已经在用 Cline、Claude Code、CC Switch 这类编码 Agent想把重复流程比如拉取网页正文、跑固定脚本、按模板生成报告沉淀成可复用能力的人。关键结论先放这里Skill 不是协议层概念而是应用层抽象。它最终被编译成三样东西——注入到system消息里的技能摘要、预先注册好的tools数组、以及多轮tool_calls循环。模型看到的永远只是标准的 OpenAI 兼容结构Skill 的全部魔法发生在客户端拼装请求体的那一刻。这篇就按声明 → 请求体 → 抓包验证的顺序把 Cline / CC Switch 接入 TaoToken 的配置骨架拆开再对照抓包结果确认 Skill 字段的真实落点。2. TaoToken 前置统一 Key 通道与接入骨架TaoToken 在这里扮演的角色是统一 Key 通道Cline、CC Switch、Claude Code 这些客户端各自维护一份配置但都指向同一个 API 入口Key 只在一处管理。这样做的直接好处是抓包时你只需要盯一个 host请求体结构也统一排查 Skill 承载链路会清爽很多。先把入口记清楚官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Basehttps://taotoken.net/apiAPI Base 不带任何查询参数客户端里填的就是这个裸地址后面由客户端自己拼/v1/chat/completions。Key 的申请在控制台的 API Keys 页面完成拿到后先别急着写进配置文件建议用环境变量过渡避免明文散落在多个 settings 里。注意TaoToken 是合规的 API 聚合入口配置时只填官方给的 Base 地址即可不要自行拼接任何非官方域名。模型对话入口可以用来快速验证 Key 是否可用https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite3. 可复制配置settings.json 与 config.toml 骨架Cline 走的是 VS Code 扩展配置核心在settings.jsonCC Switch 走的是config.toml。两者字段名不同但承载 Skill 的逻辑一致system里放技能摘要tools由客户端注册Skill 文件本身通过 Read 工具按需加载。3.1 Cline 的 settings.json 骨架{ cline.apiProvider: openai, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiApiKey: ${env:TAOTOKEN_API_KEY}, cline.openAiModelId: claude-sonnet-4-5, cline.customInstructions: When a skill is relevant, read its SKILL.md IMMEDIATELY as your first action, then follow the steps inside., cline.skills.scanPaths: [ .cline/skills, .agents/skills ] }这里有两个点值得展开。cline.customInstructions会被拼进system消息它承担的就是技能发现的提示职责——告诉模型你有技能手册可查。cline.skills.scanPaths是客户端启动时扫描的目录扫描结果只取每个SKILL.md的 frontmatternamedescription正文不读这就是所谓的渐进式加载省 token。3.2 CC Switch 的 config.toml 骨架[provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet-4-5 [agent] system_prompt_file ./prompts/agent_system.md skill_scan_paths [./skills, ./.agents/skills] tool_choice auto max_tool_rounds 12 [agent.tools] enabled [Read, Shell, Write]max_tool_rounds这个参数很关键。Skill 的加载和执行天然是多轮的第一轮模型决定读 SKILL.md第二轮拿到正文后决定执行核心命令第三轮才产出最终回答。轮数上限设太小Skill 会在中途被截断设太大又容易在异常时打转。实测 12 轮对大多数单技能流程够用。3.3 SKILL.md 的 frontmatter 写法--- name: mp-read description: - Extract plain text from web articles using a headless browser. Use when the user wants to read, fetch, extract, or summarize a URL. --- ## Prerequisites Check 确认本地已安装 mp-read 命令并准备好 cookie.txt。 ## Usage mp-read cookie-file urldescription是唯一会被注入system的部分所以要写得像触发条件而不是功能简介——把用户可能说的关键词塞进去模型匹配命中率会明显提升。4. 抓包验证Skill 字段在请求流中的实际落点配置好之后把 Cline 的请求代理到本地抓包端口发一句帮我读一下这篇文章https://example.com/post/123然后看请求体。4.1 第一轮请求只有摘要没有正文{ model: claude-sonnet-4-5, messages: [ { role: system, content: You are an AI coding assistant...\n\navailable_skills\nagent_skill fullPath\/path/to/mp-read/SKILL.md\\nExtract plain text from web articles...\n/agent_skill\n/available_skills\n\nWhen a skill is relevant, read its SKILL.md IMMEDIATELY as your first action. }, { role: user, content: 帮我读一下这篇文章https://example.com/post/123 } ], tools: [ { type: function, function: { name: Read, description: Reads a file from the local filesystem..., parameters: { type: object, properties: { path: { type: string } }, required: [path] } } } ], tool_choice: auto }抓包结果印证了前面的判断请求体里没有skill字段。Skill 的存在感只体现在system的available_skills块里而且只有name和descriptionSKILL.md正文一个字都没进来。4.2 第二轮请求模型主动读 SKILL.md模型看到用户消息里的 URL匹配到mp-read的描述于是返回一个tool_calls{ choices: [ { message: { role: assistant, content: null, tool_calls: [ { id: call_abc123, type: function, function: { name: Read, arguments: {\path\: \/path/to/mp-read/SKILL.md\} } } ] }, finish_reason: tool_calls } ] }客户端在本地执行Read把文件内容作为role: tool消息追加进messages再发下一轮。到这一步SKILL.md全文才真正进入上下文窗口。这就是 Skill 的加载动作——本质是模型自己发起的一次 Read 调用协议层完全无感。4.3 第三轮请求按 Skill 指令执行核心命令模型读完SKILL.md按里面的Usage章节构造 Shell 调用{ role: assistant, tool_calls: [ { id: call_jkl012, type: function, function: { name: Shell, arguments: {\command\: \mp-read cookie.txt https://example.com/post/123\, \block_until_ms\: 120000} } } ] }注意block_until_ms: 120000这个值——它不是客户端默认的而是模型从SKILL.md里学来的。这说明 Skill 的指令确实通过tool消息影响了后续所有轮次的参数构造。4.4 承载链路对照表Skill 概念协议层落点触发方技能发现扫描目录无纯客户端行为客户端启动时技能摘要注入messages[0].role system文本客户端拼装技能加载读正文tool_calls: [Read(SKILL.md)]模型决策技能指令执行后续tool_calls的参数模型按正文构造渐进式加载摘要先入 system正文按需 Read客户端 模型协作5. 本篇常见错排查5.1 抓包看不到available_skills块先确认skill_scan_paths指向的目录真实存在且每个技能目录下有SKILL.md。扫描是启动时做的改完配置要重启客户端。另外检查customInstructions是否被覆盖——有些客户端会用自己的默认 system prompt 顶掉自定义部分。5.2 模型不读 SKILL.md直接瞎答大概率是description写得太功能化。把描述改成触发条件式比如把网页正文提取工具改成当用户想读取、抓取、总结某个 URL 时使用。模型匹配的是语义不是功能名。5.3 请求报 401 或 404401 通常是 Key 没读到检查环境变量TAOTOKEN_API_KEY是否在当前 shell 生效404 多半是 Base 地址多写了/v1。TaoToken 的 Base 就是https://taotoken.net/api/v1/chat/completions由客户端拼。Key 管理在控制台 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite5.4 Skill 执行到一半被截断看max_tool_rounds。单技能流程一般 3 到 5 轮但如果 Skill 内部还有前置检查比如先which再Read再执行轮数会上去。设 12 轮比较稳同时留意block_until_ms是否够长长任务给到 120000 毫秒以上。5.5 多技能互相干扰扫描路径里技能太多时system里的摘要块会膨胀模型匹配精度下降。建议按项目拆分扫描路径而不是把所有技能堆在一个全局目录。CC Switch 里可以用多个 profile 隔离。6. 把 Skill 链路接进长期编码流单次抓包验证只能证明链路通真正要跑长期编码或 Agent 任务还得把 Key 通道、模型选择、轮数上限这些参数固化下来。Coding Plan 适合把 Skill 流程沉淀成日常开发的一部分https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite接入文档里有完整的字段说明和示例配置遇到协议层细节可以直接对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你用的是 Claude Code 这类客户端配置思路和 Cline 一致只是配置文件位置不同参考https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite最后留一个我踩过的坑改完SKILL.md的description后一定要重启客户端再抓包。扫描结果有缓存不重启的话system里还是旧摘要你会以为改动没生效白白排查半天。