你装的 skill，Claude Code 可能就看不到

公众号名称：AI 方寸山

作者名称：问答

发布时间：2026-05-15 09:07

昨晚打开 Claude Code，准备继续写公众号文章采集的 Skill。

看到了下边的一行提示：「74 skill descriptions dropped · /doctor for details」。

我装的 skill 总共 90 几个，74 个用不上？

这行字我看见快一周了，因为是闪现，每次也不在意，但是一些自己快遗忘的 Skill 感觉像消失了一样，是这个的影响？

所以，就一探究竟了下，结果收获不小。

这是 Claude Code 一个挺隐蔽的机制：它会悄悄关掉一部分 skill 的「自动触发」。skill 文件还在磁盘上，目录结构和配置一个字都没动，但 Claude 已经不知道它们存在。

更让我好奇的是，跑完 /context 看了一眼，上下文还剩 72% 没用。

Claude 装得下。只是默认预算只给了 1%。

/doctor 现场：1% 的预算

/doctor 是 Claude Code 自带的诊断命令。一跑就把刚才那行省略号补全了：

Skill listing will be truncated
74 descriptions dropped (full descriptions kept for most-used skills) (2.8%/1% of context):
dbs-agent-migration, agent-browser, lark-event, +71 more

两个数字最扎眼：2.8% 是我实际占用，1% 是 Claude Code 给的预算上限。超出了将近三倍。

被砍掉的 skill 明明白白列出来一部分：dbs-agent-migration、agent-browser、lark-event 是我能看见的，后面还有 71 个。这些 skill 全都在 .claude/skills/ 目录里好端端待着，目录名、SKILL.md、description 一个字都没动。但在这一次会话里，Claude 就是当它们不存在。

提示下面还有一行小字：「Opting in would cost ～6k tokens for skills every session and uses rate limits faster」。意思是说，我要是想把它们都装回来，得为每次会话多付 6k tokens，还会让我 Claude Pro 的额度用得更快。

这行小字暂时记着，后面回来算这笔账。

关键反差：Context 还剩 72%

按理说，2.8% 这个数字本身不算多，上下文都还有大半空着，多塞一点描述也无妨。

于是我跑了一下 /context 看总占用：

整个会话用了 22.3k / 200k tokens，Free space 还剩 144.7k，占 72.3%。Skills 这一项自己才占 5.6k。

我对着这个数字盯了几秒。

Claude 装得下。被锁住的是 description 预算，默认 1%。

也就是 skill 的预加载的 description 有个总空间大小的限制，超过了就会被截断省略，从而无法自动被模型识别。因为触发词没加载。

skill description 是一个节省上下文的策略。199K 的剩余上下文跟它没关系，它能用的就那 2000 tokens。

机制：skill listing budget 是什么

要理解这个 1% 是怎么用的，得先看 Claude Code 怎么”看见”你的 skill。

每次会话启动时，Claude Code 会扫描你所有装好的 skill，把每个 skill 的 description 字段（是什么，何时用）拼成一个大列表，塞进 Claude 的系统提示里。这份列表干一件事：让 Claude 知道你装了哪些工具、什么场景该用哪个。

你问它一句话的时候，Claude 不是凭空找工具。它在这份系统提示里翻一遍，看你的请求匹配上哪个 skill 的 description，然后决定要不要自动调。

skill 的「自动触发」能力，完全建立在 description 被 Claude 看见的前提上。

但这份列表的总长度有上限：skillListingBudgetFraction，默认 0.01，也就是上下文窗口的 1%。

折算到不同模型：

200K 上下文的 Sonnet / Opus：1% ≈ 2000 tokens。装到大概 15-25 个 skill 就开始触顶
1M 上下文的 Opus / Sonnet：1% ≈ 10000 tokens。要装到 75-125 个才触顶

我用的是 Sonnet 4.6 + 200K 上下文，装了 90 多个 skill，按这个公式，超额是必然的。

