# What Makes a Good reference.md

`reference.md` is the routing file required in every `references/`
subdirectory (see
`${CLAUDE_PLUGIN_ROOT}/references/layout/skill-structure.md`). It exists so
a model can decide what to read next without opening every knowledge doc.

This file is a pointer to the full pattern, kept here so
`references/layout/` stays a complete map of the layout — the actual
authoring detail lives in progressive-disclosure:

→ `${CLAUDE_PLUGIN_ROOT}/references/progressive-disclosure/reference-md-pattern.md`
  (required sections: what's here table, when to use this module, model
  guidance; anti-patterns like duplicating child content or exceeding ~50
  lines)

## When to split a reference doc out

A `reference.md` should point to a separate knowledge doc — rather than
inline the knowledge itself — whenever the content stops being "what's
here and when to read it" and becomes the knowledge itself. Concretely:

- The explanation would push `reference.md` past ~50 lines
- The content is only needed for a subset of workflows, not every reader
  of this directory
- The doc covers a distinct concept that could stand alone under a
  different topic subdirectory

Full splitting criteria (the "always needed together?" test, size
guidelines, how to split, depth limits) are in:
→ `${CLAUDE_PLUGIN_ROOT}/references/progressive-disclosure/splitting-knowledge.md`

## Quick checklist

1. Table of files/subdirs with purpose + "when to read"
2. "When to use this module" section
3. "Model guidance" (cheap vs. stronger model)
4. No duplication of child file content
5. <=50 lines total