1. 先搞清楚 SKILL 到底在解决什么问题Claude 的 SKILL 机制说白了就是给模型装上一套「按需展开的操作手册」。它不是插件不是可执行代码更不是某种新的函数调用协议。你在SKILL.md里写的东西本质是一段结构化的提示词模板Claude 在判断「当前任务需要它」时才会把这段模板注入到对话上下文里从而改变自己的处理方式。这个设计要解决的核心矛盾是上下文窗口有限但专业任务需要的背景知识、步骤约束、输出格式要求又特别多。如果把这些全部塞进系统提示词每次对话都要背着几万字的负担既浪费 token 又稀释注意力。SKILL 的思路是「渐进式披露」——先只暴露name和description让 Claude 知道「有这么个东西存在」等真正命中场景了再加载完整内容。适合谁用如果你在 Cline、CC Switch 这类工具里做 AI 工作流编排或者想让 Claude 稳定地执行某类重复性任务比如代码审查、文档生成、数据清洗SKILL 就是比「每次手写长提示词」更工程化的方案。我试过把一套代码规范检查流程写成 SKILL之后每次让 Claude 审查 PR它都会自动按我定义的步骤走输出格式也统一了。下面从文件结构、Frontmatter 元数据、allowed-tools 权限声明三个层面逐层拆开最后给出可复制的骨架和验证步骤。2. 前置准备TaoToken 接入与 SKILL 运行环境SKILL 本身是 Claude 侧的机制但你要在本地工具链里跑通它需要一个能稳定调用 Claude 模型的入口。TaoToken 提供的就是这个入口——它把模型调用统一成标准 API你在 Cline 或 CC Switch 里配置好之后SKILL 的加载和执行链路才能正常走通。先拿到 API Key。访问 https://taotoken.net/api-keys 创建密钥注意这个 Key 只在创建时完整显示一次复制后存到安全的地方。如果你还没注册从 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 进去即可。拿到 Key 之后不同工具的配置方式略有差异。Cline 是在设置里填 API Base 和 KeyCC Switch 则是改config.toml。下面两节分别给出配置片段。注意SKILL 的识别和调用依赖模型本身的能力建议用 Claude 系列模型测试其他模型可能不支持allowed-tools这类元数据字段。3. SKILL.md 文件结构与 Frontmatter 配置3.1 Frontmatter 字段逐个说明SKILL.md的开头是一段 YAML Frontmatter用---包裹。这是 Claude 判断「要不要加载这个 SKILL」的主要依据。字段不多但每个都有明确用途--- name: code-review-helper description: Use when users want to review code changes for style, security, and performance issues. Analyzes diffs and produces structured feedback. license: MIT allowed-tools: Read, Grep, Bash(git:*) model: inherit version: 1.0.0 disable-model-invocation: false ---name是必填的作为命令标识符用户可以用/code-review-helper显式调用。description同样必填这是 Claude 做意图匹配时读的主要信号写法上建议用明确的动作语言比如「Use when users want to...」而不是模糊的「This skill helps with...」。allowed-tools是可选的但很关键。它声明了这个 SKILL 在执行期间可以无需用户二次确认就使用的工具。支持通配符比如Bash(git:*)表示允许执行所有 git 开头的命令。这个字段直接关系到权限边界后面单独展开。model字段可选不填则继承当前会话的模型。disable-model-invocation设为true时Claude 不会自动匹配这个 SKILL只能通过/skill-name手动触发——适合那些你不想让模型「自作主张」调用的场景。3.2 Markdown 正文的推荐结构Frontmatter 之后是正文采用渐进式披露的写法。推荐的结构是这样# Purpose Statement 一句话说明这个 SKILL 做什么。 ## Overview 做什么、何时用。 ## Prerequisites 所需工具、文件、上下文。 ## Instructions 逐步指令用祈使句。 ## Output Format 预期输出结构。 ## Error Handling 失败场景与恢复方式。 ## Examples 具体用例。 ## Resources 对绑定文件的引用。正文控制在 5000 词以内避免上下文膨胀。写指令时用祈使语气比如「Analyze code for...」而不是「You should analyze...」。引用外部文件时用{baseDir}变量不要硬编码绝对路径这样 SKILL 在不同环境下都能用。3.3 绑定资源目录每个 SKILL 可以打包三类辅助文件放在与SKILL.md同级的目录下/scripts/存放 Python 或 Bash 可执行脚本用于确定性操作。Claude 的调用方式是python {baseDir}/scripts/script_name.py。/references/存放 Claude 需要读入上下文的文档资料比如 Markdown 指南、JSON Schema、API 文档。调用方式是Read({baseDir}/references/guide.md)。/assets/存放模板和二进制文件按路径引用不加载进上下文。比如{baseDir}/assets/template.html。4. 在 Cline 与 CC Switch 中落地配置4.1 Cline 的 settings.json 配置Cline 的配置在settings.json里核心是填对 API Base 和 Key{ cline.apiProvider: openai, cline.openaiApiKey: 你的TaoToken密钥, cline.openaiBaseUrl: https://taotoken.net/api, cline.model: claude-sonnet-4-20250514, cline.skillsDir: ./skills }skillsDir指向你存放 SKILL 的目录Cline 启动时会扫描这个目录下的所有SKILL.md文件读取 Frontmatter 建立索引。4.2 CC Switch 的 config.toml 配置CC Switch 用 TOML 格式配置片段如下[provider] name taotoken api_base https://taotoken.net/api api_key 你的TaoToken密钥 [model] default claude-sonnet-4-20250514 [skills] enabled true directory ./skills auto_load trueauto_load true表示启动时自动扫描并注册 SKILL。如果你想让某些 SKILL 只在手动触发时加载把对应 Frontmatter 里的disable-model-invocation设为true。4.3 目录结构示例一个完整的 SKILL 目录长这样skills/ └── code-review-helper/ ├── SKILL.md ├── scripts/ │ └── diff_parser.py ├── references/ │ └── style-guide.md └── assets/ └── report-template.htmlClaude 在匹配到code-review-helper后会先加载SKILL.md全文然后根据指令按需读取references/下的文件或执行scripts/下的脚本。5. 验证 SKILL 被正确识别与调用配置完成后需要确认 SKILL 真的被加载了。分三步验证。第一步检查索引。在 Cline 或 CC Switch 的日志里搜索skill registered或类似关键词应该能看到你定义的name出现在已注册列表里。如果没出现多半是skillsDir路径写错了或者SKILL.md的 Frontmatter 格式有问题。第二步显式调用。在对话里输入/code-review-helper观察 Claude 的响应。如果 SKILL 被正确加载你会看到它按照SKILL.md里定义的步骤开始工作而不是泛泛地回复。这一步能排除「Frontmatter 解析失败」的问题。第三步隐式匹配。不提 SKILL 名字直接说「帮我审查一下这段代码的改动」看 Claude 是否自动触发。这一步验证的是description字段的意图匹配效果。如果没触发说明描述写得不够明确需要调整措辞。验证请求可以用一个简单的 curl 命令直接测 API 连通性curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer 你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 列出当前可用的 skills}] }如果返回正常说明 API 链路通了剩下的就是 SKILL 配置层面的排查。6. 常见报错与排查SKILL 未被识别最常见的原因是 Frontmatter 的---没有顶格写或者 YAML 缩进用了 Tab。YAML 只认空格Tab 会导致解析失败。另一个原因是name字段缺失或包含非法字符建议只用小写字母和连字符。allowed-tools 不生效检查工具名是否拼写正确通配符格式是否合法。Bash(git:*)是正确写法Bash(git*)可能不被识别。另外allowed-tools只在 SKILL 执行期间生效执行结束后权限会重置这是设计如此不是 bug。隐式匹配不触发description写得太泛比如「helps with code」这种Claude 无法判断何时该用。改成具体的动作和场景描述比如「Use when users want to review code diffs for security vulnerabilities」。脚本执行失败检查{baseDir}变量是否正确展开脚本是否有可执行权限。在SKILL.md里引用脚本时路径要写成{baseDir}/scripts/xxx.py不要写相对路径。模型不覆盖如果 Frontmatter 里指定了model但没生效确认当前工具是否支持模型覆盖。部分工具会忽略 SKILL 级别的模型设置统一用全局配置。7. 继续深入的方向SKILL 的加载链路走通之后下一步可以研究context modifier函数的行为——它负责在 SKILL 激活时预批准工具、覆盖模型、修改权限规则并在执行结束后重置。理解这一层你就能设计出更精细的权限边界。如果你打算长期用 SKILL 做编码或 Agent 工作流建议把常用 SKILL 整理成一套目录配合 Coding Plan 使用减少每次手动配置的成本。模型对话入口可以用来快速测试 SKILL 的匹配效果接入文档里有完整的 API 参数说明。