超额之后 Claude Code 不会报错。它的处理挺简单粗暴：给所有 skill 按使用频率（大致是这个，官方没有公布细节）排个序，从最少用的开始砍 description。砍的时候只砍描述这一段，skill 的名字还留着，你想手动 /name 调出来还是能调。

这个设计不奇怪，就是为用户兜底，避免大家装了一堆 Skill，忘记了，还天天无效加载到上下文。

后果实证：dropped 后到底失去了什么

搞清楚机制之后，我直接问了 Claude 一个问题：「skill description 被丢弃之后，到底意味着什么？」

它的解释（我 cross-check 了官方文档，对得上）：

情况	Claude 看到的	影响
描述被保留	skill 名字 + 描述	能根据上下文自动识别该用哪个 skill
描述被丢弃	只看到 skill 名字	看不到触发词，无法自动匹配。用户显式 `/skill-name` 仍然有效

翻译成直白话：我装了 90 多个 skill，Claude 每次会话只「能看见」其中 20 个左右。剩下 70 个等于躺在仓库里，得我自己开口叫名字才能用。

这就解释了我之前一直困惑的事。

我装的 sub-agent-driven 今年用过几次，效果不错。但它属于「偶尔用一次」的类别。大部分时间我在写文章，用不上它。结果就是：它早就被排到 dropped 队列里。

前两周月做项目结构调整的时候，按 description 设计这种场景应该会触发 sub-agent-driven 给我建议。但 Claude 从来没主动叫过它。

我以为是 description 没写好。后来才知道，是 Claude 压根没看见。

排查神器：/context 看 skill 明细

搞清楚机制，下一个问题是：到底哪 74 个 skill 被砍了？

/doctor 给的列表是省略的：「dbs-agent-migration, agent-browser, lark-event, +71 more」。前三个是字母序，剩下 71 个被一笔带过。光看 /doctor 没办法知道哪些是半死不活、哪些已经被砍干净。

后来发现 /context 有个更精细的视图，可以看到每个 skill 各占多少 token：

Skills · /skills
Project
  web-reader: ～110 tokens
  translator: ～100 tokens
  markdown-to-wechat-html: ～100 tokens
  ...
  insight-synthesizer: ～40 tokens
  ...

看这个数字基本就能判断 skill 的健康状态：

70-110 tokens：description 完整加载，自动触发正常
～40 tokens 左右：description 被截短，触发词可能不全
< 20 tokens：几乎只剩名字，自动触发基本失效

实操就一招：跑 /context，把 skill 按 token 从小到大排，< 40 的那一批就是「装了等于半装」。

我自己扫了一遍，发现一些常用工具其实也快被砍。比如几个 lark-* 系列的飞书工具，平时确实会用，结果掉到 30 多 tokens 那一档，触发已经不稳了。

6 种解决方案，按推荐度排序

找到问题之后，是清单。我整理了 6 种解决方案：

推荐度	方法	成本	适用
⭐⭐⭐	`/skills`手动禁用低频 skill	零 token	通用首选
⭐⭐⭐	压缩 description 到 100-150 字符	零 token	自己维护的 skill
⭐⭐	`skillOverrides`改可见性	零 token	不想改第三方源码
⭐⭐	提高 `skillListingBudgetFraction`	每会话 +3k-6k tokens	50+ skill 重度用户
⭐	`SLASH_COMMAND_TOOL_CHAR_BUDGET`环境变量	同上	一次性脚本
⭐	调大 skillListingMaxDescChars	同上	description 真需要长

前两种零成本，最值得说。

第一种：跑 /skills 把不常用的禁用掉。 交互式选择器，光标移到对应行按空格切换状态（on / name-only / user-invocable-only / off），回车保存。把日常基本不用的整批切到 off，预算立刻松出来。

这招最有用的地方在于它逼你回答一个问题：这个 skill 我上次用是什么时候？装的时候每个都觉得”将来肯定用得着”，过半年回头看，七八成根本没碰过。

