Preface

When building features with AI programming tools, the common failure is rarely that the model cannot write code, but rather that the Agent starts coding before the requirements and solution are fully aligned. You casually mention an idea, and it quickly provides a directory structure, interfaces, and implementation steps; it looks complete, but only later do you realize that several critical branches were never addressed: Should we maintain compatibility with old data? How should errors be exposed? Who is responsible for handling edge cases.

Matt Pocock attributes this type of failure to a communication gap between humans and Agents. His proposed solution in the public skill repository mattpocock/skills is to first hold a grilling session: instead of rushing to produce a solution, clarify all assumptions through a decision tree. One public entry point for this is grill-me. The official README lists it alongside the companion grill-with-docs as the two most commonly used skills in this suite.

What It Is

grill-me is an Agent Skill that you trigger manually. Its scope is narrow: take a half-formed idea and refine it through systematic questioning until you can commit to a plan. The official documentation emphasizes that it is stateless—it works without a repository, does not write files to your workspace, and does not assume the subject matter is necessarily code. You can use it for feature directions, product tradeoffs, business decisions, or even the structure of an article.

It is maintained by Matt Pocock, with its source code located in the GitHub repository mattpocock/skills under skills/productivity/grill-me/. Supporting documentation is published at both aihero.dev/skills-grill-me and the repository’s docs/productivity/grill-me.md, with identical content on both sides. There is also a standalone installation page at skills.sh.

Within the current repository, grill-me’s own SKILL.md is very brief:

---
name: grill-me
description: A relentless interview to sharpen a plan or design.
disable-model-invocation: true
---

Run a `/grilling` session.

The line disable-model-invocation: true means the Agent will not activate this skill on its own—you must explicitly input /grill-me. The actual interview loop lives in the companion grilling skill in the same repository. The official grilling documentation states plainly: if you only install grill-me and not grilling, running the command will typically do nothing.

Core Mechanism

grilling models a topic as a design tree: each decision has dependent follow-up decisions. Each round only asks questions at the current frontier—questions whose prerequisites have already been confirmed and can be answered honestly right now. The questions in a single round cannot depend on one another; after you answer, the tree will grow, and the next round of questions will follow.

Each question follows a fixed format from grilling’s SKILL.md:

❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>

➡️ <your recommended answer>

This allows you to answer by number, for example “1 Yes, 2 Choose the second option, 3 No, because…”, without needing to copy the entire question back. The official also warns about an edge case: sometimes the recommended answer will argue against the premise of the question itself. In this case, agreeing with the recommendation means answering “No” to the original question, so you need to clarify whether you are responding to the recommendation or the original question.

Facts and decisions are separated. Facts that can be retrieved from the file system, code, or tools will be looked up by the Agent itself, with sub-Agents deployed if necessary—these will not be asked of you. The lookup process does not block the current round; only follow-up questions that depend on this query will wait. All decisions must be left to you. If the Agent makes a call on your behalf, that is off-track behavior, not “flexible understanding”.

There are two layers of conditions for ending a session: the frontier is empty, and you confirm that both parties have reached a shared understanding. Before confirmation, it should not begin implementation.

The official provides a rough reference: a typical grill-me session runs about four rounds with over forty questions. You should track progress by the number of rounds, not the number of questions asked, to avoid anxiety. Another note in the grilling documentation says: thirteen questions typically fall into about three rounds, rather than thirteen separate rounds. Both figures describe round-based progression, not a fixed quota.

Installation and Activation

grill-me uses the universal SKILL.md format and works with tools that support Agent Skills, such as Claude Code, Codex CLI, and Cursor. Matt Pocock’s repository offers two official installation paths with different philosophies—choose one; installing both will result in duplicate copies of the skill.

  1. Claude Code plugin: Full package, read-only, and follows the author’s updates:
   claude plugins install mattpocock-skills

You can also run this in a chat session:

   /plugin install mattpocock-skills

This plugin is already listed in the Claude Code official marketplace, so you do not need to add a custom source first.

  1. Install via the skills.sh installer to copy files into your project. The files belong to you and can be modified, and will not receive automatic background updates. This path is recommended for Codex and other Agents:
   npx skills@latest add mattpocock/skills

The installer will let you select which skills to install and which coding Agents to target. If you only want to install grill-me, the command provided on the skills.sh page is:

   npx skills add https://github.com/mattpocock/skills --skill grill-me

When installing only individual skills, be sure to also install grilling alongside it. A full package installation or the Claude Code plugin will include both skills automatically. You can pull author updates later with npx skills update.

Once installed, input /grill-me in a new chat session along with your loosely defined idea. The official explicitly recommends turning off Plan mode: Plan mode pushes the Agent to produce a plan quickly, which runs counter to the goal of pausing to ask clarifying questions. Do not use this skill to grill an already drafted solution—start from a blank chat instead.

Typical Usage

A minimal startup example looks like this:

/grill-me

