Domain-Split Reference Structure

What it kills for you: the tax of a whole schema resident in context

Three loading rules the docs pin down

The Runtime environment section of Skill authoring best practices lists three, and they are the entire economic case for this structure: (1) Metadata pre-loaded — at startup only every skill's name and description enter the system prompt; (2) Files read on-demand — SKILL.md is read once the skill is relevant, everything else only as needed; (3) No context penalty for large files, verbatim: Reference files, data, or documentation don't consume context tokens until actually read.

Install: four loading locations, pick one

# Personal: visible to every project on this machine
~/.claude/skills/<skill-name>/SKILL.md
# Project: travels with the repo, can be committed (use this to share definitions)
.claude/skills/<skill-name>/SKILL.md
# Plugin: invoked namespaced, as /plugin-name:skill-name
<plugin>/skills/<skill-name>/SKILL.md
# Nested: loads only in sessions started in or below <subdir>
<subdir>/.claude/skills/<skill-name>/SKILL.md

# To read the shipped ones first (all 19 official skills are in here)
/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

The first usage you can run today: copy official Pattern 2

Pattern 2: Domain-specific organization in the best-practices page ships a bigquery-skill skeleton you can use as-is: a SKILL.md plus a reference/ holding finance.md, sales.md, product.md and marketing.md. The SKILL.md body carries three things only — one line on what the skill covers, a routing table by domain, and a grep hint:

mkdir -p .claude/skills/warehouse/reference

# The routing table inside SKILL.md, exactly as the docs write it:
**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)

# Plus a quick-search hint so it can fish for itself:
grep -i "revenue" reference/finance.md

Metric rules go into the matching domain file, not into SKILL.md — the docs' own example is a rule like "always exclude test accounts," which lands in whichever domain owns it. When not to split: SKILL.md is still short of 500 lines, there is only one domain, or the domains are tightly coupled (asking about A always requires B) — splitting then only adds a hop. The official line is hard: Keep SKILL.md body under 500 lines... Split content into separate files when approaching this limit.

Mechanism: SKILL.md is the table of contents, the filesystem is the index

Four official skill directories, laid side by side

Three ways to route, each readable in the files above

1. Route by task — the Reading Guide in claude-api: start at {lang}/claude-api/README.md, then add per task — a chat UI adds streaming.md, tool use adds shared/tool-use-concepts.md plus {lang}/claude-api/tool-use.md, caching reads shared/prompt-caching.md, cost work reads shared/cost-optimization.md.
2. Route by condition — mcp-builder: the same step forks, TypeScript reading ./reference/node_mcp_server.md and Python reading ./reference/python_mcp_server.md, while mcp_best_practices.md and evaluation.md are read unconditionally. The value of conditional routing is that the file you should not read never even gets named.
3. Route by domain — the bigquery example under Pattern 2: finance, sales, product, marketing, and you read the one you were asked about. The definitions problem from the last issue lands exactly in this slot.

Two hard constraints, both aimed at preview-style reads

• References may be one level deep only. For a chain of SKILL.md to advanced.md to details.md, the docs say outright that the model may preview with head -100 rather than reading the whole file, and the result is incomplete information. Every reference should link directly from SKILL.md.
• A reference over 100 lines needs a table of contents at the top. Same reason: even a partial read should show the full scope of what is in there.

Real usage and limits: which layer schemas and definitions actually belong in

The three layers

• SKILL.md (read in full on every trigger): only what must apply unconditionally — one line of positioning, the routing table, and at most two or three cross-domain hard rules. The docs' own always exclude test accounts belongs here precisely because it holds for finance and sales alike.
• reference/<domain>.md (read on demand): table and field names, metric definitions, the edges of each definition, common query templates. skill-creator pulls schemas out into references/schemas.md, which is the official demonstration of this slot.
• scripts/ (executed, never loaded): anything that can be a check should not be a reminder. Verbatim: Only the script's output consumes tokens. docx turns XSD validation, run merging and accepting tracked changes into scripts under scripts/ and splits out no .md at all.

Three criteria for choosing among the four shapes

1. Do the domains get asked about together? If yes, do not split — you would read both files every time and add a hop. If no, split by domain. This is exactly why claude-api keeps shared/ apart from the language directories: someone asking about Python has no use for the eight Ruby files.
2. Is there a second axis? One axis, topic only, and a flat reference/ is enough — mcp-builder tops out at four files. Two axes present, topic by language or topic by environment, and only then is a claude-api-style matrix worth it. The cost of two axes is that the routing table has to be written with placeholders like {lang}/xxx.md, which is harder to read and harder still to change.
3. Will this file go stale? If yes, date it inside the file. The claude-api SKILL.md marks its model and pricing table as of 2026-06-24, and that is the single smallest habit worth stealing from this issue: let volatile content declare its own shelf life instead of making the reader guess.

Where this stops holding

• One domain and a SKILL.md under three hundred lines: docx, xlsx, pptx and web-artifacts-builder are to this day SKILL.md plus scripts/, with no .md split out of any of them. Do not split because "the official ones split" — most of the official ones do not.
• If you lean on grep to reach domain files, check that the environment has bash. The quick search under Pattern 2 is the single line grep -i "revenue" reference/finance.md; with no shell it degrades to reading whole files.
• Packaging for the API needs a second look: the docs state that the Claude API environment has no network access and no runtime package installation, so whatever scripts/ depends on has to be there already. Only claude.ai can pull from npm, PyPI and GitHub.

Costs and alternatives: every file you split out adds a routing line to maintain

Three ledgers

• Maintenance surface: n references means n routing lines and n relative paths that can be wrong. The FORMS.md versus forms.md case above is this ledger in the wild.
• Silent failure: split the file but never point at it from SKILL.md, or point at it vaguely ("see the reference material"), and the model neither reads it nor complains — the skill just feels unreliable. The docs' own test is behavioral: a bundled file that is never accessed is either unnecessary or poorly signaled in the main instructions.
• Preview loss: one level deep and a 100-line table of contents are not fastidiousness. The model previews with head -100, so a deep chain plus a long file with no contents equals half a schema — and half a schema is more dangerous than none, because half a definition triggers no suspicion.

What you can do instead of splitting

1. Don't split. Run a single file until it approaches 500 lines. The official template/ is still one SKILL.md and nothing else; that is what the starting position looks like.
2. Put the definitions in CLAUDE.md. The cost is that it is unconditionally resident and every session pays those tokens, so it fits only the two or three rules you genuinely need every time.
3. Serve schemas over MCP instead of from files. The server answers with the live table structure, so it never goes stale; the cost is a tool round trip per question and one more source of context tax (see Skill 9 and Skill 22).
4. Give each domain a subagent. Stronger context isolation, higher coordination tax — that one is Skill 26's subject.