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
@@ -72,6 +72,12 @@ A skill with no **steps** uses just the bottom two rungs — often a legitimatel
_Avoid_: structure, organization, layout
### Co-location
Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks *how far down* a piece sits; co-location decides *what sits beside it* once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
_Avoid_: grouping, clustering, cohesion
### Branch
A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.