I want to add an "export report" feature to our internal backend, but I haven't finalized the format, permissions, or how to handle failure alerts.

The Agent should first present a full round of frontier questions, each with a recommended answer, then pause and wait for your input. You can answer by number, push back on the questions, or say “I don’t know”. The official considers “I don’t know” a valid response; questions you cannot answer often indicate that the matter cannot be resolved through discussion alone, and you should first build a throwaway prototype instead of guessing.

If you prefer to ask only one question at a time, the official support recommends adding this line to your global CLAUDE.md (or the equivalent Agent configuration file in other tools):

When grilling, ask one question at a time.

The grilling documentation notes that the default round-based question behavior is controversial. Many users who read slowly, work in a second language, or need one question at a time to maintain focus will switch to this per-question mode. This is an officially supported customization, not a compromise. The previously available /batch-grill-me has been merged into grilling, so there is no need to install it separately anymore.

After finishing the grilling session, do not start a new chat to write the specification. The official reasoning is that the context built during this session is its core value, and you can directly pass this same chat to the companion to-spec skill in the same repository to continue the downstream construction process. to-spec is not a required part of grill-me, only an optional path for turning your idea into final software.

Applicable Scenarios and Notes

Scenarios where grill-me is suitable:
- You have only one idea worth taking seriously, but the details have not been fleshed out. Ambiguity is not a reason to wait—it is exactly what this session is meant to resolve.
- The subject matter does not have to be code: features, product directions, business decisions, or writing structures all work.
- You do not currently have a working directory, or do not want to write any files to your repository.

Scenarios where you should not use grill-me or should use a different entry point:
- You can already state the matter precisely, so no further grilling is needed.
- You need to align on an existing codebase and want to document terminology and hard decisions in the repository—use the companion grill-with-docs instead. It runs the same interview process but is stateful, maintaining CONTEXT.md and ADRs.
- The workload is too large for a single session—use wayfinder instead. It will map out your work first, then run grilling sessions within that framework.
- Questions like “Should this be a long article or three pages?” or “What should this interaction feel like?” are what the official calls ungrillable: they cannot be resolved through conversation alone. You should pause to build a quick throwaway prototype, review it, then return to answer with a single sentence.

There are several official pitfall notes for using this skill:
Passive agreement is the primary failure mode. Blowing through a session by agreeing to forty consecutive questions will result in an Agent-written plan paired with your mere assent, and the passage of time creates a false sense of certainty. You need to take active control: push back if questions are too shallow, speak up if the scope drifts, and admit when you do not know. The quality of the output depends on your answers, not the number of questions asked. Conversely, getting stuck in endless questioning without ever writing code is a rarer but real opposite problem.

If a session balloons to two hundred questions, the scope is almost certainly too broad. Ask the Agent to break the work into smaller pieces first, then grill each one individually. Once the context window is full, question quality will decline as well. The official does not provide a hard cap on the number of questions, arguing that a fixed limit will either cut off difficult cases or feel arbitrary for simple ones. You can control the scope using natural language to narrow it down, or accept the portion of the work that has already been aligned on.

Model choice matters more than it does for most skills. Grilling relies on the model’s own judgment of where the system might have gaps, so the official recommends using your best available model. Once you have the finalized context for actual coding, cheaper models can often handle the work just fine. Weaker or non-cutting-edge models sometimes condense the “reach consensus through questioning” step into two or three rounds, then dump an outline and immediately start writing code. The reliable fix is to explicitly state in your AGENTS.md or CLAUDE.md: Do not implement anything without explicit permission.

Another known quirk: calling one skill from another does not guarantee that the target skill will be loaded. If a purported grilling session dumps all questions at once without any ➡️ recommended answers, the model is likely running an ad-hoc interview instead of using the grilling skill. Simply asking it if it has loaded grilling will usually correct this.

The official also provides concrete signals to confirm whether the session is working correctly:
1. Each round is a numbered list with ➡️ recommended answers, and you can respond by quoting the question numbers.
2. Questions in the same round do not depend on one another.
3. Subsequent rounds will ask questions that could not have been asked in earlier rounds.
4. The Agent will look up factual information on its own instead of asking you.
5. The session will first confirm shared consensus before beginning any implementation work.

Summary

grill-me does one very restrained thing: before the Agent starts coding, it uses round-based decision tree questioning to surface hidden assumptions. It does not write to repositories, does not replace your decision-making, and is not a complete research and development workflow. When viewed alongside its companion skills grilling, grill-with-docs, and wayfinder, it serves as the user-facing entry point that works anytime, anywhere, without relying on a repository.

Official links:
- Skill directory: https://github.com/mattpocock/skills/tree/main/skills/productivity/grill-me
- SKILL.md: https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md
- Documentation: https://aihero.dev/skills-grill-me
- skills.sh: https://skills.sh/mattpocock/skills/grill-me
- Skill suite repository: https://github.com/mattpocock/skills