grill-me: Make Your Agent Interview You Before It Writes Code

I have a rule I tell every developer I mentor: the agent that asks you questions is worth ten agents that don't. Most of the bad code an AI writes isn't bad because the model is dumb. It's bad because the model guessed. You said "add a settings page" and it invented twelve assumptions you never stated, built all of them, and now you're staring at a diff that's 80% correct and 20% wrong in ways that are tedious to unwind.

grill-me is Matt Pocock's answer to that, and it's the most popular skill in his collection for a reason. It does one thing: before the agent writes a single line, it interviews you about what you actually want. It grills you. It surfaces the assumptions, drags the ambiguity into the open, and only then starts building. It's small, it composes with everything else, and it embodies a philosophy I happen to agree with strongly — that the tools you use to build with AI should give you more control, not quietly take it away.

This guide covers the skill itself, the philosophy behind it, how the interview actually works, when to reach for grill-me versus its more powerful sibling grill-with-docs, the rest of Matt's collection, and how to wire these small skills together into something that fits how you actually work.

What grill-me is, in one sentence

grill-me is a Claude Code skill that flips the default. Instead of "describe what you want and the agent builds it," it's "describe what you want, the agent asks you sharp questions until the ambiguity is gone, and then it builds it."

That's the whole idea. The value is entirely in the gap between what you said and what you meant.

Here's the thing about requirements: you never give them all at once. You give the headline ("a checkout flow") and you hold the details in your head as a fuzzy cloud of half-decisions. Some of those decisions you've genuinely made. Some you think you've made but haven't. Some you don't even know are decisions yet. A good engineer pulls those out of you with questions. grill-me makes the agent do the same.

Install is one line via Vercel's skills CLI:

npx skills@latest add mattpocock/skills

That pulls in Matt's whole collection. You then invoke grill-me by name when you want to be interviewed before a build.

The philosophy: small, composable, and against all-in-one

To understand why grill-me is shaped the way it is, you have to understand what Matt is reacting against. There's a whole genre of AI dev tooling right now built around owning your entire process — heavy spec-driven systems that want you to write a formal spec, generate a plan, decompose into tasks, and execute, all inside one rigid pipeline. Matt's position, and I share it, is that these systems are cumbersome and that they cost you something you don't notice until it bites: control.

When a system owns your whole process, it also owns your bugs. And the worst bugs in an AI workflow aren't bugs in your code — they're bugs in your process. A step that always pulls in too much context. A planning phase that hallucinates structure. When that process lives inside a monolith, you can't reach in and fix the one broken step. You either accept it or abandon the whole system.

Small composable skills don't have that problem. Each one does a single, legible thing. If grill-me's interview gets too aggressive for a particular task, you skip it that time — you don't fight a framework. If you want the interview but not the test-driven loop, you take one and leave the other. You assemble your process out of parts you understand, and when a part misbehaves, you swap that part.

I think about it like the Unix philosophy applied to agent workflows. grep doesn't try to be your editor. grill-me doesn't try to be your whole methodology. It interviews you. That's it. And because it's that focused, you can actually reason about what it does and trust it.

There's a second-order benefit that's easy to miss. Small skills are readable. You can open the SKILL.md, read the instructions in two minutes, and know exactly what behavior you're invoking. Try doing that with a 4,000-line spec framework. The legibility is the point. You're not delegating your judgment to a black box; you're handing the agent a short, inspectable set of instructions and keeping the steering wheel.

How the interview actually works

When you invoke grill-me, the agent stops being eager. Instead of jumping to a solution, it reads your request, identifies what it doesn't know, and asks you about it — usually in small batches so you're not staring at a wall of twenty questions.

The questions tend to fall into a few categories. Once you've seen the pattern, you'll start asking them of yourself before the agent even gets the chance.

Scope and boundaries

The first thing a good interview establishes is the edges. What's in, what's out.

