1. 为什么你的 SKILL.md 越写越像脚手架先说一个我观察到的现象很多人第一次接触 Agent Skill会下意识把它当成“超级提示词模板”。一个 SKILL.md 里塞进登录、下单、支付、退款全流程正文六百多行跑起来确实能工作但每次调用都要把全部内容灌进上下文改一个支付逻辑得从头翻到尾想单独复用登录步骤——拆不出来因为所有东西都耦合在一个文件里。这就是把 Skill 当脚手架用了。脚手架的特征是一次性搭起来、用完就拆、只服务于当前这一个任务。但 Skill 的设计意图恰恰相反它是可复用、可组合、可演进的能力单元。你读不懂 SKILL.md 的渐进式披露机制读不懂仓库目录为什么分成 scripts、references、assets就会一直停留在“写提示词”的阶段而不是“构建能力”。这篇面向的是用 Cline、CC Switch 这类工具接入 TaoToken 统一 Key 的开发者。我会把 SKILL.md 的最小结构、仓库目录的职责划分、以及接入 TaoToken 时 settings.json / config.toml 该怎么写全部拆成可复制的骨架。重点不是让你背格式而是让你理解为什么元数据要单独抽出来、为什么正文要精炼、为什么脚本和参考文档要分目录放。理解了这个你写出来的 Skill 才能被 Agent 自动发现、按需加载、跨任务复用。2. 接入前的准备TaoToken 统一 Key 与工具链在动手写 SKILL.md 之前先把接入层理顺。不管你用 Cline 还是 CC Switch核心都是让工具通过一个统一的 API Key 去调用模型而这个 Key 从 TaoToken 的控制台获取。TaoToken 在这里扮演的角色是统一入口你不需要为每个模型、每个工具单独配置一套凭证而是拿一个 Key在多个 Agent 工具里复用。这对 Skill 开发特别重要因为 Skill 本身是模型无关的能力封装接入层越统一你越能把精力放在 Skill 的结构设计上。具体操作路径是这样的先到控制台创建 API Key然后根据你用的工具选择对应的配置文件格式。Cline 走的是 settings.jsonCC Switch 走的是 config.toml两者字段名不同但语义一致——都是把 base_url 指向 TaoToken 的 API 地址把 api_key 填进去再指定默认模型。这里有个容易踩的坑很多人把 base_url 写成官网地址结果请求 404。API 地址和官网地址是两个东西配置里必须用https://taotoken.net/api不要带任何多余路径。另一个坑是 Key 的权限范围如果你在控制台创建 Key 时限制了模型白名单而 Skill 里指定的模型不在白名单内请求会被拒绝报错信息往往很模糊让人以为是 Skill 加载失败。建议的做法是先创建一个权限较宽的 Key 用于开发调试等 Skill 结构稳定后再收紧权限。开发阶段最重要的是快速验证“Skill 能不能被正确加载、元数据能不能被正确解析”而不是一上来就搞最小权限。3. 可复制的配置骨架settings.json 与 config.toml这一节直接给骨架你复制过去改三个字段就能用。3.1 Cline 的 settings.jsonCline 的配置通常放在工具的设置目录下核心字段如下{ apiProvider: openai, openAiBaseUrl: https://taotoken.net/api, openAiApiKey: sk-你的TaoToken密钥, openAiModelId: claude-sonnet-4-20250514, skills: { enabled: true, searchPaths: [ ./skills, ~/.cline/skills ] } }这里searchPaths是关键。Cline 启动时会扫描这些目录读取每个子目录下的 SKILL.md但只解析 YAML frontmatter 里的 name 和 description不会加载正文。这就是渐进式披露的第一层——发现层。如果你把 searchPaths 配错了Skill 根本不会被发现Agent 自然也不会调用。3.2 CC Switch 的 config.tomlCC Switch 用 TOML 格式语义一样但写法不同[provider] name taotoken base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 default_model claude-sonnet-4-20250514 [skills] enabled true paths [./skills, ~/.ccswitch/skills] max_metadata_tokens 2000max_metadata_tokens这个字段值得单独说。它限制的是所有 Skill 元数据加起来占用的 token 上限。如果你有几十个 Skill每个 description 写得很长这个值会被撑爆导致部分 Skill 的元数据被截断Agent 就看不到它们了。所以 description 要精炼这不是风格问题是硬性约束。3.3 SKILL.md 最小示例配置好搜索路径后在./skills下建一个目录比如api-test-generator/里面放 SKILL.md--- name: api-test-generator description: 根据 OpenAPI/Swagger 文档生成 API 测试用例。当用户提到接口测试、API测试、生成测试用例、swagger 转测试时使用。 allowed-tools: - read_file - write_file - run_script --- # API 测试用例生成器 ## 目标 读取 OpenAPI 文档为每个 endpoint 生成正向和异常测试用例。 ## 执行步骤 1. 读取用户指定的 swagger.json 或 openapi.yaml 2. 解析 paths 和 schemas 3. 对每个 endpoint 生成正常请求、缺参请求、类型错误请求 4. 输出为 pytest 格式的测试文件 ## 输入输出 - 输入OpenAPI 文档路径 - 输出test_service.py ## 边界 不负责执行测试只负责生成。执行交给 pytest。注意正文只有三十多行。这不是偷懒是刻意设计。正文只写 AI 必须知道的执行逻辑更长的规范、示例、边界情况全部放到 references/ 目录按需加载。4. 仓库结构scripts、references、assets 各司其职一个标准 Skill 仓库的结构是这样的api-test-generator/ ├── SKILL.md ├── scripts/ │ └── parse_openapi.py ├── references/ │ ├── assertion_rules.md │ └── pytest_template.md └── assets/ └── sample_swagger.json每个目录的职责不能混。我见过有人把 Python 脚本直接贴在 SKILL.md 正文里结果每次加载 Skill 都要把整段代码读进上下文token 消耗翻倍而且代码里的注释和 AI 的执行逻辑混在一起模型容易分不清哪些是“要执行的指令”、哪些是“参考代码”。scripts/ 放可执行脚本。Agent 可以直接运行这些脚本把结果拿回上下文。脚本代码本身不占上下文 token只有执行结果进入上下文。这是 Skill 承载确定性能力的关键——复杂计算、数据清洗、格式转换交给脚本而不是让模型去猜。比如上面的parse_openapi.py它负责把 swagger 解析成结构化数据模型只需要读解析结果不需要理解 swagger 的全部规范。references/ 放参考文档。详细的断言规则、长篇幅的风格指南、政策文档都放这里。SKILL.md 正文里用相对路径引用比如“断言规则见 references/assertion_rules.md”。Agent 在执行到需要断言的时候才会去读这个文件不需要的时候不加载。assets/ 放静态资源。模板文件、样例数据、图片。Agent 生成内容时可以直接引用这些模板避免每次从零构造。这三层目录加 SKILL.md 本身构成了完整的渐进式披露体系元数据是第一层发现正文是第二层执行scripts/references/assets 是第三层按需加载的深层资源。目录结构不是装饰是渐进式披露的物理载体。你把所有东西塞进 SKILL.md等于把三层压成一层渐进式披露就失效了。5. 验证 Skill 加载与仓库结构解析写完配置和 SKILL.md怎么确认它真的被正确加载了不要靠“感觉它能用”要有具体的验证动作。第一步检查元数据是否被解析。在 Cline 或 CC Switch 的日志里搜索 Skill 名称。如果配置正确启动日志里会出现类似Loaded skill metadata: api-test-generator的记录。如果搜不到说明 searchPaths 配错了或者 SKILL.md 的 frontmatter 格式有问题——最常见的是---分隔符前后有空格或者 name 字段和文件夹名不一致。第二步触发一次实际调用。在对话里说“帮我根据这个 swagger 生成测试用例”观察 Agent 的行为。正确的表现是Agent 先读取 SKILL.md 正文然后按步骤读取 references/ 下的文件最后调用 scripts/ 里的脚本。如果 Agent 直接把整个 SKILL.md 内容复述一遍就结束说明它没有理解“执行步骤”正文写得太像说明文档而不是操作指令。第三步检查 token 消耗。这是验证渐进式披露是否生效的硬指标。在只触发一个 Skill 的情况下观察上下文 token 数。如果 token 数接近 SKILL.md 全文加上所有 references 的总和说明渐进式披露没生效所有内容被一次性加载了。正常情况应该只加载元数据加正文references 按需加载。第四步验证仓库结构解析。在 Skill 目录下故意放一个格式错误的文件比如 references/ 下放一个空的 .md看 Agent 是否会报错。如果它静默忽略说明解析逻辑比较宽松如果报错说明结构校验是严格的。两种行为都可以接受但你要知道你的工具是哪种这样出问题时能快速定位。我试过在 CC Switch 里把max_metadata_tokens设成 500然后放了 10 个 Skill结果只有前 3 个能被发现。这就是元数据超限的典型症状——不是 Skill 写错了是配置的预算不够。把 description 精简到一句话或者调大这个值问题就解决了。6. 本篇常见错排查报错一Skill 完全不生效Agent 从不调用。先查 searchPaths 是否指向了正确的目录。注意相对路径是相对于工具的工作目录不是相对于配置文件。如果你在项目根目录启动工具./skills就是项目根下的 skills 目录。其次查 SKILL.md 的 frontmattername 必须和文件夹名完全一致包括大小写。最后查 description如果写得太泛比如“帮助处理数据”Agent 的语义匹配可能命中不了换成包含具体触发短语的描述。报错二请求返回 401 或 403。这是接入层问题不是 Skill 问题。检查 api_key 是否填对base_url 是否是https://taotoken.net/api。如果 Key 有模型白名单确认 SKILL.md 里指定的模型在白名单内。还有一种情况是 Key 过期或被禁用去控制台重新生成一个。报错三Skill 加载了但执行结果不对。大概率是正文写得太模糊。Agent 读到了指令但不知道具体怎么做。把“生成测试用例”改成“对每个 endpoint 生成三个用例正常请求、缺参请求、类型错误请求输出为 pytest 格式”。指令越具体执行越稳定。另外检查 references/ 里的文件是否被正确引用路径写错的话 Agent 读不到参考文档只能靠猜。报错四token 消耗异常高。检查是不是把所有内容都塞进了 SKILL.md 正文。正文超过 200 行就要警惕了。把参考信息移到 references/把代码移到 scripts/。另外检查max_metadata_tokens是否设得过大导致所有 Skill 的元数据都被加载。元数据总量控制在 2000 token 以内比较合理。报错五多个 Skill 冲突。两个 Skill 的 description 触发了同一个用户请求Agent 不知道该用哪个。解决办法是在 description 里明确边界比如“本 Skill 只处理 OpenAPI 文档不处理 Postman 集合”。如果边界确实有重叠考虑合并成一个 Skill或者在上层用一个调度 Skill 来路由。7. 把 Skill 当能力单元而不是长提示词回到最开始的问题你打开最近写的一个 SKILL.md看一眼正文长度。如果超过 200 行问自己这里面有多少是核心执行逻辑有多少是参考信息如果参考信息占了大半你其实没在用渐进式披露只是写了个长文本提示词然后给它披上了 SKILL.md 的外衣。正确的做法是反过来先想清楚这个 Skill 的边界在哪它只做哪一件事这件事的输入输出是什么。然后正文只写执行这件事必须知道的步骤其他全部外移。脚本放 scripts/规范放 references/模板放 assets/。这样写出来的 Skill加载快、复用易、改起来只动一个文件夹。接入层用 TaoToken 统一 Key是为了让你在多个工具之间切换时不用重复配置。但 Skill 本身的质量取决于你对渐进式披露和仓库结构的理解。配置骨架可以直接复制但结构设计得自己判断。判断的标准很简单这个 Skill 能不能被另一个 Skill 调用能不能在不改正文的情况下替换底层脚本能不能让 Agent 在只读元数据的时候就决定要不要加载它三个问题都能答“是”你就写对了。如果你在配置 settings.json 或 config.toml 时遇到接入问题可以先到 API Keys 页面确认 Key 状态再对照接入文档检查字段名。想快速验证模型是否连通用模型对话跑一次最小请求最直接。如果是长期做编码和 Agent 开发Coding Plan 能省去反复配 Key 的麻烦。