OpenClaw 的 Agent Skills 最容易踩的坑不是 SKILL.md 写得不规范而是模型通道没接上——TaoToken 要解决的也正是这一段。先把结论放前面去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 拿一把 Key再把 openclaw.json 里的 Base URL 填成 https://taotoken.net/api技能才有机会被模型「看见」。很多人以为把 SKILL.md 丢进 skills 目录就算装好了其实文件只是躺在磁盘上真正决定它能不能被挑中的是模型那一侧的通道是否通、模型 ID 是否对得上。这篇文章按加载链路走一遍先拆开 SKILL.md 的两段式结构再看 openclaw.json 里那两个总要自己拼的空位最后给出可以直接抄的配置、验证方法和出错时的排查顺序。1. 把 SKILL.md 丢进目录OpenClaw 到底读到了什么1.1 frontmatter 先上场正文按需再读Agent Skills 的加载是两段式的理解这一点比记住任何配置项都重要。第一段发生在会话刚开始OpenClaw 扫描技能目录把每个 SKILL.md 顶部 frontmatter 里的name和description抽出来拼进系统上下文。第二段发生在模型决定要用某个技能之后这时候才把 SKILL.md 的正文读进来正文里写了什么命令、什么步骤、输出格式要求是什么模型此时才看得见。这个两段式设计省的是 token。二十个技能的元数据加起来可能只有几百字但二十个技能的完整正文动辄上万字全部预加载纯属浪费。代价同样明显——description 是第一段唯一的筛选依据写得含糊模型在第一步就把你排除了正文写得再工整也没有出场机会。一个能跑的 SKILL.mdfrontmatter 大概长这样--- name: weather-brief description: 查询指定城市的实时天气并给出穿衣、带伞建议。用户提到天气、气温、下雨、要不要带伞时使用。 ---正文部分建议分成三块写清楚。第一块说明触发场景用自然语言重复一遍 description 里的关键词第二块写具体怎么做把命令原样贴出来第三块写输出要求比如「两句话讲完不要罗列原始数据」。中间那块的命令块单独长这样curl -s https://wttr.in/Shanghai?format3注意这条命令是在你自己的机器上执行的网络不通、域名解析失败、命令不存在报错都会原样回到对话里。SKILL.md 本身不负责执行它只是把「该执行什么」告诉模型。1.2 技能目录的层级和文件名比内容更容易出错目录结构上OpenClaw 通常按skills/技能名/SKILL.md这一层来找。技能名建议和 frontmatter 里的name保持一致全小写、用连字符分隔避免空格和大小写混写。常见错误有三种把 SKILL.md 直接放在 skills 根目录而不是放进子目录文件名写成skill.md、SKILL.md.txt、README.md子目录名带空格或者中文。另外要注意技能目录的解析顺序。项目内的./skills和用户目录下的~/.openclaw/skills如果同时存在同名技能到底哪一份生效取决于你本地版本的实现顺序。稳妥做法是同一个技能名只保留一份改完文件后用一条明确的问句去验证不要指望「两个都放总会有一个生效」。技能数量也不用一上来就堆。先跑通一个确认链路通了再按需增加。一口气塞十个技能进去最先出问题的往往不是技能本身而是你自己都分不清是哪个环节没生效。1.3 决定加载成败的其实是模型通道文件层面全部正确之后真正的关卡才出现。OpenClaw 要把 frontmatter 元数据送进模型、接收模型返回的「要不要用这个技能」、再把技能正文送进去让模型编排步骤——这三个动作全部经过同一个模型通道。通道不通前面所有准备都是白做模型收不到元数据自然不会调用任何技能。这就是为什么很多人遇到的现象是「技能明明写对了AI 就是不用」。它不报错也不提示就是不用。因为模型压根没看到那段 description或者看到的是被截断的版本。所以排查技能加载问题顺序应该倒过来先确认模型通道是通的、模型 ID 是存在的再回头检查 SKILL.md 的写法。倒着查能省掉大量时间。2. openclaw.json 里那两个总要自己拼的空位2.1 官方示例留下的两个坑OpenClaw 的初始配置文件里model段通常是留空的或者给一个明显是占位符的值apiKey写着your-api-key-herebaseURL要么注释掉要么指向一个示例域名。官方这么做是合理的它不知道你想用哪条通道但对第一次上手的人来说这两个空位就是全部问题的来源。直接拿一个真实厂商的地址填进去又会遇到第二层麻烦模型名对不上、额度不好估算、换一个模型要改一次配置、几把 Key 分散在不同控制台里。技能这边只要动一次模型那边就得跟着动来回几次之后配置文件就变成了一团谁也不敢改的东西。2.2 TaoToken 在这条链路里只做一件事当模型通道把baseURL指向 https://taotoken.net/api 之后模型这一段就固定下来了。它是兼容通道的形式协议按 OpenAI 那一套走OpenClaw 不需要为它单独写适配器。需要换模型的时候只改model字段baseURL和apiKey都不用动。关键要说清楚的是它的边界TaoToken 只出现在模型通道这一层。SKILL.md 里的curl、wttr.in、你自己写的脚本命令一个都不用改。技能文件长什么样和你用哪条通道没有关系。有些教程会让人把命令里的地址也一起改掉那纯粹是多余的——命令是给本机执行的通道是给模型走请求的两者在不同的层上。2.3 provider 字段别乱填provider一般保持openai-compatible这一类兼容标识OpenClaw 会据此选择协议适配方式。如果你把它填成某个具体厂商的名字OpenClaw 可能去找一个不存在的适配器然后在一堆技能加载日志里报一个和模型无关的错你按技能去查会查半天。同一份配置里只保留一个 model 段。有些版本的配置文件允许定义多个 provider 再引用来引用去能用是能用但出问题时链长了两倍。单技能调试阶段一个 provider、一条 baseURL、一把 Key足够了。3. 手把手改 openclaw.json3.1 先创建 Key再动配置文件打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册登录进控制台创建一把 API Key复制出来先放在临时记事本里。同时去模型广场看一眼当前可用的模型 ID 列表把准备用的那个记下来——注意是列表里实际存在的 ID不是凭印象拼出来的名字。这里有个习惯值得养成给 Key 起一个能认出来的名字比如openclaw-dev以后在控制台看用量时能一眼分清是哪个工具在调用。Key 只在创建时完整展示后面再看就是脱敏的了复制时别多带换行和空格。准备齐三样东西就可以动手了一把 Key下文统一写成YOUR_API_KEY、一个 Base URLhttps://taotoken.net/api、一个模型 ID以模型广场当时列表为准。3.2 openclaw.json 的最小可用配置配置文件里和技能加载直接相关的其实就两块model决定技能能不能被模型看到skills决定文件从哪些目录被扫到{ model: { provider: openai-compatible, baseURL: https://taotoken.net/api, apiKey: YOUR_API_KEY, model: YOUR_MODEL_ID }, skills: { directories: [./skills, ~/.openclaw/skills] } }如果你的 openclaw.json 里已经有model段只改baseURL、apiKey、model三行即可其余字段别碰。改完保存重启 OpenClaw让配置重新加载。有一个细节必须强调baseURL只填到https://taotoken.net/api末尾不要加/v1。OpenClaw 自己会拼接后续路径你多写一层请求就打到/v1/v1/...上去报错信息里通常看不出是这里的问题。另外落地页那种带查询参数的链接是给人点的不要整串贴进配置文件配置文件里只认干净的接口地址。3.3 逐字段核对一遍再启动字段填什么常见错法model.provider兼容标识如 openai-compatible填成具体厂商名找不到适配器model.baseURLhttps://taotoken.net/api末尾多写 /v1或贴进带参数的落地页链接model.apiKeyYOUR_API_KEY留着示例占位值或复制时带了空格换行model.model以模型广场当时列表为准凭记忆写一个名字列表里根本没有skills.directories你实际的技能目录路径写成了相对路径但启动目录不对核对完这一轮再启动能省掉大部分来回。特别是最后一行./skills是相对路径它相对于谁取决于 OpenClaw 启动时的工作目录。拿不准就用绝对路径别在这种地方跟自己较劲。4. 跑起来验证技能有没有被模型挑中4.1 一条测试问句比看配置文件有用配置保存、服务重启之后别急着看日志先在 OpenClaw 里发一条明确能命中技能的问句比如「上海今天要带伞吗」。这条问句里同时出现了地点和「带伞」正好落在 weather-brief 的 description 关键词上是命中率最高的一种问法。然后看回显。理想情况是模型先说它要用天气简报这个技能接着出现一次命令执行打印出一行天气数据最后给出两句话结论。整个过程中命令是你本机跑的模型只是决定「要跑这条命令」并解读结果。反过来如果模型直接凭记忆答了一句「上海最近可能下雨建议带伞」没有任何命令执行痕迹那基本可以判定技能没被加载或没被选中。这种答法看起来像成功其实是最容易骗过自己的失败。4.2 三段链路分开判断把上面的流程拆成三段来看定位会快很多。第一段是元数据有没有进上下文把技能数量临时减到只剩一个如果这时能命中说明是技能之间互相干扰不是通道问题。第二段是通道通不通如果所有技能都不命中而且普通提问也回答得很奇怪或者干脆报错先怀疑通道。第三段是执行环节模型说要跑命令、但输出是报错那问题在命令本身跟配置无关。这三段各自独立别混在一起改。一次只动一个变量改完立刻用同一条问句复测。4.3 去控制台对一下这次调用记上账没有链路通了之后回到 TaoToken 控制台 看一下调用记录。控制台里能看到刚才那条问句产生的请求对着时间戳能确认走的就是 openclaw-dev 这把 Key。这一步的意义不在「看用量」而在于确认你改的配置真的生效了——如果记录是空的说明请求压根没发到你填的这条通道上配置文件里大概率还留着别的地方没改。顺手也能看到每次技能加载大概消耗多少 token。技能数量上来之后这部分开销会变明显元数据不是免费的值得定期看一眼。5. skills 没动静的时候按这个顺序查5.1 文件层面目录、文件名、frontmatter先确认三件事SKILL.md 在不在skills/技能名/这个层级里文件名是不是全大写的SKILL.mdfrontmatter 有没有用三条短横线正确包起来。frontmatter 里如果name和description有一项缺失元数据就是空的模型看到的是半截信息行为会变得很随机——有时用有时不用最难查。5.2 触发层面description 写得太宽或者太窄太宽的写法长这样「帮助用户处理各种日常问题」。这句话放进上下文里几乎是噪音模型无法判断什么时候该用它。太窄的写法是只写了一个生僻关键词用户的自然问法根本碰不到。一个实用的写法是把 description 写成「做什么 什么时候用」两段前半句说能力后半句列出用户可能说的几个词。上面那个天气技能就是这么写的命中率明显比只写「查天气」高。5.3 通道层面Key 和 Base URL 先各看一眼所有技能同时失效而且普通对话也开始报鉴权相关的错那就是通道层。先确认apiKey不是官方示例里的占位值再确认baseURL是https://taotoken.net/api而不是别的地址、也没多写/v1。最后核对模型 ID模型名不存在时报错通常很模糊容易误判成技能问题去模型广场对一遍就能排除。5.4 执行层面命令报错就贴回对话不要在配置里找原因如果模型确实调用了技能但命令输出是command not found、超时、或者返回一段 HTML 错误页这跟 openclaw.json 没有任何关系。把你本机的报错原样贴回对话让模型下一步去换命令或者换参数。SKILL.md 里的命令写的是你本机环境的事实环境不对改配置文件是解决不了的。6. 多技能共存时别让 SKILL.md 互相打架6.1 description 之间要有清晰边界两个技能的 description 都提到「文件」这个词模型在选择时就会摇摆有时选 A、有时选 B、有时两个都调用一遍。这种问题不会报错只会让输出变得不稳定。解决办法是在描述里写清楚处理对象的类型比如一个专门写「批量重命名本地文件」另一个写「整理 Markdown 文档结构」边界一清二楚。技能数量增长到十几个以后建议隔一段时间回头读一遍所有 description把重叠的合并把已经废弃的删掉。元数据是每轮对话都要进上下文的留着不用的技能就是在持续消耗预算。6.2 技能变多之后先把「常用」和「备用」分开如果发现技能变多之后响应明显变慢先检查是不是所有技能都挂在默认扫描目录里。可以把低频技能挪到另一个目录只在需要时临时加进directories用完再移出去。这比调任何参数都直接。另外技能的正文别写成操作手册写清楚最小执行路径就够了。正文越长被模型读进来之后占的上下文越多留给实际任务的余量就越少。7. 配通之后下一步去哪技能加载跑通只是第一步接下来通常是三件小事。想先用同一把 Key 在不改配置的情况下试试别的模型可以打开 模型对话 发一条消息确认模型 ID 和通道都没问题日常写代码的量稳定下来之后Coding Plan 里能看清配额够不够要给别的工具或者新项目再开一把 Key直接去 控制台 API Keys 创建记得按用途命名。如果你同时在用 Claude Code环境变量那一套的对照表在 接入文档 里字段名和这里的baseURL不一样但填的地址是同一个。最后留一句提醒Agent Skills 真正的价值不在于技能数量而在于每个技能的触发条件写得够不够准。通道配好之后把精力放回 description 和正文上收益比继续加技能大得多。
TaoToken 统一接入 OpenClaw 后，Agent Skills 正常加载
OpenClaw 的 Agent Skills 最容易踩的坑不是 SKILL.md 写得不规范而是模型通道没接上——TaoToken 要解决的也正是这一段。先把结论放前面去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 拿一把 Key再把 openclaw.json 里的 Base URL 填成 https://taotoken.net/api技能才有机会被模型「看见」。很多人以为把 SKILL.md 丢进 skills 目录就算装好了其实文件只是躺在磁盘上真正决定它能不能被挑中的是模型那一侧的通道是否通、模型 ID 是否对得上。这篇文章按加载链路走一遍先拆开 SKILL.md 的两段式结构再看 openclaw.json 里那两个总要自己拼的空位最后给出可以直接抄的配置、验证方法和出错时的排查顺序。1. 把 SKILL.md 丢进目录OpenClaw 到底读到了什么1.1 frontmatter 先上场正文按需再读Agent Skills 的加载是两段式的理解这一点比记住任何配置项都重要。第一段发生在会话刚开始OpenClaw 扫描技能目录把每个 SKILL.md 顶部 frontmatter 里的name和description抽出来拼进系统上下文。第二段发生在模型决定要用某个技能之后这时候才把 SKILL.md 的正文读进来正文里写了什么命令、什么步骤、输出格式要求是什么模型此时才看得见。这个两段式设计省的是 token。二十个技能的元数据加起来可能只有几百字但二十个技能的完整正文动辄上万字全部预加载纯属浪费。代价同样明显——description 是第一段唯一的筛选依据写得含糊模型在第一步就把你排除了正文写得再工整也没有出场机会。一个能跑的 SKILL.mdfrontmatter 大概长这样--- name: weather-brief description: 查询指定城市的实时天气并给出穿衣、带伞建议。用户提到天气、气温、下雨、要不要带伞时使用。 ---正文部分建议分成三块写清楚。第一块说明触发场景用自然语言重复一遍 description 里的关键词第二块写具体怎么做把命令原样贴出来第三块写输出要求比如「两句话讲完不要罗列原始数据」。中间那块的命令块单独长这样curl -s https://wttr.in/Shanghai?format3注意这条命令是在你自己的机器上执行的网络不通、域名解析失败、命令不存在报错都会原样回到对话里。SKILL.md 本身不负责执行它只是把「该执行什么」告诉模型。1.2 技能目录的层级和文件名比内容更容易出错目录结构上OpenClaw 通常按skills/技能名/SKILL.md这一层来找。技能名建议和 frontmatter 里的name保持一致全小写、用连字符分隔避免空格和大小写混写。常见错误有三种把 SKILL.md 直接放在 skills 根目录而不是放进子目录文件名写成skill.md、SKILL.md.txt、README.md子目录名带空格或者中文。另外要注意技能目录的解析顺序。项目内的./skills和用户目录下的~/.openclaw/skills如果同时存在同名技能到底哪一份生效取决于你本地版本的实现顺序。稳妥做法是同一个技能名只保留一份改完文件后用一条明确的问句去验证不要指望「两个都放总会有一个生效」。技能数量也不用一上来就堆。先跑通一个确认链路通了再按需增加。一口气塞十个技能进去最先出问题的往往不是技能本身而是你自己都分不清是哪个环节没生效。1.3 决定加载成败的其实是模型通道文件层面全部正确之后真正的关卡才出现。OpenClaw 要把 frontmatter 元数据送进模型、接收模型返回的「要不要用这个技能」、再把技能正文送进去让模型编排步骤——这三个动作全部经过同一个模型通道。通道不通前面所有准备都是白做模型收不到元数据自然不会调用任何技能。这就是为什么很多人遇到的现象是「技能明明写对了AI 就是不用」。它不报错也不提示就是不用。因为模型压根没看到那段 description或者看到的是被截断的版本。所以排查技能加载问题顺序应该倒过来先确认模型通道是通的、模型 ID 是存在的再回头检查 SKILL.md 的写法。倒着查能省掉大量时间。2. openclaw.json 里那两个总要自己拼的空位2.1 官方示例留下的两个坑OpenClaw 的初始配置文件里model段通常是留空的或者给一个明显是占位符的值apiKey写着your-api-key-herebaseURL要么注释掉要么指向一个示例域名。官方这么做是合理的它不知道你想用哪条通道但对第一次上手的人来说这两个空位就是全部问题的来源。直接拿一个真实厂商的地址填进去又会遇到第二层麻烦模型名对不上、额度不好估算、换一个模型要改一次配置、几把 Key 分散在不同控制台里。技能这边只要动一次模型那边就得跟着动来回几次之后配置文件就变成了一团谁也不敢改的东西。2.2 TaoToken 在这条链路里只做一件事当模型通道把baseURL指向 https://taotoken.net/api 之后模型这一段就固定下来了。它是兼容通道的形式协议按 OpenAI 那一套走OpenClaw 不需要为它单独写适配器。需要换模型的时候只改model字段baseURL和apiKey都不用动。关键要说清楚的是它的边界TaoToken 只出现在模型通道这一层。SKILL.md 里的curl、wttr.in、你自己写的脚本命令一个都不用改。技能文件长什么样和你用哪条通道没有关系。有些教程会让人把命令里的地址也一起改掉那纯粹是多余的——命令是给本机执行的通道是给模型走请求的两者在不同的层上。2.3 provider 字段别乱填provider一般保持openai-compatible这一类兼容标识OpenClaw 会据此选择协议适配方式。如果你把它填成某个具体厂商的名字OpenClaw 可能去找一个不存在的适配器然后在一堆技能加载日志里报一个和模型无关的错你按技能去查会查半天。同一份配置里只保留一个 model 段。有些版本的配置文件允许定义多个 provider 再引用来引用去能用是能用但出问题时链长了两倍。单技能调试阶段一个 provider、一条 baseURL、一把 Key足够了。3. 手把手改 openclaw.json3.1 先创建 Key再动配置文件打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册登录进控制台创建一把 API Key复制出来先放在临时记事本里。同时去模型广场看一眼当前可用的模型 ID 列表把准备用的那个记下来——注意是列表里实际存在的 ID不是凭印象拼出来的名字。这里有个习惯值得养成给 Key 起一个能认出来的名字比如openclaw-dev以后在控制台看用量时能一眼分清是哪个工具在调用。Key 只在创建时完整展示后面再看就是脱敏的了复制时别多带换行和空格。准备齐三样东西就可以动手了一把 Key下文统一写成YOUR_API_KEY、一个 Base URLhttps://taotoken.net/api、一个模型 ID以模型广场当时列表为准。3.2 openclaw.json 的最小可用配置配置文件里和技能加载直接相关的其实就两块model决定技能能不能被模型看到skills决定文件从哪些目录被扫到{ model: { provider: openai-compatible, baseURL: https://taotoken.net/api, apiKey: YOUR_API_KEY, model: YOUR_MODEL_ID }, skills: { directories: [./skills, ~/.openclaw/skills] } }如果你的 openclaw.json 里已经有model段只改baseURL、apiKey、model三行即可其余字段别碰。改完保存重启 OpenClaw让配置重新加载。有一个细节必须强调baseURL只填到https://taotoken.net/api末尾不要加/v1。OpenClaw 自己会拼接后续路径你多写一层请求就打到/v1/v1/...上去报错信息里通常看不出是这里的问题。另外落地页那种带查询参数的链接是给人点的不要整串贴进配置文件配置文件里只认干净的接口地址。3.3 逐字段核对一遍再启动字段填什么常见错法model.provider兼容标识如 openai-compatible填成具体厂商名找不到适配器model.baseURLhttps://taotoken.net/api末尾多写 /v1或贴进带参数的落地页链接model.apiKeyYOUR_API_KEY留着示例占位值或复制时带了空格换行model.model以模型广场当时列表为准凭记忆写一个名字列表里根本没有skills.directories你实际的技能目录路径写成了相对路径但启动目录不对核对完这一轮再启动能省掉大部分来回。特别是最后一行./skills是相对路径它相对于谁取决于 OpenClaw 启动时的工作目录。拿不准就用绝对路径别在这种地方跟自己较劲。4. 跑起来验证技能有没有被模型挑中4.1 一条测试问句比看配置文件有用配置保存、服务重启之后别急着看日志先在 OpenClaw 里发一条明确能命中技能的问句比如「上海今天要带伞吗」。这条问句里同时出现了地点和「带伞」正好落在 weather-brief 的 description 关键词上是命中率最高的一种问法。然后看回显。理想情况是模型先说它要用天气简报这个技能接着出现一次命令执行打印出一行天气数据最后给出两句话结论。整个过程中命令是你本机跑的模型只是决定「要跑这条命令」并解读结果。反过来如果模型直接凭记忆答了一句「上海最近可能下雨建议带伞」没有任何命令执行痕迹那基本可以判定技能没被加载或没被选中。这种答法看起来像成功其实是最容易骗过自己的失败。4.2 三段链路分开判断把上面的流程拆成三段来看定位会快很多。第一段是元数据有没有进上下文把技能数量临时减到只剩一个如果这时能命中说明是技能之间互相干扰不是通道问题。第二段是通道通不通如果所有技能都不命中而且普通提问也回答得很奇怪或者干脆报错先怀疑通道。第三段是执行环节模型说要跑命令、但输出是报错那问题在命令本身跟配置无关。这三段各自独立别混在一起改。一次只动一个变量改完立刻用同一条问句复测。4.3 去控制台对一下这次调用记上账没有链路通了之后回到 TaoToken 控制台 看一下调用记录。控制台里能看到刚才那条问句产生的请求对着时间戳能确认走的就是 openclaw-dev 这把 Key。这一步的意义不在「看用量」而在于确认你改的配置真的生效了——如果记录是空的说明请求压根没发到你填的这条通道上配置文件里大概率还留着别的地方没改。顺手也能看到每次技能加载大概消耗多少 token。技能数量上来之后这部分开销会变明显元数据不是免费的值得定期看一眼。5. skills 没动静的时候按这个顺序查5.1 文件层面目录、文件名、frontmatter先确认三件事SKILL.md 在不在skills/技能名/这个层级里文件名是不是全大写的SKILL.mdfrontmatter 有没有用三条短横线正确包起来。frontmatter 里如果name和description有一项缺失元数据就是空的模型看到的是半截信息行为会变得很随机——有时用有时不用最难查。5.2 触发层面description 写得太宽或者太窄太宽的写法长这样「帮助用户处理各种日常问题」。这句话放进上下文里几乎是噪音模型无法判断什么时候该用它。太窄的写法是只写了一个生僻关键词用户的自然问法根本碰不到。一个实用的写法是把 description 写成「做什么 什么时候用」两段前半句说能力后半句列出用户可能说的几个词。上面那个天气技能就是这么写的命中率明显比只写「查天气」高。5.3 通道层面Key 和 Base URL 先各看一眼所有技能同时失效而且普通对话也开始报鉴权相关的错那就是通道层。先确认apiKey不是官方示例里的占位值再确认baseURL是https://taotoken.net/api而不是别的地址、也没多写/v1。最后核对模型 ID模型名不存在时报错通常很模糊容易误判成技能问题去模型广场对一遍就能排除。5.4 执行层面命令报错就贴回对话不要在配置里找原因如果模型确实调用了技能但命令输出是command not found、超时、或者返回一段 HTML 错误页这跟 openclaw.json 没有任何关系。把你本机的报错原样贴回对话让模型下一步去换命令或者换参数。SKILL.md 里的命令写的是你本机环境的事实环境不对改配置文件是解决不了的。6. 多技能共存时别让 SKILL.md 互相打架6.1 description 之间要有清晰边界两个技能的 description 都提到「文件」这个词模型在选择时就会摇摆有时选 A、有时选 B、有时两个都调用一遍。这种问题不会报错只会让输出变得不稳定。解决办法是在描述里写清楚处理对象的类型比如一个专门写「批量重命名本地文件」另一个写「整理 Markdown 文档结构」边界一清二楚。技能数量增长到十几个以后建议隔一段时间回头读一遍所有 description把重叠的合并把已经废弃的删掉。元数据是每轮对话都要进上下文的留着不用的技能就是在持续消耗预算。6.2 技能变多之后先把「常用」和「备用」分开如果发现技能变多之后响应明显变慢先检查是不是所有技能都挂在默认扫描目录里。可以把低频技能挪到另一个目录只在需要时临时加进directories用完再移出去。这比调任何参数都直接。另外技能的正文别写成操作手册写清楚最小执行路径就够了。正文越长被模型读进来之后占的上下文越多留给实际任务的余量就越少。7. 配通之后下一步去哪技能加载跑通只是第一步接下来通常是三件小事。想先用同一把 Key 在不改配置的情况下试试别的模型可以打开 模型对话 发一条消息确认模型 ID 和通道都没问题日常写代码的量稳定下来之后Coding Plan 里能看清配额够不够要给别的工具或者新项目再开一把 Key直接去 控制台 API Keys 创建记得按用途命名。如果你同时在用 Claude Code环境变量那一套的对照表在 接入文档 里字段名和这里的baseURL不一样但填的地址是同一个。最后留一句提醒Agent Skills 真正的价值不在于技能数量而在于每个技能的触发条件写得够不够准。通道配好之后把精力放回 description 和正文上收益比继续加技能大得多。
详解：核心公式、Python实现与工程调参指南)
