Grill me: let your agent ask before it codes.

Type "add dark mode" into a coding agent and you get dark mode. A toggle in some corner, colours you didn't pick, the choice saved somewhere you would never have saved it. The code compiles. It might even be good code. It is just not the thing you had in your head, because you never said what was in your head, and the agent never asked.

That gap has a name. Matt Pocock's skills repository lists four ways coding agents fail, and misalignment is number one: you think the agent knows what you want, then you see what it built. His fix is a skill called /grill-me, and the interesting thing about it is how little it contains.

Watch the 60-second version on Instagram.

When it works, the difference is stark. One grilling session was the only prompt Claude Opus 5.5 needed to build a case study page for me that matched what I had in mind.

The repo, and the four failures

mattpocock/skills is Matt Pocock's own set of agent skills, published under the MIT licence. The repository was created on 2026.02.03 and, as I write this in October 2026, has about 287,000 stars and 24,000 forks on GitHub. The README is organised around four failure modes he sees in Claude Code, Codex and other agents, each with the skills that address it:

This post is about the first row. The README calls the grilling skills his most popular, and recommends using them every time you want to make a change.

Two lines of markdown

Here is the whole of grill-me:

---
name: grill-me
description: A relentless interview to sharpen a plan or design.
disable-model-invocation: true
---
 
Call the Skill tool with "grilling".

That's it. The frontmatter gives it a name and a one-line description, and disable-model-invocation: true tells Claude Code that the agent may never load this skill on its own. Only you can, by typing /grill-me. In Claude Code, a skill with that flag doesn't even put its description into the agent's context; it does nothing until you call it.

The body hands off to a second skill, grilling, which is model-invoked: the agent can reach for it whenever a task fits. That split is deliberate and runs through the whole repo. User-invoked skills are thin entry points that orchestrate; model-invoked skills hold the reusable discipline. grilling is the interview primitive behind grill-me, grill-with-docs, triage, wayfinder and improve-codebase-architecture.

The point I want to make here is about what a skill is. It's tempting to think of skills as prompts that make the model smarter. grill-me adds no knowledge at all. It doesn't know anything about dark mode, React or your codebase. It changes when the agent acts: questions first, code second. Process, not knowledge.

The interview is a tree

The grilling skill is about 25 lines, and almost every line earns its place. It starts with the goal, to keep interviewing you until the two of you share an understanding of the plan, and then gives the agent a structure for getting there: a design tree, where every decision branches into the decisions that hang off it.

The tree is worked in rounds. The skill defines the frontier as every decision whose prerequisites are already settled, the questions the agent can ask now without guessing at answers it hasn't heard. Each round, it asks the whole frontier at once, numbered, each with a recommended answer, then stops and waits.

In the figure, the request "add dark mode" is the root. Round 1 has three questions that don't depend on each other: follow the OS setting? add a toggle? save the choice? Round 2 only exists because of round 1's answers. Where the toggle goes and whether it is an icon or a label only matter once you've said yes to a toggle. Which storage to use only matters once you've said yes to saving. The skill is explicit about this: a question whose answer depends on another question still open in this round belongs to a later round.

Two things fall out of that structure:

• No question is wasted. The agent doesn't ask about the toggle's icon if you might not want a toggle at all.
• You answer in batches, not one by one. A round is one message and one reply. Ten questions in three rounds is three round trips, not ten.

The session is done when the frontier is empty: every branch visited, nothing silently assumed. And then the line that matters most: the agent must not act on the plan until you confirm you've reached a shared understanding.

"Yes" accepts the recommendation

Every question comes with the agent's own recommended answer, and the skill asks it to word each question so that a plain "yes" accepts that recommendation. A round looks roughly like this (illustrative, not real output):

> /grill-me I want to add dark mode
 
Q1 - Follow the OS: Default to the system colour scheme?
-> Yes, read prefers-color-scheme on first visit.
 
Q2 - Override: Add a toggle so people can choose?
-> Yes, three states: light, dark, system.
 
Q3 - Persist: Remember the choice between visits?
-> Yes, the toggle is pointless if it resets.

This is a small detail with a large effect. The cost of a question is the effort of answering it. If every question is open-ended ("how should the theme be stored?"), you end up designing the feature in a chat window. With a recommendation attached, most answers are "yes", and your attention goes to the two or three where you disagree. The agent does the proposing; you do the deciding.

There is a trade-off here, and I think it's worth naming. A recommended answer is an anchor. If you're tired or in a hurry, "yes, yes, yes" is easy to type, and you've agreed to the agent's plan without thinking about it, which is roughly where you started. The format makes good answers cheap; it doesn't make you read the question.

For me it is mostly "yes", because the recommendations are usually what I wanted anyway. But not always. While planning the posts on this blog, the agent's plan reused the renders from my Instagram stories; I asked for the figures to be redrawn for the blog column instead, and the rest of the plan changed around that answer.

Facts are the agent's job

The other rule I like is a clean division of labour. Some questions have answers in the environment: is Tailwind installed, is there already a theme file, which storage does the app use elsewhere. Others are choices only you can make: should it follow the OS, where should the toggle go.

