The grill-me skill gets a coding agent to question a plan before it starts doing the work. Instead of moving straight from an idea into implementation, the agent works through the decisions behind it, looks for gaps and assumptions, and asks you to resolve anything that could cause problems later. Matt Pocock published the first version in February 2026 with only two sentences of instructions. Since then, it has grown into a small family of agent skills that ask questions in rounds, recommend answers and look up information the agent can find for itself. The skills work in Claude Code, Codex, OpenCode and other agents that support the open Agent Skills format.
If you came across grill-me earlier in the year, you may remember it working differently. For a while, it asked one question at a time. That instruction was added on 26 March and stayed until July, when the interview switched to rounds. The current version also expects the agent to do some research before it asks you for information. If the answer is already in the codebase or another source it can access, it should find it there rather than making you repeat it. That works naturally in a repository. In client work, where the context is often spread across calls, shared drives and documents, making that material available to the agent is a much bigger part of the job.
At our weekly knowledge-sharing session on 2 October, I showed an internal skill I've been working on for preparing new client engagements. One stage is called "the grill". Before the interview starts, the workflow pulls in the client's documents and call transcripts so the agent can search them itself. That means I don't have to spend the session repeating facts that are already sitting in a kickoff call or project document. The questions can focus on the decisions that are still open and the things I actually need to resolve with the client. It is still an internal workflow we're developing, but it gave us a concrete example of how grilling can fit into client work when the agent has the right context available from the start.
What the grill-me skill does#
The name is quite literal. When you type /grill-me and describe an idea, the agent starts questioning the plan before it does any implementation. It treats the plan as a design tree: some decisions can be made immediately, while others depend on choices that need to be settled first. Each question also comes with a recommended answer. You can accept it, change it or reject it, but you are responding to a concrete proposal rather than starting from an empty prompt.
The questions now come in rounds. The skill calls the set of questions that can be answered at the current point in the conversation the frontier. Anything that depends on an unresolved decision waits until that earlier choice has been made. If an implementation detail depends on the behaviour you want, for example, the skill should settle the behaviour first and only then ask about the implementation. After each round, it uses your answers to work out which decisions are ready to discuss next.
The grill-me skill itself is stateless. It does not create a specification, write files into the workspace or leave behind a separate record of the decisions. The interview lives in the conversation, and the agent waits for you to confirm that you have reached a shared understanding before it starts implementing the plan. These interviews can become fairly substantial. Pocock's documentation gives an example with forty-six questions across four rounds, which gives a good sense of how far the skill can go beyond a few quick clarifications.
Although grill-me is usually discussed in the context of coding agents, there is nothing in the skill that limits it to code. You can use it to work through a product direction, a migration plan, a business decision or a piece of writing while the idea is still taking shape. A repository only matters when there is information inside it that the agent should inspect. The quality of the interview depends much more on the context the agent has and the decisions you are trying to make than on whether there is code involved.
How the grill-me skill has changed since February 2026#
The commit history in mattpocock/skills shows how quickly the idea has changed. The first version was a single line with two sentences. By the end of March, the skill had grown to five short instructions, including the one-question-at-a-time behaviour that many articles still associate with grill-me. Later changes altered both the shape of the interview and how much work the agent is expected to do before it asks the user anything. The table below follows those changes from the first release through October 2026.
| Date | Change |
|---|---|
| 25 Feb 2026 | The first version tells the agent to interview the user about every aspect of the plan and resolve the dependencies between decisions in order. It says nothing yet about how many questions to ask at once. |
| 13 Mar 2026 | Adds a rule to inspect the codebase when it can answer a question. |
| 19 Mar 2026 | Adds a recommended answer to every question. |
| 26 Mar 2026 | Tells the agent to ask the questions one at a time. |
| 31 May 2026 | Makes grill-me a short wrapper around a separate grilling skill and limits invocation to the user. |
| 3 Jul 2026 | Adds a confirmation step before the agent can act on the plan. |
| 16 Jul 2026 | Groups questions into numbered rounds across the frontier and delegates fact-finding to sub-agents. |
| 7 Oct 2026 | Words each question so that answering "yes" accepts the recommended answer. |
Moving from single questions to rounds addressed one of the most obvious problems with the earlier version. A long interview could become slow when the agent stopped after every question and waited for another reply. Rounds let you deal with several independent decisions together while still keeping dependent questions in the right order. If you prefer the slower one-at-a-time style, the documentation suggests adding When grilling, ask one question at a time. to your global CLAUDE.md.
The repository had more than 280,000 GitHub stars when we checked the API on 13 October 2026, and the skills are published under the MIT licence, so teams can copy and adapt them for their own workflows. If you do that, it is worth checking the upstream repository from time to time. In only the first seven months, grill-me changed from a very small interview prompt into a more structured process with recommendations, rounds, fact-finding and a confirmation step before implementation.
How to install the grill-me skill#
Installation depends on the agent you are using. Claude Code and Codex install the collection as a plugin, so updates can flow through the plugin mechanism. OpenCode, Cursor and other compatible agents use the skills installer, which copies editable files into the project. The README also includes instructions for GitHub Copilot and Gemini CLI. Use one installation route for each agent; installing both the plugin and the files gives you duplicate copies of every skill.
# Claude Code
claude plugin install mattpocock-skills@claude-plugins-official
# Codex
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
# OpenCode, Cursor and other agents (leave out -a to choose interactively)
npx skills@latest add mattpocock/skills -a opencode
Once it is installed, start a fresh session and invoke /grill-me with a description of the idea you want to work through. Pocock recommends doing this with plan mode turned off. Plan mode encourages the agent to start producing a plan while the interview is still trying to work out what that plan should contain, which works against the purpose of the skill. Grill-me only runs when you call it, so it does not change the agent's normal behaviour outside the session.
Which grilling skill to use: grill-me, grilling or grill-with-docs#
The repository contains three related skills, and the names are similar enough that it is easy to mix them up. For a normal conversation, grill-me is the entry point: it runs the interview and keeps the result in the conversation. The underlying grilling skill is designed to be called from other skills, which is the option to use when you want the interview to become one stage in a larger workflow. Grill-with-docs combines the interview with codebase inspection and writes some of what it learns back into files.
| Skill | What it does | When to use it |
|---|---|---|
| grill-me | Runs an interview without writing files. | Working through an idea, with or without a repository. |
| grilling | Provides the interview loop that other skills can call. | Adding an interview stage to your own skill. |
| grill-with-docs | Reads the codebase, records terms in GLOSSARY.md and captures decisions that are difficult to reverse as ADRs. | Planning a change to an existing codebase and keeping a record of the decisions. |
In the engagement skill I showed, grilling sits inside a larger workflow rather than being a separate exercise. The answers from the interview carry into the stages that produce the research, plans and other documents afterwards, so I don't have to move between a separate interview and document-generation process or explain the same context again each time the workflow moves on.
Claude Code's built-in AskUserQuestion tool can make this slightly confusing because both can present questions to a user. They solve different problems. AskUserQuestion controls how a question is shown, including multiple-choice options. The grilling skill decides what needs to be asked, which decisions depend on one another, what the agent should research for itself and when enough has been resolved to move on. That is why a grilling session can continue through several rounds where an ordinary clarification would have ended after a single answer.
Why grilling depends on what the agent can reach#
The grilling skill already assumes that the agent should look things up for itself. Since July, its instructions have made that explicit: if a question can be answered from the environment, the agent should send a sub-agent to find the answer and only bring the real decision back to the user. In a code repository, that is straightforward because the source code and documentation are already available on disk. Client work is different. Important context may live in a recorded kickoff call, a shared drive, meeting notes or a document sent by email, none of which helps the agent unless the workflow gives it access.
For client work, I needed the agent to have access to more than a codebase. The workflow first gathers the material it may need: recorded calls come in through the recording tool's MCP connector, notes and client documents come from the shared drive, and a context extractor catalogues everything in a manifest the agent can search. In the example I showed during the session, the extractor found twenty sources for a single engagement. The workflow also checks whether there is client source code or a public link the agent should read before it starts forming a view of the engagement.
Only after that context has been gathered does the consultant type "start the grill". At that point the sub-agents have something to search, so the questions can focus on gaps in the source material and decisions that still need to be made with the client. The answers then feed into the rest of the engagement workflow: a research report, an engagement narrative, a twelve-week plan split into slices, preparation for the kickoff workshops and a slide deck that follows our brand guidelines.
The difference is mostly about where the consultant spends their attention. Without the preparation step, the agent has nothing to look up, so the early rounds are filled with questions about facts the consultant already knows or has already discussed with the client. Searching the source material costs agent time; explaining the same material again costs consultant time and attention. Bringing the context together first makes the interview more specific and removes a large number of questions that never needed to be asked.
When a grilling session becomes a burden#
A grilling session only works if the person being interviewed is actually thinking about the recommendations. The format makes passivity surprisingly easy. If the agent gives you forty suggested answers and you keep accepting them without checking the reasoning, you can reach the end with a plan that was mostly decided by the model. Pocock's documentation calls this the passivity problem. Since 7 October, questions are deliberately phrased so that a simple "yes" accepts the recommendation. That makes a round quick to complete, but it also makes it easy to approve assumptions you have not properly considered. The user still needs to challenge bad suggestions, add missing constraints and correct anything the agent has misunderstood.
The other limit is scope. Once the interview grows into hundreds of questions, it becomes difficult to keep the conversation coherent, and the later questions may suffer as the context window fills up. Pocock's documentation recommends splitting the work into smaller pieces if a grill reaches roughly two hundred questions and interviewing those parts separately. There is a similar issue in longer agentic workflows generally: the more later work depends on earlier decisions, the more opportunity there is for an early mistake to spread through everything that follows.
Some decisions also do not improve just because the agent asks more questions. A choice such as whether a form should be one page or three can be much easier to judge once you can see both versions. The documentation describes these as "ungrillable" questions and suggests building a throwaway prototype instead. If the interview keeps circling around the same decision without making progress, creating something concrete to react to is often more productive than continuing the discussion in the abstract.
For a small, low-risk change, a full grilling session may be unnecessary. Asking the agent to challenge the plan or point out missing considerations can be enough. The structured interview becomes more valuable when several decisions depend on one another and changing an early choice later would be expensive. Its main contribution is not that it asks more questions; it is that it tries to settle those decisions in an order that reflects their dependencies.
What to do with the output of a grilling session#
Because grill-me is stateless, the decisions disappear with the conversation unless you record them somewhere else. That is fine for an idea you are exploring on your own. It becomes a problem when the work continues across sessions, moves to another person or needs to be reviewed by a team. In those cases, the agreed decisions belong in a specification, ADRs or an engagement plan, along with enough context to understand why an option was chosen or rejected.
In a spec-driven development workflow, the grilling session comes before the specification. Decisions that have been settled can become requirements, while anything that is still unresolved can be written down as an assumption or open question for review. The specification then becomes the durable record that people and agents can work from. We cover that process in What is spec-driven development?, and Pocock's repository also includes a separate skill for turning the result of an interview into a specification.
Writing the decisions down does not remove the need for human review. In my engagement workflow, nothing is synchronised back to the shared drive until the consultant has read it and corrected it. Even after a detailed interview, the model can still make claims that are not true of the client or reach a conclusion the consultant would not stand behind. The grill gives the model better information before it generates the deliverables, but the consultant is still responsible for making sure those deliverables accurately reflect the engagement.
Sources and further reading#
- mattpocock/skills: the repository and commit histories for grill-me, grilling and grill-with-docs, published under the MIT licence.
- Use The /grill-me Skill, AI Hero: how to run a grilling session.
- 9 Things People Get Wrong With /grill-me and /grill-with-docs, AI Hero: common mistakes, including "ungrillable" questions.
- The grilling skill and the grill-with-docs skill: the interview loop and the variant that reads and records codebase decisions.
Related articles#
- Agentic AI Architecture: The Intent Plane and the Execution Plane: how planning connects to agent execution.
- What is spec-driven development?: turning agreed decisions into a reviewed specification.
- Give Claude Code Persistent Memory of Your Codebase: keeping the context an agent gathers available across sessions.
- Why We Teach Agentic Coding Backwards: how we teach planning and review before generation.