• What exactly are we building right now, and what are we explicitly not building?
• Is this a throwaway prototype or production code? (The answer changes everything downstream.)
• Are we touching existing code or starting fresh?
• What's the smallest version of this that would be useful?

That last one is the most valuable question in software and almost nobody asks it unprompted. grill-me does.

Behavior and edge cases

Once scope is pinned, the interview moves to behavior — and specifically to the cases you didn't mention because they felt obvious to you.

• What happens when the input is empty? When it's malformed? When the network call fails?
• What should the user see while it's loading? When it errors?
• Are there permissions or auth concerns?
• What's the expected scale — ten records or ten million?

These are the questions that separate a demo from a thing you can ship. You knew the happy path when you wrote the request. The agent forces the unhappy paths into the open.

Constraints and context

Then come the questions about the world the code lives in.

• What's the existing tech stack and what are we constrained to?
• Are there conventions in this codebase I should follow?
• Are there libraries you want to use or avoid?
• Any performance, bundle-size, or accessibility requirements?

Decisions you didn't know you were making

This is the category that earns grill-me its name. Every feature hides forks in the road, and the agent's job is to make you choose consciously rather than letting it choose for you.

You said	Hidden decision the interview surfaces
"Add a search box"	Debounced or on-submit? Fuzzy or exact? Searches what fields?
"Save the user's settings"	Where — localStorage, server, both? Optimistic UI or wait for confirm?
"Send a notification"	Email, in-app, push? Immediate or batched? Retry on failure?
"Let users upload a file"	Size limits? Allowed types? Where does it get stored? Virus scan?
"Add pagination"	Offset or cursor? Page size? What about deleted items mid-scroll?

Each row is a place where the agent, left to its own devices, would have silently picked one option and built it. The interview turns the silent pick into your explicit choice.

When the interview stops

A good interview is not infinite. The skill is designed to stop when the remaining ambiguity is small enough that the agent can fill the gaps with reasonable defaults and tell you what defaults it chose. The signal to stop is roughly: "I now know enough that any remaining decisions are low-stakes and reversible."

That's an important nuance. grill-me isn't trying to extract a perfect specification. It's trying to eliminate the expensive ambiguity — the stuff that, if guessed wrong, means rewriting big chunks. Cheap ambiguity (what to name a variable, exact wording of a label) it lets go. The skill explicitly instructs the agent to state its remaining assumptions out loud before building, so even the gaps are visible.

Turning answers into a build

Once the interview wraps, the agent summarizes what it heard — a compact statement of scope, behavior, constraints, and the decisions you made — and confirms it with you. Then it builds against that summary.

This summary step matters more than it looks. It's a cheap checkpoint. Reading a five-line summary takes you ten seconds and catches the misunderstanding before the agent writes 300 lines against it. I've watched developers save themselves an entire afternoon because the summary said "stores settings in localStorage" and they went "no, server-side, it has to sync across devices." Ten seconds versus an afternoon.

Here's roughly what that handoff looks like in practice:

You: Build me a rate limiter for the API.

Agent (grill-me):
  Before I build, a few questions:
  1. Per-user, per-IP, or global?
  2. What's the limit and window — e.g. 100 req / minute?
  3. In-memory or backed by Redis? (Affects whether it survives restarts
     and works across multiple instances.)
  4. What should a blocked request get back — 429 with Retry-After?
  5. Do certain routes need different limits?

You: Per-user. 100/min. Redis. 429 with Retry-After. Auth routes
     should be stricter — 10/min.

Agent:
  Got it. Summary:
  - Per-user token-bucket limiter, Redis-backed (survives restarts,
    works across instances)
  - Default 100 req/min; auth routes 10 req/min
  - Blocked requests get 429 + Retry-After header
  - Assumption: user identified by the auth token's subject claim;
    unauthenticated requests fall back to per-IP. Flag if wrong.
  Building now.

