git:20260711.f8dd35c to git:20260821.d838e58

+ ## Where a fact has to live for the model to see it

+

+ Three surfaces, three different moments. Putting something on the wrong one is

+ why a capability that exists still does not get used.

+

+ | Surface | When it enters context | Budget |

+ |---|---|---|

+ | `description` in the frontmatter | always, in the skill listing | combined description text truncated at **1536 characters**; the listing itself is capped at ~1% of the context window |

+ | `SKILL.md` body | when the skill is invoked | published guidance is **under 500 lines**; the gate here enforces **500 words over the whole file** (see below) |

+ | `references/*.md` | when the model chooses to read one | none, they cost nothing until read |

+

+ What follows from that:

+

+ - **A missing capability in the `description` is the only true skip.** The model

+ never invokes the skill, so nothing further is consulted. Put the key use case

+ first: when many skills are installed the listing overflows its budget and

+ descriptions get shortened or dropped, starting with the least-used skills.

+ - **A missing capability in the body is a blind spot, not a skip.** The skill

+ runs, and the model does not know the thing exists.

+ - **Scripts belong in the body.** They are executed, never loaded, so listing one

+ costs a line and buys the only chance the model has of knowing it is there.

+

+ ### The enforced budget is not the documented one

+

+ The `validate-skill` pre-commit hook comes from `netresearch/skill-repo-skill`,

+ and it counts **500 words over the whole file**, frontmatter included. The

+ published guidance is *"Keep `SKILL.md` under 500 lines"*. Words are a much

+ tighter budget than lines, and charging the frontmatter to it means the

+ `description` -- the one surface that decides whether the skill is used at all

+ -- competes with the instructions for the same allowance.

+

+ The practical consequence is visible in this repository's history: it sat at

+ 499 of 500 and left a script out of `SKILL.md` rather than spend fourteen words

+ on it. Note also that `Build/Scripts/validate-skill.sh` here is a COPY that

+ nothing runs -- editing it changes no gate.

+

+ Until the upstream check is corrected, budget in words and count the

+ frontmatter. When the body is tight, move detail into an existing reference and

+ keep the capability: a reader who cannot see that a script exists will not run

+ it.

+

+ ### One level of references, and each one says when to read it

+

+ The documented shape is flat: `SKILL.md` is the overview and navigation, with

+ supporting files beside it, and each one referenced *"so Claude knows what each

+ file contains and when to load it"*. The `Reference Files` table in `SKILL.md`

+ is that mechanism -- the `Content Triggers` column is not decoration, it is what

+ lets the model decide to read a file it cannot see.

+

+ So do not nest a second hop. `SKILL.md` -> `references.md` -> `topic.md` puts

+ the third file behind a door with no sign on it: nothing states what it holds or

+ when it matters, so the model has to open the middle file on speculation and

+ then guess again. Split by topic at the FIRST level instead -- `topic-a.md` and

+ `topic-b.md` both listed in the table, each with its own trigger.

+

+ The body stays short because detail moves into references, never because facts

+ get dropped. If the body is at its limit, that is a signal to move a section

+ into a reference and add a row to the table -- not to leave a capability

+ undocumented.

+