From 801a01cc7d265e06dd9dbcef5a4c471add05a0b3 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:18:05 +0100 Subject: [PATCH] refine: Update terminology from Commands/Skills to User-invoked/Model-invoked and enhance documentation --- CLAUDE.md | 4 ++-- README.md | 10 +++++----- docs/commands-vs-skills.md | 16 ---------------- docs/invocation.md | 18 ++++++++++++++++++ skills/engineering/README.md | 8 ++++---- skills/productivity/README.md | 8 ++++---- .../writing-great-skills/GLOSSARY.md | 6 ++++++ .../productivity/writing-great-skills/SKILL.md | 2 ++ 8 files changed, 41 insertions(+), 31 deletions(-) delete mode 100644 docs/commands-vs-skills.md create mode 100644 docs/invocation.md diff --git a/CLAUDE.md b/CLAUDE.md index 3899085..53c86e9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,6 +11,6 @@ Every skill in `engineering/`, `productivity/`, or `misc/` must have a reference Each skill entry in the top-level `README.md` must link the skill name to its `SKILL.md`. -Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **Commands** and **Skills**. +Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. -Every `SKILL.md` is either a command (always user-invoked, `disable-model-invocation: true`) or a skill (model- or user-invocable). For the full definitions, description conventions, and the rule that commands invoke skills but never commands, see [docs/commands-vs-skills.md](./docs/commands-vs-skills.md). +Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). For the full definitions, description conventions, and why a user-invoked skill can invoke model-invoked skills but never another user-invoked one, see [docs/invocation.md](./docs/invocation.md). diff --git a/README.md b/README.md index a23628b..672320b 100644 --- a/README.md +++ b/README.md @@ -142,13 +142,13 @@ Software engineering fundamentals matter more than ever. These skills are my bes ## Reference -These come in two flavours. **Commands** are always user-invoked (you type `/grill-me`); their job is to orchestrate. **Skills** can be invoked by you _or_ reached for automatically by the agent when the task fits; they hold the reusable discipline. A command may invoke skills, but never another command. +These split on one axis — who can invoke them. **User-invoked** skills are reachable only when you type them (e.g. `/grill-me`); their job is to orchestrate. **Model-invoked** skills can be invoked by you _or_ reached for automatically by the agent when the task fits; they hold the reusable discipline. A user-invoked skill may invoke model-invoked skills, but never another user-invoked one. ### Engineering Skills I use daily for code work. -**Commands** +**User-invoked** - **[grill-with-docs](./skills/engineering/grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. - **[triage](./skills/engineering/triage/SKILL.md)** — Move issues through a state machine of triage roles. @@ -159,7 +159,7 @@ Skills I use daily for code work. - **[zoom-out](./skills/engineering/zoom-out/SKILL.md)** — Ask the agent to zoom out a level and map the relevant modules and callers on an unfamiliar section of code. - **[prototype](./skills/engineering/prototype/SKILL.md)** — Build a throwaway prototype to flesh out a design — either a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. -**Skills** +**Model-invoked** - **[diagnosing-bugs](./skills/engineering/diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. - **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. @@ -171,7 +171,7 @@ Skills I use daily for code work. General workflow tools, not code-specific. -**Commands** +**User-invoked** - **[caveman](./skills/productivity/caveman/SKILL.md)** — Ultra-compressed communication mode. Cuts token usage ~75% by dropping filler while keeping full technical accuracy. - **[grill-me](./skills/productivity/grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. @@ -179,7 +179,7 @@ General workflow tools, not code-specific. - **[teach](./skills/productivity/teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. - **[writing-great-skills](./skills/productivity/writing-great-skills/SKILL.md)** — Reference for writing and editing skills well: the vocabulary and principles that make a skill predictable. -**Skills** +**Model-invoked** - **[grilling](./skills/productivity/grilling/SKILL.md)** — Interview the user relentlessly about a plan or design until every branch of the decision tree is resolved. The reusable loop behind `grill-me` and `grill-with-docs`. diff --git a/docs/commands-vs-skills.md b/docs/commands-vs-skills.md deleted file mode 100644 index b6bb8e3..0000000 --- a/docs/commands-vs-skills.md +++ /dev/null @@ -1,16 +0,0 @@ -# Commands vs skills - -Every `SKILL.md` in this repo is one of two kinds. The test for "is it a skill" is: _could the model usefully reach for this autonomously?_ Reuse is the reason to extract a skill, not the test. - -- **Command** — _always_ user-invoked. Set `disable-model-invocation: true` in the frontmatter. The `description` is **human-facing**: a one-line summary read by a person browsing slash-commands. Strip trigger lists ("Use when the user says…") from command descriptions. A command may invoke skills, but **never another command**. -- **Skill** — invocable by **model or user**. The `description` is **model-facing** and keeps rich trigger phrasing ("Use when the user wants…, mentions…, asks for…") so auto-invocation fires. Do not set `disable-model-invocation`. - -Bucket `README.md`s and the top-level `README.md` group entries into **Commands** and **Skills**. - -## Dependencies between them - -Dependencies are expressed as **`/skill`-style prose invocation** ("Run the `/grilling` skill"), not deep `../other-skill/FILE.md` cross-references. Shared reference docs live inside the skill that owns them; other skills reach that material by invoking the skill, not by linking across folders. - -## Passive vs active domain work - -Merely _reading_ `CONTEXT.md` for vocabulary is a one-line prose pointer, not the `domain-modeling` skill. Only the active build/sharpen discipline (challenge terms, edge-case scenarios, write ADRs, update `CONTEXT.md` inline) is `domain-modeling`. diff --git a/docs/invocation.md b/docs/invocation.md new file mode 100644 index 0000000..c434516 --- /dev/null +++ b/docs/invocation.md @@ -0,0 +1,18 @@ +# Model-invoked vs user-invoked + +Every `SKILL.md` in this repo is a skill. The one axis that splits them is **invocation** — who can reach it: + +- **User-invoked** — reachable **only by the human typing its name**. Set `disable-model-invocation: true` in the frontmatter. The `description` is **human-facing**: a one-line summary read by a person browsing slash-commands. Strip trigger lists ("Use when the user says…"). +- **Model-invoked** — reachable by **model or user**. The default: omit `disable-model-invocation`. The `description` is **model-facing** and keeps rich trigger phrasing ("Use when the user wants…, mentions…, asks for…") so auto-invocation fires. The test for whether a skill should stay model-invoked: _could the model usefully reach for this autonomously?_ (Reuse is the reason to extract a skill, not the test.) + +Because a user-invoked skill has no description, nothing but the human can reach it — no other skill can fire it. So a user-invoked skill may invoke model-invoked skills, but it can never reach another user-invoked skill. + +Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. + +## Dependencies between them + +Dependencies are expressed as **`/skill`-style prose invocation** ("Run the `/grilling` skill"), not deep `../other-skill/FILE.md` cross-references. Shared reference docs live inside the skill that owns them; other skills reach that material by invoking the skill, not by linking across folders. + +## Passive vs active domain work + +Merely _reading_ `CONTEXT.md` for vocabulary is a one-line prose pointer, not the `domain-modeling` skill. Only the active build/sharpen discipline (challenge terms, edge-case scenarios, write ADRs, update `CONTEXT.md` inline) is `domain-modeling`. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 58e02a9..bdec4f2 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -2,9 +2,9 @@ Skills I use daily for code work. -## Commands +## User-invoked -User-invoked entry points (`disable-model-invocation: true`). +Reachable only when you type them (`disable-model-invocation: true`). - **[grill-with-docs](./grill-with-docs/SKILL.md)** — Grilling session that also builds your project's domain model, sharpening terminology and updating `CONTEXT.md` and ADRs inline. - **[triage](./triage/SKILL.md)** — Move issues through a state machine of triage roles. @@ -15,9 +15,9 @@ User-invoked entry points (`disable-model-invocation: true`). - **[zoom-out](./zoom-out/SKILL.md)** — Ask the agent to zoom out a level and map the relevant modules and callers. - **[prototype](./prototype/SKILL.md)** — Build a throwaway prototype — a runnable terminal app for state/logic questions, or several toggleable UI variations. -## Skills +## Model-invoked -Model- or user-invocable (rich trigger phrasing so the model can reach for them). +Model- or user-reachable (rich trigger phrasing so the model can reach for them). - **[diagnosing-bugs](./diagnosing-bugs/SKILL.md)** — Disciplined diagnosis loop for hard bugs and performance regressions: reproduce → minimise → hypothesise → instrument → fix → regression-test. - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. diff --git a/skills/productivity/README.md b/skills/productivity/README.md index 570dab3..e98607d 100644 --- a/skills/productivity/README.md +++ b/skills/productivity/README.md @@ -2,17 +2,17 @@ General workflow tools, not code-specific. -## Commands +## User-invoked -User-invoked entry points (`disable-model-invocation: true`). +Reachable only when you type them (`disable-model-invocation: true`). - **[grill-me](./grill-me/SKILL.md)** — Get relentlessly interviewed about a plan or design until every branch of the decision tree is resolved. - **[handoff](./handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. - **[teach](./teach/SKILL.md)** — Teach the user a new skill or concept over multiple sessions, using the current directory as a stateful teaching workspace. - **[writing-great-skills](./writing-great-skills/SKILL.md)** — Reference for writing and editing skills well: the vocabulary and principles that make a skill predictable. -## Skills +## Model-invoked -Model- or user-invocable (rich trigger phrasing so the model can reach for them). +Model- or user-reachable (rich trigger phrasing so the model can reach for them). - **[grilling](./grilling/SKILL.md)** — Interview the user relentlessly about a plan or design until every branch of the decision tree is resolved. diff --git a/skills/productivity/writing-great-skills/GLOSSARY.md b/skills/productivity/writing-great-skills/GLOSSARY.md index 83af665..665cf07 100644 --- a/skills/productivity/writing-great-skills/GLOSSARY.md +++ b/skills/productivity/writing-great-skills/GLOSSARY.md @@ -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. diff --git a/skills/productivity/writing-great-skills/SKILL.md b/skills/productivity/writing-great-skills/SKILL.md index 4669bea..cd46075 100644 --- a/skills/productivity/writing-great-skills/SKILL.md +++ b/skills/productivity/writing-great-skills/SKILL.md @@ -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: