From 355fa7420b418af838998f7ec4365ceda1c8dfcc Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 10:57:02 +0100 Subject: [PATCH 1/3] feat: add wait-what, the verbosity fire extinguisher A three-line, user-invoked skill in in-progress/. Fire it when the agent's last message doesn't land; it re-pitches that message with the missing context, in ASD-STE100 Simplified Technical English, using the ubiquitous language from CONTEXT.md. The name is the mechanism. Concision skills fail by growing, so this one is a single precise leading word and nothing else. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/wait-what.md | 9 +++++++++ skills/in-progress/README.md | 1 + skills/in-progress/wait-what/SKILL.md | 7 +++++++ skills/in-progress/wait-what/agents/openai.yaml | 5 +++++ 4 files changed, 22 insertions(+) create mode 100644 .changeset/wait-what.md create mode 100644 skills/in-progress/wait-what/SKILL.md create mode 100644 skills/in-progress/wait-what/agents/openai.yaml diff --git a/.changeset/wait-what.md b/.changeset/wait-what.md new file mode 100644 index 0000000..da37751 --- /dev/null +++ b/.changeset/wait-what.md @@ -0,0 +1,9 @@ +--- +"mattpocock-skills": minor +--- + +Add **`wait-what`** to `in-progress/` — a fire extinguisher for model verbosity. Fire it the moment a message doesn't land, and the agent re-pitches *that message*: a little context, ASD-STE100 Simplified Technical English, and the ubiquitous language from your `CONTEXT.md`. User-invoked, three lines long. + +The mechanism is the name. Concision skills fail by growing — a 400-line skill still leaves the model verbose — so this one is a single precise leading word and nothing else. It also reuses the leading words already in your global `CLAUDE.md`, so the skill, `CLAUDE.md` and every `CONTEXT.md` reach for the same tokens. + +It's the extinguisher, not the sprinkler. The cure for jargon is a shared language built upfront with `/grill-with-docs`; this is the in-the-moment corrective for when you don't have one yet. diff --git a/skills/in-progress/README.md b/skills/in-progress/README.md index 63556de..12270c2 100644 --- a/skills/in-progress/README.md +++ b/skills/in-progress/README.md @@ -7,4 +7,5 @@ Skills that are still being developed. They're not ready to ship — expect roug - **[writing-fragments](./writing-fragments/SKILL.md)** — Grilling session that mines you for fragments — heterogeneous nuggets of writing — and appends them to a single document as raw material for a future article. - **[writing-shape](./writing-shape/SKILL.md)** — Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step. - **[claude-handoff](./claude-handoff/SKILL.md)** — Hand the current conversation off to a fresh background agent that picks up the work immediately, seeded with a handoff summary via `claude --bg`. User-invoked. +- **[wait-what](./wait-what/SKILL.md)** — Fire this when the agent's last message did not land. It re-pitches that message with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary. User-invoked. - **[setup-ts-deep-modules](./setup-ts-deep-modules/SKILL.md)** — Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files, tests exercising it through those. User-invoked. diff --git a/skills/in-progress/wait-what/SKILL.md b/skills/in-progress/wait-what/SKILL.md new file mode 100644 index 0000000..318c4be --- /dev/null +++ b/skills/in-progress/wait-what/SKILL.md @@ -0,0 +1,7 @@ +--- +name: wait-what +description: Stop. That last message did not land — re-pitch it. +disable-model-invocation: true +--- + +Wait — I don't understand where you've got to here. Re-pitch that last message: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`. diff --git a/skills/in-progress/wait-what/agents/openai.yaml b/skills/in-progress/wait-what/agents/openai.yaml new file mode 100644 index 0000000..03490ca --- /dev/null +++ b/skills/in-progress/wait-what/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Wait What" + short_description: "Re-pitch that last message — simpler, with the context I'm missing" +policy: + allow_implicit_invocation: false From 006ca0546bc5aa144e2796875debf3f73852a27c Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 11:07:06 +0100 Subject: [PATCH 2/3] refactor: loosen wait-what's re-pitch scope to a bare demonstrative MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "Re-pitch that last message" pinned the correction to one message. "Re-pitch that" leaves the agent to judge how much of what it said failed to land — and is shorter. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/wait-what.md | 2 +- skills/in-progress/README.md | 2 +- skills/in-progress/wait-what/SKILL.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.changeset/wait-what.md b/.changeset/wait-what.md index da37751..7207f65 100644 --- a/.changeset/wait-what.md +++ b/.changeset/wait-what.md @@ -2,7 +2,7 @@ "mattpocock-skills": minor --- -Add **`wait-what`** to `in-progress/` — a fire extinguisher for model verbosity. Fire it the moment a message doesn't land, and the agent re-pitches *that message*: a little context, ASD-STE100 Simplified Technical English, and the ubiquitous language from your `CONTEXT.md`. User-invoked, three lines long. +Add **`wait-what`** to `in-progress/` — a fire extinguisher for model verbosity. Fire it the moment a message doesn't land, and the agent re-pitches it: a little context, ASD-STE100 Simplified Technical English, and the ubiquitous language from your `CONTEXT.md`. User-invoked, three lines long. The mechanism is the name. Concision skills fail by growing — a 400-line skill still leaves the model verbose — so this one is a single precise leading word and nothing else. It also reuses the leading words already in your global `CLAUDE.md`, so the skill, `CLAUDE.md` and every `CONTEXT.md` reach for the same tokens. diff --git a/skills/in-progress/README.md b/skills/in-progress/README.md index 12270c2..d44b93a 100644 --- a/skills/in-progress/README.md +++ b/skills/in-progress/README.md @@ -7,5 +7,5 @@ Skills that are still being developed. They're not ready to ship — expect roug - **[writing-fragments](./writing-fragments/SKILL.md)** — Grilling session that mines you for fragments — heterogeneous nuggets of writing — and appends them to a single document as raw material for a future article. - **[writing-shape](./writing-shape/SKILL.md)** — Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step. - **[claude-handoff](./claude-handoff/SKILL.md)** — Hand the current conversation off to a fresh background agent that picks up the work immediately, seeded with a handoff summary via `claude --bg`. User-invoked. -- **[wait-what](./wait-what/SKILL.md)** — Fire this when the agent's last message did not land. It re-pitches that message with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary. User-invoked. +- **[wait-what](./wait-what/SKILL.md)** — Fire this when the agent's last message did not land. It re-pitches what didn't land, with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary. User-invoked. - **[setup-ts-deep-modules](./setup-ts-deep-modules/SKILL.md)** — Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files, tests exercising it through those. User-invoked. diff --git a/skills/in-progress/wait-what/SKILL.md b/skills/in-progress/wait-what/SKILL.md index 318c4be..d493cfa 100644 --- a/skills/in-progress/wait-what/SKILL.md +++ b/skills/in-progress/wait-what/SKILL.md @@ -4,4 +4,4 @@ description: Stop. That last message did not land — re-pitch it. disable-model-invocation: true --- -Wait — I don't understand where you've got to here. Re-pitch that last message: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`. +Wait — I don't understand where you've got to here. Re-pitch that: give me a little bit of context, talk in ASD-STE100 Simplified Technical English, and use the ubiquitous language from `CONTEXT.md`. From 50777fcc0982d5867997a75a1e0731b9daac94eb Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 5 Aug 2026 11:11:54 +0100 Subject: [PATCH 3/3] feat: graduate wait-what into the productivity bucket MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Moves the skill out of in-progress/ and ships it: bucket README, top-level README, plugin.json, an ask-matt router entry, and a docs page at docs/productivity/wait-what.md. Productivity rather than engineering — it fires in any conversation with an agent, code or not. The CONTEXT.md clause is an opportunistic hook, not a prerequisite. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/wait-what.md | 4 +- .claude-plugin/plugin.json | 1 + README.md | 1 + docs/productivity/wait-what.md | 48 +++++++++++++++++++ skills/engineering/ask-matt/SKILL.md | 1 + skills/in-progress/README.md | 1 - .../in-progress/wait-what/agents/openai.yaml | 5 -- skills/productivity/README.md | 1 + .../wait-what/SKILL.md | 0 .../productivity/wait-what/agents/openai.yaml | 5 ++ 10 files changed, 59 insertions(+), 8 deletions(-) create mode 100644 docs/productivity/wait-what.md delete mode 100644 skills/in-progress/wait-what/agents/openai.yaml rename skills/{in-progress => productivity}/wait-what/SKILL.md (100%) create mode 100644 skills/productivity/wait-what/agents/openai.yaml diff --git a/.changeset/wait-what.md b/.changeset/wait-what.md index 7207f65..c611cdd 100644 --- a/.changeset/wait-what.md +++ b/.changeset/wait-what.md @@ -2,8 +2,8 @@ "mattpocock-skills": minor --- -Add **`wait-what`** to `in-progress/` — a fire extinguisher for model verbosity. Fire it the moment a message doesn't land, and the agent re-pitches it: a little context, ASD-STE100 Simplified Technical English, and the ubiquitous language from your `CONTEXT.md`. User-invoked, three lines long. +Add **`wait-what`** — a fire extinguisher for model verbosity. Fire it the moment a message doesn't land, and the agent re-pitches it: a little context, ASD-STE100 Simplified Technical English, and the ubiquitous language from your `CONTEXT.md`. User-invoked, three lines long. -The mechanism is the name. Concision skills fail by growing — a 400-line skill still leaves the model verbose — so this one is a single precise leading word and nothing else. It also reuses the leading words already in your global `CLAUDE.md`, so the skill, `CLAUDE.md` and every `CONTEXT.md` reach for the same tokens. +The mechanism is the name. Concision skills fail by growing — a 400-line skill still leaves the model verbose — so this one is a single precise leading word and nothing else. Names that describe the *output* (`/tldr`, `/no-fluff`) make the model clip words and lose you further; naming the *listener's* state asks for both halves at once, fewer words **and** the context you were missing. It also reuses the leading words already in your global `CLAUDE.md`, so the skill, `CLAUDE.md` and every `CONTEXT.md` reach for the same tokens. It's the extinguisher, not the sprinkler. The cure for jargon is a shared language built upfront with `/grill-with-docs`; this is the in-the-moment corrective for when you don't have one yet. diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 8c3e9ce..8b69b1c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -42,6 +42,7 @@ "./skills/productivity/handoff", "./skills/productivity/teach", "./skills/productivity/to-questionnaire", + "./skills/productivity/wait-what", "./skills/productivity/writing-for-agents" ] } diff --git a/README.md b/README.md index 1ad017c..2661315 100644 --- a/README.md +++ b/README.md @@ -223,6 +223,7 @@ General workflow tools, not code-specific. - **[handoff](./skills/productivity/handoff/SKILL.md)** — Compact the current conversation into a handoff document so another agent can continue the work. - **[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. - **[to-questionnaire](./skills/productivity/to-questionnaire/SKILL.md)** — Turn a decision you can't answer alone into a Markdown questionnaire for the one person who can — filled in async, or together over a meeting. It grills you about the send (who it's for, what you need back), not the subject. +- **[wait-what](./skills/productivity/wait-what/SKILL.md)** — Fire this the moment a message doesn't land. The agent re-pitches it with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary. - **[writing-for-agents](./skills/productivity/writing-for-agents/SKILL.md)** — Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer. **Model-invoked** diff --git a/docs/productivity/wait-what.md b/docs/productivity/wait-what.md new file mode 100644 index 0000000..9dfb863 --- /dev/null +++ b/docs/productivity/wait-what.md @@ -0,0 +1,48 @@ +Quickstart: + +```bash +npx skills@latest add mattpocock/skills --skill=wait-what +``` + +```bash +npx skills@latest update wait-what +``` + +[Source](https://github.com/mattpocock/skills/tree/main/skills/productivity/wait-what) + +## What it does + +`wait-what` is the fire extinguisher for a message that didn't land. You fire it the moment you lose the thread, and the agent re-pitches what it just said: a little of the context you were missing, plain English, and the vocabulary from your project's `CONTEXT.md`. + +It is three lines long, and that is the design rather than an unfinished draft. Skills that fight verbosity fail by growing — a four-hundred-line concision skill still leaves the model verbose, because the model reads the volume, not the plea. This one carries a single precise leading word and nothing else. + +## When to reach for it + +You invoke this by typing `/wait-what` — the agent won't reach for it on its own, and it shouldn't: only you know when you stopped following. + +Reach for it the second you notice you're skimming — the agent has drifted into jargon it invented, stacked five acronyms, or explained a decision whose premise you never saw. It's a one-shot corrective on the conversation you're already in. To stop the jargon arriving in the first place, use [grill-with-docs](https://aihero.dev/skills-grill-with-docs) instead, which builds the shared language upfront. + +## The name is the mechanism + +The leading word is **wait**. Not "be concise" — an instruction about the agent's output, which the model satisfies by clipping words and losing you further. **Wait** is about *your* state: it says comprehension failed here. An agent that hears "be brief" writes telegrams. An agent that hears "wait, you lost me" backs up and explains. + +That distinction is the whole skill. Every popular fix for verbosity — `/tldr`, `/no-fluff`, `/talk-normal` — names the *output*, so the model over-corrects into a caveman register that's shorter and no clearer. Naming the *listener* asks for both halves at once: fewer words **and** the context you were missing. + +The re-pitch is deliberately vague about its own scope. It says re-pitch **that**, not "that last message", because what lost you is usually bigger than one paragraph — the agent decides how far back to go. + +## It plugs into the language you already have + +The body reuses the leading words already sitting in your global `CLAUDE.md` and your project's `CONTEXT.md`: ASD-STE100 Simplified Technical English for the register, ubiquitous language for the nouns. Skill, `CLAUDE.md` and `CONTEXT.md` reach for the same tokens, so firing it isn't a new instruction — it's a reminder of one the agent already agreed to. + +If you have no `CONTEXT.md`, it still works; you just lose the domain-vocabulary half. + +## It's working if + +- The re-pitch is **shorter and clearer**, not shorter and blunter. +- It adds the premise you were missing rather than just deleting words. +- Project nouns replace invented ones — the terms in your `CONTEXT.md` come back. +- You can fire it twice in a row without it degrading into terseness. + +## Where it fits + +`wait-what` is a reach-for-it-anytime standalone — it sits inside whatever conversation you're already having, in any skill, at any point. It's the extinguisher; [grill-with-docs](https://aihero.dev/skills-grill-with-docs) is the sprinkler system, because a shared language agreed upfront is the real cure for jargon, and [domain-modeling](https://aihero.dev/skills-domain-modeling) is what you reach for when the *words themselves* are the problem rather than one bad message. When you're unsure which skill fits the moment, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/skills/engineering/ask-matt/SKILL.md b/skills/engineering/ask-matt/SKILL.md index 63bd0a6..1fedec4 100644 --- a/skills/engineering/ask-matt/SKILL.md +++ b/skills/engineering/ask-matt/SKILL.md @@ -79,6 +79,7 @@ Off the main flow entirely. - **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it. - **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`. - **`/wizard`** — for the steps only a **human** can take: clicking through a third-party dashboard, running a one-off migration, moving the project from state A to state B. It generates an interactive bash script that opens each URL, captures each value, and writes it into `.env` and GitHub secrets — so the procedure stops being something you re-explain to an agent every time. If the agent could just do it itself, it should; reach for this only where a human is genuinely in the loop. +- **`/wait-what`** — the fire extinguisher for a message that didn't land. Fire it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It's the in-the-moment corrective; `/grill-with-docs` and `/domain-modeling` are the upfront cure, because a shared language agreed early is what stops the jargon arriving at all. - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace. - **`/writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs. diff --git a/skills/in-progress/README.md b/skills/in-progress/README.md index d44b93a..63556de 100644 --- a/skills/in-progress/README.md +++ b/skills/in-progress/README.md @@ -7,5 +7,4 @@ Skills that are still being developed. They're not ready to ship — expect roug - **[writing-fragments](./writing-fragments/SKILL.md)** — Grilling session that mines you for fragments — heterogeneous nuggets of writing — and appends them to a single document as raw material for a future article. - **[writing-shape](./writing-shape/SKILL.md)** — Take a markdown file of raw material and shape it into an article paragraph by paragraph, arguing format choices at each step. - **[claude-handoff](./claude-handoff/SKILL.md)** — Hand the current conversation off to a fresh background agent that picks up the work immediately, seeded with a handoff summary via `claude --bg`. User-invoked. -- **[wait-what](./wait-what/SKILL.md)** — Fire this when the agent's last message did not land. It re-pitches what didn't land, with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary. User-invoked. - **[setup-ts-deep-modules](./setup-ts-deep-modules/SKILL.md)** — Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files, tests exercising it through those. User-invoked. diff --git a/skills/in-progress/wait-what/agents/openai.yaml b/skills/in-progress/wait-what/agents/openai.yaml deleted file mode 100644 index 03490ca..0000000 --- a/skills/in-progress/wait-what/agents/openai.yaml +++ /dev/null @@ -1,5 +0,0 @@ -interface: - display_name: "Wait What" - short_description: "Re-pitch that last message — simpler, with the context I'm missing" -policy: - allow_implicit_invocation: false diff --git a/skills/productivity/README.md b/skills/productivity/README.md index 8f2db7f..97127ab 100644 --- a/skills/productivity/README.md +++ b/skills/productivity/README.md @@ -10,6 +10,7 @@ Reachable only when you type them (Claude Code: `disable-model-invocation: true` - **[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. - **[to-questionnaire](./to-questionnaire/SKILL.md)** — Turn a decision you can't answer alone into a Markdown questionnaire for the one person who can — filled in async, or together over a meeting. +- **[wait-what](./wait-what/SKILL.md)** — Fire this the moment a message doesn't land. The agent re-pitches it with the context you're missing, in plain English, using your `CONTEXT.md` vocabulary. - **[writing-for-agents](./writing-for-agents/SKILL.md)** — Writing documents for agents: skills, AGENTS.md/CLAUDE.md, and any doc an agent reaches by a pointer. ## Model-invoked diff --git a/skills/in-progress/wait-what/SKILL.md b/skills/productivity/wait-what/SKILL.md similarity index 100% rename from skills/in-progress/wait-what/SKILL.md rename to skills/productivity/wait-what/SKILL.md diff --git a/skills/productivity/wait-what/agents/openai.yaml b/skills/productivity/wait-what/agents/openai.yaml new file mode 100644 index 0000000..ba77f1c --- /dev/null +++ b/skills/productivity/wait-what/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Wait What" + short_description: "Re-pitch that — simpler, with the context I'm missing" +policy: + allow_implicit_invocation: false