第二种：压缩 description 字段。 Anthropic 文档的建议是把 description 总长压到 100-150 词，关键词前置。380 字的营销腔写法会把关键词埋在末尾，截断时直接砍掉。110 字的密集型写法动词前置，关键词全在前 50 字。同样的预算能装更多 skill，token 效率上去后命中率也跟着涨。

第 3-4 种（skillOverrides 和调高 budget）后面单独说。第 5-6 种平时用不上，跑批脚本或者非得写长 description 才碰。

克制原则：调 budget 不免费

回到那行小字：「Opting in would cost ～6k tokens for skills every session and uses rate limits faster」。

要是你装了 50+ skill 还是不想清理，直接调高 budget 是最快的解法。改一下 ～/.claude/settings.json：

{
  "skillListingBudgetFraction":0.02
}

注意小数格式，0.02 表示 2%，不是数字 2。改完重启 Claude Code 才生效。

但这一招的代价 /doctor 已经写在脸上了：每次会话多花 6k tokens。在 200K 上下文模型里相当于多吃了 3% 的空间，更现实的影响是 Claude Pro 的额度用得更快。

我跑了一下，调到 0.02 之后 dropped 数量明显下降，具体降了多少没仔细数，但感受上就是少了一截。

跑了几个会话之后我换回去了。这一招不免费。本来是每次会话浪费点描述空间，现在变成每月 Claude Pro 额度被多吃。两害相权，前者还好挽回，清理一遍 skill 就行。后者每个月都要付一次。

档位推荐：

0.01（默认）：< 20 个常用 skill 够用
0.02：20-50 个 skill 且半数常用
0.03：50+ skill 且确实需要广覆盖
大于 0.05：不推荐，这时候该回去清理 skill 了，不是堆预算

一个判断信号：调到 0.03 还在 dropped，说明 skill 装臃肿了，不是预算问题。回头看看你那 50 个 skill 里，过去半年真正用过的有几个。

我自己的方案

我没去调 budget。

先做的是清点。/context 列出来的 skill 按 token 从小到大一拉，那批 < 40 tokens 的就是「半装」状态。我装的 skill 里掉到这一档的有四五十个。

然后跑 /skills 进交互界面，把半装区里过去半年没动过的整批切到 off。能这么砍掉的有 30 多个，大部分是当初看到别人 GitHub 上有就 clone 下来、想着”以后可能用”的实验性工具。半年回头一看，确实一次没碰。

剩下的 skill 里又翻出几个 description 写得太啰嗦的。打开它们的 SKILL.md，把 description 压到 100 字符以内，关键词全往前挪。

还有一类比较尴尬：飞书的 lark-* 系列。日常用得少，但偶尔要发个会议总结、查个考勤。这种直接 off 太狠，要用还得手动开。我后来用 skillOverrides 把它们设成 name-only：

{
  "skillOverrides":{
    "lark-attendance":"name-only",
    "lark-okr":"name-only"
  }
}

Claude 看到名字但不加载描述。这样 token 零开销，要用的时候手动 /lark-attendance 也能调出来。

调完跑了一遍 /doctor。Skills 类目从 5.6k 掉回 3k 不到，预算占用 2.8% 回到 1.4%。还是超 1%，但常用工具的描述至少不再被砍了。

最后

装一年多 Claude Code，今天才知道还有这么个机制。

写 skill 的时候每个都想着”以后可能用得着”。但 description 是要占预算的，装得越多，常用那批反而越容易被挤掉。

如果你装了很多 skill，但 Claude Code 总是不主动调用，先别急着骂 description 写得烂。它可能根本没读到。

打开你自己的 Claude Code 跑一下 /doctor 和 /context 看看。说不定能每天加个鸡腿呢。

感谢您阅读到这里。

cover_image

Original 问答 AI 方寸山

内容效果不满意？点此反馈