The skill says finding facts is the agent's job, never the user's. When a frontier question needs a fact from the filesystem or tools, the agent sends a sub-agent to look it up instead of asking you. And it doesn't block on it: a running lookup counts as an unsettled prerequisite, so only the questions that depend on it wait, and the rest of the frontier is asked now. Decisions go to you, and the agent waits for each.

This is what separates a useful interview from an annoying one. An agent that asks "which CSS framework do you use?" when package.json is right there is wasting your time and telling you it hasn't looked. An agent that comes back with "you already use Tailwind with a dark: variant; reuse it?" has done its homework and is asking a real question.

Why asking first works

None of this is new. The README opens the misalignment section with a line from The Pragmatic Programmer: "No-one knows exactly what they want." Requirements have always been discovered in conversation, not handed over complete. Good engineers ask questions before they estimate, and good teams write the spec before the code. What's new is that the developer on the other end of the conversation now types at a few hundred lines a minute, so skipping the conversation costs more than it used to.

The economics are simple. A question costs one message. A wrong implementation costs reading it, explaining what's wrong, and a rewrite, often several, because each correction reveals the next misunderstanding. Agents make code cheap, so it's tempting to treat a wrong first attempt as free. It isn't: your review time is the expensive part, and a 400-line diff built on the wrong assumption still has to be read before you can throw it away.

Grilling also helps with something that has nothing to do with the agent: it makes you think. Half the questions in a good round are ones you hadn't considered. Should the toggle have a "system" state? What happens on first visit before the script runs? If you can't answer, you've learned the plan wasn't ready, before anything was built on top of it.

This is the part that maps most directly onto my day job. With clients and with teams, the hard thing has never been agreeing; it is that we agree while picturing different things, and the difference shows up as rework. A grilling session asks the right questions, and some of them I only think about because I see them written down. Those are the ones I take back to the team and the product owners before development starts, which is where rework is cheapest to avoid.

grill-me or grill-with-docs

The repo has two grilling entry points, and the README is clear about the difference. grill-me lives in the productivity folder and is described there as being for non-code uses: a plan, a decision, an idea. grill-with-docs lives in engineering and is the same interview plus the domain-modeling skill, so while it grills you it also builds your project's shared language in a GLOSSARY.md and records hard-to-explain decisions as ADRs (architecture decision records). It is also just two lines:

---
name: grill-with-docs
description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
disable-model-invocation: true
---
 
Call the Skill tool twice, for "grilling" and "domain-modeling".

The README rates the shared glossary as possibly the best technique in the whole repo, and it's the fix for failure number two. If you're grilling about code in a real project, grill-with-docs is the one the repo points you to; grill-me is the lighter version for when you only want the interview.

That matches how I use them: grill-with-docs for larger features. I have also used grilling as a building block, in workflow skills of my own that invoke it and then hand off to other commands or skills.

When not to grill

A design-tree interview is the wrong tool for a one-line fix. If the change is "rename this variable" or "the button is 2px off", there is no tree, and three rounds of questions are pure overhead. Grilling pays off where there are real decisions: a new feature, a data model, an API, a refactor with more than one reasonable shape.

It also doesn't replace the other three rows of the table. A perfectly aligned plan can still produce broken code, which is why the same repo has tdd (one test, one implementation, repeat, in vertical slices) and diagnosing-bugs. Alignment is the first gate, not the only one.

And it costs time up front. A thorough session on a meaty feature can run several rounds before a line of code appears. That is the point, but it means grilling is a habit for work that matters, not something to run on every message.

Installing it

The repo supports several agents. Pick one install method per agent: the README warns that installing both the plugin and the editable files gives you every skill twice.

# Claude Code: a plugin that updates itself
claude plugin install mattpocock-skills@claude-plugins-official
 
# Any other agent (Cursor, OpenCode, Windsurf, ...): editable files you update by hand
npx skills@latest add mattpocock/skills

Codex, GitHub Copilot and Gemini CLI have their own commands in the README. After installing, run /setup-matt-pocock-skills once per repo: it asks which issue tracker you use, which triage labels you apply and where to save docs, which the engineering skills rely on. /grill-me itself works without it.

The repo also moves fast. Version 1.3.0 renamed the CONTEXT.md convention to GLOSSARY.md, and earlier releases renamed writing-great-skills to writing-for-agents. Tutorials written a few months ago may name files that no longer exist, so read the current README rather than a blog post (including this one) when the details matter.

The short version

1. Most bad agent output is the right code for the wrong plan. Fix the plan first.
2. /grill-me is two lines that hand off to grilling. It adds no knowledge; it changes when the agent acts.
3. The interview walks a design tree in rounds: every question that can be answered now, in one batch, each with a recommendation that "yes" accepts.
4. Facts are the agent's job (it looks them up); decisions are yours.
5. Nothing is built until you confirm the plan. Save it for features and designs, not one-line fixes.

Sources: mattpocock/skills README · grilling SKILL.md · grill-me SKILL.md · grill-with-docs SKILL.md · tdd SKILL.md · CHANGELOG · GitHub API, repository metadata · Claude Code docs, skills and disable-model-invocation · Claude plugin listing