Claude Code Skills 描述被截断：1536 字符上限和共享预算机制解析
Claude Code 加载 skills 时有两道独立的字符限制：每条 skill 描述上限 1536 字符，所有 skills 合计不超过上下文窗口的 1%。触发任一限制，描述会被截断或整条被丢掉。本文讲清楚原因、诊断方法和修复思路。
你写了一个 Claude Code skill，触发描述很详细，但 Claude 老是无法正确触发它——问题可能不是 Claude 的理解能力，而是你的描述根本没完整进入上下文。Claude Code 对 skills 的描述加载有两道独立的字符限制，任何一道触发，描述都会被静默截断或整条丢弃。
两道独立的加载限制
第一道：单条 skill 描述上限 1536 字符
每个 skill 的 description + when_to_use 两个字段合计不能超过 1536 字符。超出的部分被截断，Claude 看到的是残缺的描述。这个上限通过两个设置项控制（两个官方来源对设置项名称有分歧）：
- 文档里叫
skillListingMaxDescChars - 已发布设置 schema 里叫
maxSkillDescriptionChars - 默认值：1536
第二道：所有 skills 共享的列表预算
Claude Code 给所有 skills 列表分配了固定的上下文窗口比例，默认是 1%，有文档注明的字符兜底是 8000 字符。当所有 skills 的描述加起来超出这个预算时，Claude Code 会从调用频率最低的 skills 开始删除描述——保留的只有名字，没有触发说明。调用频率最高的 skills 保持完整；长尾里的 skills 变成无法被触发的裸名。
这个共享预算通过 skillListingBudgetFraction 控制，默认 0.01（即 1%）。
如何判断你的 skill 是否被截断
步骤一：运行 /doctor
/doctor 是 Claude Code 的内置诊断命令，会显示当前列表是否超出预算、有没有 skills 被降级为裸名。这是最快速的诊断入口，先跑它再做其他操作。
如果 /doctor 显示列表超出预算，先解决预算问题再检查单条 skill 的截断。
步骤二：检查单条 skill 的长度
在 terminal 里运行：
# 统计 skill 描述的字符数（description + when_to_use 两个字段）
wc -c your-skill/SKILL.md
更精确的方式是只统计 frontmatter 里的 description 和 when_to_use 字段内容，而不是整个文件。如果两个字段合计接近或超过 1536 字符，截断就在发生。
步骤三：单独读第一句话
单独看描述的第一句话，问：这一句话能让 Claude 从一个用户请求里找到这个 skill 的触发场景吗？如果第一句是名词短语（"SQL 助手"）而不是任务描述（"读取 SQL 文件并提出索引优化建议"），Claude 没有足够的信号来匹配。这是截断之外的另一类常见问题。
描述被截断的修复方向
针对单条 skill 超 1536 字符的修复：
把描述里的"教程"部分移出去。触发描述的核心功能是让 Claude 在接收到用户请求时决定调用哪个 skill——它不需要完整的使用手册，只需要一个能被匹配的任务描述。
优先保留：
- 这个 skill 解决什么问题（一句话）
- 何时应该调用（触发场景，3-5 条）
- 明确的"不要在以下情况调用"（避免误触发）
可以移出去的：
- 详细的使用步骤（放进 skill 的 body 里）
- 背景说明和上下文历史
- 示例输出
针对共享预算超限的修复：
删除不再使用的 skills。6 个月没被调用过的 skill，即使保留了描述也没有贡献，但它在每次 session 启动时都占着预算。/doctor 的输出里会显示调用频率，找出最低频的先删。
调整 skillListingBudgetFraction。在 Claude Code 的配置里把这个值从默认 0.01 提高，比如改成 0.02。这会给列表分配更多上下文比例，但同时会减少其他功能可用的上下文空间。适合 skills 数量多、其他上下文需求相对少的场景。
描述写法的实质影响
Claude Code 加载 skills 的方式决定了描述是一个过滤器，而不是一份说明书。Claude 在每个 turn 开始时扫描所有 skills 的名字和描述，决定当前用户请求是否应该触发某个 skill。这个决策是基于描述文本和用户请求的语义匹配。
后果：
- 描述里的第一句是最重要的——如果被截断，第一句仍然保留
- 触发场景的措辞要和用户实际输入的语言接近，不要用过于技术化或内部的说法
- "何时不调用"的说明和"何时调用"同样重要，它防止误触发把 skill 用在不对的场景
常见问题
问：1536 字符是含还是不含 frontmatter 的其他字段？
答：只计算 description 和 when_to_use 两个字段的内容，不含 name、tools、model 等其他 frontmatter 字段，也不含 skill 的正文（skill body，即 frontmatter 之后的部分）。
问：/doctor 说列表超预算了，但我只有 5 个 skills，怎么会超？
答：有可能每个 skill 的描述都比较长，5 个 × 1500 字符 = 7500 字符，接近默认的 8000 字符上限。检查每个 skill 的描述长度，把最长的那几个缩减。
问：能否把描述写成英文来节省字符数？ 答：英文描述在字节数上更紧凑（英文字母是单字节，中文汉字是多字节），但 1536 字符的限制是按字符计，不是按字节——所以中英文的字符数是一样的。不过英文描述确实更简短、意思更密集，如果主要用于英文工作流，切英文描述是有价值的。
问：描述被截断后，skill 还能用吗？ 答：能，但只有完整触发条件的前半部分会被 Claude 看到。如果关键的触发场景描述在末尾（超过 1536 字符的部分），Claude 就不会知道在那个场景下应该调用这个 skill，表现为"在正确场景下没有被自动触发"。