40 lines
1.6 KiB
Markdown
40 lines
1.6 KiB
Markdown
|
# 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
|