Notice the agent stated an assumption it didn't ask about — the unauthenticated fallback — rather than silently coding it. That's the behavior grill-me is reinforcing: surface the decision even when you don't want to spend a question on it.

grill-me vs grill-with-docs

grill-me has a more powerful sibling: grill-with-docs. They share the interview DNA but differ in what they leave behind.

• grill-me runs the interview and goes straight to building. The understanding lives in the conversation and then evaporates when the session ends. Perfect for a single, contained task.
• grill-with-docs runs the interview and writes a shared-language document — a durable artifact that captures the decisions, the vocabulary, and the shape of the thing you're building. That document pays off across sessions.

Why does the document matter? Because the most expensive thing in a long AI project isn't writing code, it's re-establishing context. Every new session, the agent starts cold. Every time you come back after a week, you've forgotten half the decisions you made. grill-with-docs captures the shared language once — what you mean by "account" versus "user," what the lifecycle of an order is, which invariants must hold — so the next session starts warm. You point the agent at the doc and it already speaks your dialect.

Here's how I decide between them:

Situation	Reach for
One-off task, contained, finished today	grill-me
A feature you'll iterate on over days or weeks	grill-with-docs
Onboarding the agent to a domain with its own vocabulary	grill-with-docs
Quick bug fix where you basically know the answer	Neither — just ask
Multi-session greenfield project	grill-with-docs, early

The rule of thumb: if the understanding has a lifespan longer than this conversation, write it down. If it's disposable, don't bother. grill-with-docs is the difference between interviewing someone and interviewing them while taking notes you'll actually reread.

The honest downside

I promised you no hype, so here's the honest part: grill-me can be annoying.

When you know exactly what you want, when the task is genuinely trivial, when you just want to ship the thing — being interrogated is friction. You typed "fix the typo in the header" and the agent wants to know about your accessibility requirements. No. Stop. Just fix it.

This is a real failure mode and you should be clear-eyed about it. The skill's value scales with the ambiguity of the task. High ambiguity, high payoff. Low ambiguity, the interview is overhead you don't need. The skill is composable precisely so you can not invoke it when it's the wrong tool. Don't make it your default for everything; make it your default for anything where you can feel yourself hand-waving.

My personal heuristic: if I can describe the task in one sentence and there's exactly one obvious way to do it, I skip grill-me. If my one-sentence description hides three or more decisions, I grill. The moment I notice myself thinking "the agent will probably figure out the details" — that's the tell. "Probably figure out the details" is exactly the assumption-generation machine grill-me exists to stop.

The rest of Matt's collection

grill-me is the star, but it lives in a family of small skills that compose with it. Knowing the siblings is how you get the most out of the whole approach.

tdd — red, green, refactor

A skill that drives the classic test-driven loop: write a failing test (red), make it pass with the simplest code (green), then clean up (refactor). The reason this pairs so well with grill-me is that the interview produces exactly the thing TDD needs — clear, specific behavior. Once you've grilled out "blocked requests get a 429 with a Retry-After header," that's not a vague intention anymore, it's a test you can write. Interview to define behavior, then TDD to lock it in.

diagnose — debugging discipline

diagnose brings structure to debugging: form a hypothesis, gather evidence, isolate the cause, confirm with a test, then fix. It's the antidote to the agent's worst debugging habit — changing five things at once and declaring victory when the symptom disappears. diagnose makes it move one variable at a time, like an actual scientist. When something breaks mid-build, you switch from building skills to diagnose, fix it, and switch back.

improve-codebase-architecture — rescue the spaghetti

For when you've inherited (or grown) a tangle. This skill is about restructuring messy code into something maintainable — identifying the seams, untangling dependencies, proposing a cleaner shape before tearing anything apart. It's deliberately slow and deliberate, because the failure mode of architectural cleanup is making a huge change that breaks everything subtly. Pairs naturally with grill-with-docs: interview to capture how the system is supposed to work, then restructure toward that.

