refine: Update terminology from Commands/Skills to User-invoked/Model-invoked and enhance documentation

This commit is contained in:
Matt Pocock 2026-06-17 14:18:05 +01:00
parent bc4cf903ff
commit 801a01cc7d
8 changed files with 41 additions and 31 deletions

View file

@ -33,6 +33,8 @@ Push too little down and the top bloats; push too much and you hide material the
**Progressive disclosure** is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a **branch** — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A **context pointer**'s _wording_, not its target, decides when and how reliably the agent reaches the material.
Where the ladder decides _how far down_ a piece sits, **co-location** decides _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it.
## When to split
**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut earns it. Two cuts: