mattpocock-grill-with-docs
mattpocock/grill-with-docs
A two-line wrapper that turns a design interview into a glossary and ADRs written as you go.
The whole SKILL.md is one instruction: Call the Skill tool twice, for "grilling" and "domain-modeling". All the behavior lives in those two skills, so this page explains them. Matt calls the grill skills my most popular skills.
Who it is for
Anyone about to change code who wants the agent to understand the plan, and the project’s words, first.
What you get
A settled plan, plus GLOSSARY.md entries and docs/adr/ files created only when there is something to record.
Misalignment Is The Most Common Failure
From the repo README.
The most common failure mode in software development is misalignment.
The fix for this is a grilling session - getting the agent to ask you detailed questions about what you're building.
Agents are usually dropped into a project and asked to figure out the jargon as they go. So they use 20 words where 1 will do.
It's hard to explain how powerful this is. It might be the single coolest technique in this repo. That is Matt on the shared-language half.
A Design Tree, Worked One Frontier At A Time
grilling supplies the interview; domain-modeling supplies the side effects.
The design tree
Map this as a design tree: every decision branches into the decisions that hang off it.
The frontier
The frontier is every decision whose prerequisites are already settled
Facts vs decisions
Finding _facts_ is your job, never the user's. The _decisions_ are the user's: put each to them and wait.
Docs as a side effect
When a term is resolved, update GLOSSARY.md right there.
Two Words In SKILL.md, Four Files Of Behavior
Click a part. Quotes are checked against the file named under each.
Each Round Asks Everything It Can, Then Waits
The round format, copied from grilling/SKILL.md.
❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices> ➡️ <your recommended answer> --- ❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices> ➡️ <your recommended answer>
Format of one round.
Ask the whole frontier in one round: number each question and give your recommended answer.
When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it
When the user uses a term that conflicts with the existing language in GLOSSARY.md, call it out immediately.
When the user states how something works, check whether the code agrees.
The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed.
Use One Of Three, Not All Three
| Skill | What loads | Writes files? | Use when |
|---|---|---|---|
grill-me | grilling | No | Non-code plans and ideas |
grill-with-docs | grilling + domain-modeling | GLOSSARY.md, docs/adr/ | Code changes in a repo |
grilling | itself | No | The agent reaches for it on its own (model-invoked) |
| Signal | Number | Source |
|---|---|---|
| grill-me installs | 1.4M | skills.sh, 23 Oct 2026 |
| grill-with-docs installs | 1.2M | skills.sh |
| grilling installs | 979K | skills.sh |
| Matt: Meta’s Muse Code ships /grill and /grill-with-docs | 959 likes, 6 Aug 2026 | x.com/mattpocockuk |
Lauren Tan On Why Grilling Works
From the stream with Matt, auto transcript, verbatim.
“And that's why sort of grilling, I think, works effectively. Grilling is a Yeah. Yeah. It it draws those words out of you, right?”Lauren Tan (poteto), stream with Matt Pocock, 8:59
“someone might find a lot of success combining, you know, like your grill me with docs, uh, or wayfinder skill with some of the execution skills in Pstack as an example.”Lauren Tan (poteto), stream with Matt Pocock, 1:01:54
It Is Only As Good As The Skill Loader
From reading every file at 5beb35b. No scripts ship, so there was nothing to run.
Gap Depends on a “Skill tool”
The whole body is “call the Skill tool twice”. In an agent without a skill-loading tool, the wrapper does nothing unless grilling and domain-modeling are installed and the agent opens them itself.
Gap Name clash with pstack
pstack has principle-model-the-domain, which is about stateful code shape, not glossaries. Different jobs, similar names; keep both.
Gap README still mentions CONTEXT.md
The README example links a glossary “still named CONTEXT.md” from before the rename. The skills now use GLOSSARY.md.
Cost Rounds are long
Asking the whole frontier at once means big first rounds. Answer “yes” to accept a recommendation.
Copy Lazy files
No empty GLOSSARY.md or docs/adr/ until a term or decision is actually settled.
Grill First, Then Hand The Settled Plan To pstack
pstack has no skill that interviews you about the plan. These are the hand-offs that fit.
| pstack skill | What pstack says it does | How it pairs |
|---|---|---|
architect | “Sketch types, signatures, and module structure before code” | Feed it the settled answers and new glossary terms; type names follow the glossary. |
in-your-own-words | “Restate in your own words what you think the user's goals are” | Run it after grilling as a cheap check that the agent really understood. |
interrogate | “Multiple LLM reviewers challenge changes from independent angles” | grill-with-docs reviews your thinking; interrogate reviews the resulting code. |
tdd | “Use only when the user explicitly asks for TDD” | Glossary terms become test names. |
create-verification-skill | “Generate a project-local verification skill that drives your app the way a user does” | What Lauren calls the most important skill; grilling cannot replace it. |
“verification I would say is probably the most important skill in PAC”Lauren Tan (poteto), stream with Matt Pocock, 18:43
Read The Two Engines
- skills/engineering/grill-with-docs/SKILL.md
- skills/productivity/grilling/SKILL.md
- skills/engineering/domain-modeling/SKILL.md
- skills/engineering/domain-modeling/ADR-FORMAT.md
- skills/engineering/domain-modeling/GLOSSARY-FORMAT.md
- skills/productivity/grill-me/SKILL.md
- Matt on Muse Code copying grill
- github.com/mattpocock/skills: the repo and its README
- skills.sh/mattpocock/skills: install counts per skill
- Inside pstack: the pstack explainer on this site
- Matt Pocock with poteto, live: the stream quoted here
- mattpocock/wayfinder uses grill-with-docs’ pair for every grilling ticket