按域拆 Reference 的 Skill 结构

它替你干掉什么：整份 schema 常驻 context 的税

官方写死的三条加载规则

Skill authoring best practices 的 Runtime environment 一节列了三条，是这套结构全部的经济学依据：① Metadata pre-loaded——启动时只有所有 skill 的 name 与 description 进系统提示；② Files read on-demand——相关了才读 SKILL.md，其余文件再按需读；③ No context penalty for large files，原话是 Reference files, data, or documentation don't consume context tokens until actually read.

装法：四个加载位置，挑一个

# 个人级：本机所有项目可见
~/.claude/skills/<skill-name>/SKILL.md
# 项目级：随仓库走，能进 git（团队共享口径就用这个）
.claude/skills/<skill-name>/SKILL.md
# 插件级：调用时带命名空间 /plugin-name:skill-name
<plugin>/skills/<skill-name>/SKILL.md
# 子目录级：在 <subdir> 或其下启动的会话才加载
<subdir>/.claude/skills/<skill-name>/SKILL.md

# 想先看现成的（19 个官方 skill 全在里面）
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

第一条立刻能跑的用法：照抄官方 Pattern 2

官方 best-practices 里的 Pattern 2: Domain-specific organization 给了一个 bigquery-skill 的骨架，原样可用：SKILL.md 加一个 reference/，里面 finance.md / sales.md / product.md / marketing.md 四份。SKILL.md 正文只放三种东西——一句话说这个 skill 管什么、一张按域路由的表、一条 grep 提示：

mkdir -p .claude/skills/warehouse/reference

# SKILL.md 里的路由表，官方原样：
**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)

# 以及一条 quick search 提示，让它自己捞：
grep -i "revenue" reference/finance.md

口径规则写进对应那份域文件，不写进 SKILL.md——官方举的例子正是「always exclude test accounts」这类规则，它属于哪个域就落在哪份里。什么时候别拆：SKILL.md 还没到 500 行、只有一个域、或者域之间强耦合（问 A 必然要读 B）——拆了只是多一跳。官方那条界线写得很硬：Keep SKILL.md body under 500 lines... Split content into separate files when approaching this limit.

机制：SKILL.md 是目录页，文件系统是索引

四个官方 skill 的真实目录，摊开看

三种路由写法，都能在上面这几个里读到原文

1. 按任务路由——claude-api 的 Reading Guide：先读 {lang}/claude-api/README.md，然后按任务加料——Chat UI 加 streaming.md，tool use 加 shared/tool-use-concepts.md + {lang}/claude-api/tool-use.md，缓存读 shared/prompt-caching.md，省钱读 shared/cost-optimization.md。
2. 按条件路由——mcp-builder：同一步里分叉，选 TypeScript 读 ./reference/node_mcp_server.md，选 Python 读 ./reference/python_mcp_server.md；而 mcp_best_practices.md 与 evaluation.md 是无条件读的。条件路由的价值在于「不该读的那份连名字都不会被展开」。
3. 按域路由——官方 Pattern 2 的 bigquery 例：finance / sales / product / marketing 四份，问哪个域读哪份。上一期说的口径问题，落点就在这一格。

两条硬约束，都是为了对付「预览式读取」

• 引用只能一层深。SKILL.md → advanced.md → details.md 这种链条，官方明说模型可能只用 head -100 预览而不是整份读，结果是残缺信息。所有 reference 都要从 SKILL.md 直接链过去。
• 超过 100 行的 reference 顶部要放目录。理由同上：即使只被预览，也得让它看得见全貌。

真实用法与边界：schema 和口径到底写在哪一层

三层落位

• SKILL.md（每次触发全读）：只放必须无条件生效的东西——一句话定位、路由表、最多两三条跨域硬规矩。官方那条 always exclude test accounts 就属于这里，因为它对 finance 和 sales 同时成立。
• reference/<域>.md（按需读）：表名字段、指标定义、口径边界、常用查询模板。skill-creator 把 schema 单独拎成 references/schemas.md，就是这一格的官方示范。
• scripts/（执行，不进 context）：能写成校验的别写成叮嘱。官方原话：Only the script's output consumes tokens. docx 把 XSD 校验、run 合并、接受修订全做成了 scripts/ 下的脚本，一份 .md 都没拆。

三条判据，用来在上面四档之间取舍

1. 域之间会不会被同时问到？会 → 别拆，拆了每次都要读两份还多一跳。不会 → 按域拆。这正是 claude-api 把 shared/ 和语言目录分开的理由：问 Python 的人不需要 Ruby 那 8 份。
2. 有没有第二根轴？只有「主题」一根 → reference/ 平铺就够，mcp-builder 四份到顶。主题 × 语言、或主题 × 环境两根都在 → 才值得做成 claude-api 那样的矩阵。两轴的代价是路由表必须写成 {lang}/xxx.md 这种带占位符的模板，人读着累、改起来更累。
3. 这份文件会过期吗？会 → 在文件里标日期。claude-api 的 SKILL.md 把模型与定价表标成 as of 2026-06-24，是本期最该抄走的一个小动作：volatile 的内容自己声明保质期，别让读者替你猜。

什么时候这套不成立

• 只有一个域、SKILL.md 三百行以内：docx / xlsx / pptx / web-artifacts-builder 四个官方 skill 至今都是 SKILL.md + scripts/，没有任何 .md 被拆出来。别因为「官方都拆」而拆——官方一多半没拆。
• 靠 grep 捞域文件的话，先确认环境里有 bash。官方 Pattern 2 的 quick search 就是一行 grep -i "revenue" reference/finance.md，没有 shell 就退化成整份读。
• 打包给 API 用要多看一眼：官方明说 Claude API 环境无网络、不能运行时装包，scripts/ 依赖的东西得预先在那儿；claude.ai 才能从 npm / PyPI / GitHub 拉。

代价与替代品：拆出来的每一份，都新增一条要维护的路由行

三笔账

• 维护面：n 份 reference = n 条路由行 + n 个可能写错的相对路径。上一节那个 FORMS.md / forms.md 就是这笔账的实例。
• 沉默失效：拆了但 SKILL.md 里没指，或者指得太含糊（「详见参考资料」），模型不会去读也不会报错——你只会觉得这个 skill「时好时坏」。官方给的检验办法是看行为：某份 bundled 文件如果从来没被访问过，它要么多余、要么在 SKILL.md 里没被好好信号化。
• 预览损耗：一层深和 100 行目录这两条不是洁癖。模型会用 head -100 预览，深链 + 无目录的长文件 = 读到一半的 schema，这比没读到更危险——半份口径不会触发任何怀疑。

不拆的话，你还能怎么办

1. 就不拆。单文件跑到 500 行再说。官方 template/ 至今只有一个 SKILL.md，起手式本来就是这样。
2. 把口径放进 CLAUDE.md。代价是无条件常驻，每个会话都付这笔 token；只适合真的每次都用得上的两三条。
3. 让 schema 走 MCP，别走文件。表结构由 server 现查现给，永远不会过期；代价是每问一次都要一轮工具调用，且多一个 context 税源（见本站 Skill 9 与 Skill 22）。
4. 给每个域开一个 subagent。上下文隔离更彻底，协调税更高——这条留到 Skill 26 展开。