1. 为什么 SKILL.md 写好了Claude Agent 却像没看见很多人第一次接触 skill 规范都会卡在同一个地方文件明明按官方结构写好了SKILL.md放在.claude/skills/下name和description也填了结果让 Claude Agent 干活时它压根不加载这个 skill或者加载了却像没读一样行为完全不受约束。我试过把一份写得很细的SKILL.md丢进项目结果 agent 该用pdfplumber的地方自己换成了别的库该走备份流程的地方直接跳步。排查半天才发现问题不在 skill 内容本身而在“规范翻译”这一层——也就是把 skill 的字段、目录结构、加载机制正确映射成 Claude Agent 能读懂的配置。skill 规范agentskills.io 那套和 Claude Agent 的实际读取逻辑之间隔着一层需要手动对齐的映射关系。这篇就聚焦这个映射场景把skill、description这些字段翻译成 Claude Agent 可读的配置交付能直接复制的settings.json与config.toml骨架给出 CC Switch / Cline 的接入步骤最后用一个验证动作确认 skill 真的加载了、description 真的生效了。适合已经在写 skill、但被“写了不生效”折磨过的同学。核心检索词先摆出来SKILL.md 是什么、能做什么、适合谁。SKILL.md 是 skill 规范里的核心文件一个 skill 就是一个目录SKILL.md是必需项顶部 YAML 元数据加正文 Markdown 指令它能让 Claude Agent 在匹配到任务时按需加载你的领域知识、脚本和参考文档。适合所有想让 agent 稳定复现某类任务的人。2. 前置TaoToken 统一 Key 与 skill 目录约定在动手翻译配置之前先把两件事定下来模型访问入口和 skill 的存放位置。模型访问这块我用 TaoToken 的统一 Key 来打通。它的好处是一个 Key 就能覆盖 Claude 系列模型的调用不用在多个平台之间来回切配置。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个不加 UTM。后面settings.json和config.toml里的base_url都指向它。skill 目录约定这块Claude Agent 的扫描逻辑遵循 skill 规范的三层加载会话一开始只加载所有SKILL.md的namedescription每个约 50~100 token模型根据description判断要不要用决定用了才加载整个SKILL.md正文建议 5k token 内正文里引用了references/、scripts/、assets/才按需加载。所以目录结构必须规范my-skill/ ├── SKILL.md # 必需YAML 元数据 Markdown 指令 ├── scripts/ # 可选可执行脚本 ├── references/ # 可选参考文档 └── assets/ # 可选模板、静态资源SKILL.md顶部的 YAML 必须严格按规范写name要和目录名一致、最大 64 字符description最大 1024 字符。这两个字段是“翻译”的关键——它们决定了 agent 会不会激活这个 skill。注意description不是随便写的简介它是 agent 决策是否加载 skill 的唯一依据。写得太窄该触发时不触发写得太宽不该触发时乱触发。3. 可复制配置settings.json 与 config.toml 骨架这一节是重点直接给能复制的骨架。Claude Agent 侧的配置主要落在settings.jsonCline 这类客户端用config.toml两者字段含义要对齐。3.1 settings.json 骨架Claude Agent / Claude Code{ model: claude-sonnet-4-5, apiKey: sk-your-taotoken-key, baseURL: https://taotoken.net/api, skills: { enabled: true, directories: [ .claude/skills, .agents/skills, ~/.claude/skills ], autoDiscovery: true, maxScanDepth: 5, maxScanDirs: 2000 }, skillActivation: { mode: model-driven, allowUserOverride: true, overridePrefix: /skill- }, context: { protectSkillContent: true, dedupeActivatedSkills: true } }逐字段说明。baseURL指向 TaoToken 的 API 基址apiKey用你在控制台生成的 Key。skills.directories是 agent 扫描 skill 的目录列表项目级.claude/skills优先级高于用户级~/.claude/skills.agents/skills是跨客户端通用约定建议都留着。maxScanDepth和maxScanDirs是防止扫描过深目录树拖慢启动规范里建议 4~6 层、2000 个目录上限。skillActivation.mode设为model-driven表示由模型根据description语义匹配决定激活allowUserOverride允许用户用/skill-xxx显式指定。context.protectSkillContent很关键——它保证已激活的 skill 内容在上下文压缩时不被裁掉否则聊到后面 agent 会“忘记” skill 规则。3.2 config.toml 骨架Cline 等客户端[model] provider openai-compatible model_id claude-sonnet-4-5 base_url https://taotoken.net/api api_key sk-your-taotoken-key [skills] enabled true directories [.claude/skills, .agents/skills] auto_discovery true max_scan_depth 5 [skills.activation] mode model-driven allow_user_override true override_prefix /skill- [skills.context] protect_skill_content true dedupe_activated_skills trueconfig.toml和settings.json的字段是一一对应的只是命名风格从驼峰换成了下划线。provider用openai-compatible是因为 TaoToken 的 API 兼容 OpenAI 协议格式Claude 系列模型通过这个协议也能正常调用。3.3 SKILL.md 字段到配置的映射表把 skill 规范字段翻译成 agent 可读配置对应关系如下SKILL.md 字段规范要求映射到配置的作用name必需与目录名一致≤64 字符作为 skill 唯一标识用于/skill-name显式激活和去重description必需≤1024 字符注入到 agent 的 skill 索引模型据此判断是否激活license可选元数据不影响加载compatibility可选≤500 字符激活后随正文给模型指导环境适配metadata可选KV 结构作者、版本等供管理用allowed-tools可选空格分隔限制该 skill 可调用的工具范围description的写法直接决定激活率。规范建议用祈使句聚焦“用户想干嘛时用这个 skill”而不是“这个 skill 能做什么”。比如--- name: csv-analyzer description: Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts, and clean messy data. Use this skill when the user has a CSV, TSV, or Excel file and wants to explore, transform, or visualize the data, even if they dont explicitly mention CSV or analysis. ---对比一下差的写法description: Process CSV files.——太窄用户说“帮我看看这个表格”就触发不了。4. CC Switch / Cline 接入步骤与验证动作配置骨架有了接下来是接入和验证。这一步不做你永远不知道 skill 到底加载没有。4.1 CC Switch 接入CC Switch 用来在多个 Claude 配置之间切换。接入 TaoToken 的步骤第一步在 CC Switch 里新增一个 providerbase_url填https://taotoken.net/apiapi_key填你的 TaoToken Key。第二步把上面 3.1 的settings.json内容合并进当前 profile重点是skills.directories要包含你实际放 skill 的目录。第三步切换到这个 profile重启 Claude Agent 会话让 skill 扫描重新执行。4.2 Cline 接入Cline 走config.toml。在 Cline 的设置里找到配置文件路径把 3.2 的内容写进去api_key换成你的 Key。保存后 Cline 会在下次会话启动时重新扫描 skill 目录。4.3 验证动作调用一次确认 skill 加载与 description 生效光看配置不叫验证要实际跑一次。准备一个测试 skill目录结构.claude/skills/csv-analyzer/ ├── SKILL.md └── scripts/ └── summarize.pySKILL.md里写一条只有这个 skill 才知道的规则比如“输出统计结果时必须用 markdown 表格且表头固定为 Metric / Value”。然后在会话里发一条能匹配description的提示我有个 CSV 在 data/sales.csv帮我算一下各列汇总用表格给我。观察 agent 的执行过程。如果 skill 生效它会按SKILL.md里的规则输出固定表头的表格如果没生效它会用默认格式。更严谨的做法是看执行日志里的工具调用历史确认出现了读取SKILL.md的动作。再验证一次“不该触发”的情况发一条不相关的提示帮我写个斐波那契函数。如果 agent 没去加载csv-analyzer说明description的边界控制得当。规范建议准备约 20 条查询8~10 条应触发、8~10 条不应触发每条跑 3 次算触发率应触发的触发率高于 0.5 算通过。5. 本篇常见错排查配置和验证跑下来最容易踩的坑集中在这几类。5.1 skill 完全不加载先查目录。agent 只认包含SKILL.md的目录文件名大小写敏感skill.md不行必须SKILL.md。再查settings.json里的skills.directories有没有包含实际路径。如果 skill 放在项目级目录但项目没被标记为可信部分实现会跳过加载这是安全考量。5.2 description 不触发description写得太窄或太泛都会出问题。太窄比如只写了“处理 CSV”用户说“分析这个表格”就匹配不上太泛比如“处理数据文件”用户说“改一下 Excel 公式”也会误触发。规范建议聚焦“用户想达成什么目标”并明确列出适用场景哪怕用户没直接点明领域词。5.3 YAML 解析失败导致 skill 被跳过description里带冒号比如时间戳、URL没加引号宽松解析器能过严格解析器直接报错跳过整个 skill。解决办法是用引号包起来或者用 YAML 块标量|或写多行文本。这也是为什么同一个 skill 在 A 客户端能用、B 客户端不能用。5.4 激活后 agent 行为不受约束检查context.protectSkillContent是否为true。如果为false长会话里 skill 内容可能被上下文压缩裁掉agent 就“忘记”规则了。另外确认dedupeActivatedSkills开启避免同一 skill 反复注入。5.5 脚本执行卡住skill 里的脚本如果在非交互式 shell 里等待输入比如input()、read -pagent 会无限挂起。脚本所有输入必须通过命令行参数、环境变量或 stdin 传入并且提供--help说明用法报错信息要包含“发生了什么”和“下一步怎么办”。6. 把 Key 和 skill 配置一次对齐回到开头那个问题SKILL.md 写好了却不生效本质是规范字段和 agent 配置没对齐。把name、description映射到 skill 索引把目录约定映射到skills.directories把激活和上下文保护映射到skillActivation和context这层翻译做对了skill 才会真正被 agent 用起来。模型访问这块用 TaoToken 的统一 Key 把base_url和api_key一次配好后面不管切 CC Switch 还是 Cline都只改客户端不改 Key。需要生成或管理 Key 的话控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你还在调 skill 的接入和排障建议先把 API Keys 和接入文档过一遍接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。想先确认模型对话是否正常可以去模型对话页 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 发一条测试。长期跑编码和 Agent 任务的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Claude Code 相关配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个实操建议每次改完description别只看配置文件一定跑一次“应触发 不应触发”的对照测试。skill 这东西写得好不好agent 用不用只有实际调用一次才知道。