编写或重构 Claude 技能时如何决定 SKILL.md…

当创建新技能、重构旧技能，或 SKILL.md 超过 300-400 行、不确定内容该放哪里时，用来判断是否拆分以及如何拆分文件以节省上下文并保证可靠加载。

适用场景

解决思路

1. 先区分两类问题：触发问题（技能是否被调用，完全由 YAML description 决定，与文件拆分无关，应改用 skill-creator 的 run_loop.py 修 description）与渐进披露问题（技能激活后加载什么内容）。若用户因触发问题而想拆分文件，先指出这个混淆并重定向。
2. 默认不拆分：单体 SKILL.md 在未被证明更差之前优于拆分版。仅当满足以下之一才拆分：SKILL.md 超过约 400 行且内容有自然分支；有实测证据（eval 记录）显示模型浪费上下文在无关章节；某内容体积大且只在狭窄条件下需要。
3. 选择拆分轴一：变体分支。SKILL.md 放决策逻辑与共享流程，每个 references/<variant>.md 放该路径专属细节（如云厂商、数据库引擎、框架、输出格式、语言）。适用于用户意图恰好选中一条路径的情况。
4. 选择拆分轴二：流程 vs 参考数据。SKILL.md 放过程（动词、顺序、决策），references/ 放按键查询的查找材料（schema、错误码表、API 清单、示例库、配置矩阵、设计 token）。这是杠杆最高的拆分。
5. 选择拆分轴三：深度分层（常见路径 vs 边界情况）。SKILL.md 覆盖 80% 常见情况，references/edge-cases.md 覆盖其余，指针必须写成“若出现 X、Y 或 Z，停下并先读 references/edge-cases.md 再继续”。
6. 避免无效拆分：不要按主题拆（真实任务跨 2-3 个主题会强制多次加载）；不要为凑行数目标而拆（无分支条件时引用会并行或总是加载，毫无节省）；不要把罕见但关键的内容放进 references/（引用是可选的，模型可能跳过，关键内容必须留在 SKILL.md）；不要做装饰性拆分（Examples、Notes、Tips 文件没有加载条件，要么总是加载浪费调用，要么永不加载成为死内容）。
7. 遵守指针卫生：指针就是完整的加载契约。要写出触发加载的用户可见信号（如“若用户提到快照测试”而非“关于测试”）；每个指针一句话，不要在 SKILL.md 里总结引用内容；把加载条件编码进文件名（如 go126-simd.md 而非 advanced.md）；超过 300 行的引用加文件顶部目录；若两个引用在多数运行中同时加载则合并。
8. 确定性任务优先用 scripts/ 而非 references/：格式化、校验、schema 生成、文件转换、重正则解析等应写成脚本，执行时零上下文成本、可重复、可单测、可复用。
9. 拆分前回答决策清单：1) 该内容是否有模型能从用户输入检测到的清晰可观察加载条件？2) 拆分是否真的减少上下文（计入 SKILL.md 新增的路由文字）？3) 这是查找数据还是过程内容（过程内容通常留在 SKILL.md）？4) 能否用脚本确定性处理？5) 在真实调用中该文件被加载的比例是多少——低于 20% 就内联或删除，20–80% 是拆分甜区，高于 80% 就提升进 SKILL.md。若第 1 题答案不清晰，就不要拆。
10. 做架构评估（区别于输出评估）：输出评估问“是否产出正确结果”，架构评估问“是否以可接受成本为正确理由加载了正确文件”。两者用同一套 harness 但指标不同，都要跑；输出质量是底线，架构是之上的优化。
11. 为架构设计 eval 集：每个声明的变体一条查询、每个边界分支一条、每个主要查找类别一条、一条只走常见路径且零引用加载的查询、2-3 条不应触发技能的离题查询（同时测 description）。若没有真实查询能触发某引用文件，该文件就是死的，先内联或删除再跑。
12. 做插桩：每次 eval 由加载了技能的子代理执行，记录完整 transcript（含每次工具调用）、读取了哪些 references/* 文件（解析对技能目录内路径的 view 调用）、是否调用了 scripts/*、总 token 与墙钟时间、输出。每次运行持久化为 transcript.json 和 loads.json，并扩展 skill-creator harness 的评分步骤从 transcript 提取引用加载。
13. 按引用文件统计指标：加载率（被读取的运行占比）、共现率（与每个其他引用同时加载的运行占比）、加载后使用率（加载的运行中内容是否明显影响输出——引用内容、应用流程、使用 schema，需查 transcript）、重读率（同一次运行中重复加载同一文件的占比）。
14. 按技能整体统计指标：每次调用的 token 中位数与 p95（含与不含引用）、SKILL.md 利用率（读 transcript 找出任何运行中模型从未引用的章节，是删除的强候选）、路径覆盖率（每条声明路径是否至少被一条查询命中）。
15. 按决策规则行动：引用加载率 <20% → 内联进 SKILL.md 或删除；20–80% → 保持拆分；>80% → 提升进 SKILL.md；两个引用共加载 >70% → 合并；引用被加载但未用于输出 → 修或删 SKILL.md 中的指针；同一次运行内重读 → SKILL.md 路由不清，需澄清；无查询触发某引用 → 删除；SKILL.md 某章节从未被引用 → 删除。阈值按成本画像调整，小引用可容忍更低加载率。
16. 比较两套架构时：对两版跑相同 eval 集；两版都跑输出质量 eval 确认无回退（若质量下降则架构改动失败，无论省多少 token）；比较 token 中位数、p95 与时间中位数；比较路径覆盖率。省 15% token 但增加输出方差的拆分不如单体——可靠性优先于效率。
17. 注意指标无法告诉你的：SKILL.md 文字是否清晰（需读 transcript 找困惑的工具调用与死胡同）、description 是否触发正确（这是单独的 eval）、内容放置是否符合用户心智模型（主观，需人工评审）。设计时看起来干净的拆分很少匹配真实加载模式，信 transcript 而非直觉。
18. 给出建议时的输出流程：1) 先诊断是触发问题还是披露问题；2) 引用现有 SKILL.md 的相关内容再给建议；3) 提出最小可行拆分，抵制拆成过多文件；4) 为每个拟建引用文件写出将放入 SKILL.md 的确切指针句；5) 明确呈现权衡（用本技能的正反列表作为呈现范式）；6) 若不确定拆分是否有帮助，先建议插桩（跑 eval、读 transcript）再决定。

适用边界 · 注意事项

• 当问题其实是技能触发不可靠时——那是 description 的问题，拆分文件无济于事，应改用 skill-creator 的 run_loop.py 修 description。
• 当内容没有清晰可观察的加载条件时——不要拆分，否则引用要么总是加载（浪费）要么永不加载（死内容）。
• 当内容罕见但关键时——引用按设计是可选的，模型可能跳过；这种情况通常说明技能在做两件事，应拆成两个技能而非拆文件。