caveman — spend fewer tokens

A pragmatic one. caveman reduces token cost by making the agent communicate and reason more tersely — fewer words, less ceremony, more signal. When you're running a lot of agent turns and watching the bill, it's a real lever. It trades some of the agent's verbose explanation for economy. Use it when you trust the process and don't need the agent narrating every step.

Here's the family at a glance:

Skill	Does	Reach for it when
grill-me	Interviews you before building	The task hides decisions
grill-with-docs	Interviews + writes a shared-language doc	The understanding outlives the session
tdd	Red-green-refactor loop	Behavior is well-defined and worth locking in
diagnose	Structured debugging	Something's broken and you don't know why
improve-codebase-architecture	Restructures messy code	You've inherited spaghetti
caveman	Cuts token usage	You're optimizing cost over verbosity

Combining the skills

The whole point of composability is that you chain these to fit the task. A few combinations I actually use:

Greenfield feature, multi-session. Start with grill-with-docs to interview and capture the shared language. Then tdd to build against the behaviors the interview surfaced. The doc keeps every later session anchored to the same decisions.

Contained one-off. Just grill-me, then build. No doc, no test ceremony if it's throwaway. In and out.

Inherited mess you need to extend. grill-with-docs to capture how the system actually works and how it's supposed to. Then improve-codebase-architecture to clean the seam you need to touch. Then tdd to add the new behavior safely. Then, if you're running it on autopilot over many turns, caveman to keep the cost down.

Production bug. diagnose to find it, tdd to write a failing test that reproduces it, then fix to green. The test becomes a regression guard so the bug can't quietly return.

The reason this works is that none of these skills fight each other. They're not competing frameworks; they're tools on a bench. You pick up the one the moment needs and set it back down. That's the composable philosophy delivering on its promise — your process is yours, assembled from legible parts, and when one part is wrong you fix that part instead of abandoning the whole thing.

Where this fits in the broader skill ecosystem

If you've read my other write-ups, you'll recognize the family resemblance to the broader skills movement. The big, batteries-included collections like superpowers give you a huge surface area in one install. Matt's collection sits at the opposite end of the spectrum on purpose: minimal, sharp, each skill a single idea. Neither is wrong. They're different bets about how much process you want a tool to own.

My advice is to hold both. Use a broad collection for the long tail of capabilities you'd never write yourself, and use Matt's focused skills for the parts of your workflow where you want maximum control and legibility — the interview, the test loop, the debugging discipline. If you're serious about getting agents to use the right amount of context at the right time, pair grill-me's up-front clarity with the practices in context-engineering. The interview is, after all, a context-engineering act: it front-loads the precise information the agent needs and strips out the guessing.

And if you're just getting oriented in this whole space, the interview-first mindset is the single highest-leverage habit you can build. Everything else — TDD, diagnosis, architecture — gets easier once you stop letting the agent guess.

Resources & links

External tools and repos:

• mattpocock/skills on GitHub — Matt Pocock's full collection, including grill-me, grill-with-docs, tdd, diagnose, improve-codebase-architecture, and caveman.
• Vercel skills CLI — the npx skills@latest add installer used to pull the collection.
• Claude Code — the agent harness these skills run inside.

Related skills on this site:

• superpowers — the batteries-included end of the spectrum, for contrast.
• context-engineering — get the right context in front of the agent; pairs with the interview-first habit.
• karpathy-guidelines — principles for keeping agents on a short, legible leash.
• skilld — more on building and shipping your own skills.

Guides and tracks to go deeper:

• The most popular AI coding skills — where grill-me ranks and why.
• Spec-driven development with AI agents — the heavier approach Matt is deliberately reacting against, so you can judge the tradeoff yourself.
• The complete prompt engineering guide for 2026 — the interview is structured prompting in disguise.
• The agentic automation track — the full learning path this skill belongs to.