Source: mattpocock/skills · Maintainer: community: Matt Pocock · License: MIT · Checked: 24 October 2026
What is the grill with docs skill?
The grill with docs skill makes your coding agent interview you about a plan or design until you both share one understanding of it, and writes the project's vocabulary and its hard decisions into your repo while you talk. It is for developers starting a change in an existing codebase, before any spec or code exists.
It lives in mattpocock/skills, which Matt Pocock describes in the README as "My agent skills that I use every day to do real engineering - not vibe coding." The skill's description reads: "A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go."
The README calls the shared language this skill builds "the single coolest technique in this repo", and names /grill-me and /grill-with-docs as "my most popular skills". As of 24 October 2026, its skills.sh page listed about 1.2 million installs (snapshot, 24 October 2026).
What does it do?
The folder is small: a SKILL.md and agents/openai.yaml (Codex display metadata, "Grill with Docs"). The whole instruction in the SKILL.md is one line: "Call the Skill tool twice, for "grilling" and "domain-modeling"."
So the behavior comes from two other skills in the same repo:
- grilling runs the interview. The agent maps your plan as a design tree, asks every question it can ask without guessing at answers it hasn't heard yet, in one numbered round with a recommended answer for each, then waits. It looks up facts in the code itself rather than asking you.
- domain-modeling does the writing. Terms go into
GLOSSARY.mdthe moment they settle, and decisions that qualify become ADRs.
The repo's docs for grill-with-docs call it "stateful": other grilling skills leave the session in your head, this one leaves files on disk. Here is where each outcome lands:
| What resolved | Where it lands |
|---|---|
| A term (the project's own word for a thing) | GLOSSARY.md, as soon as it resolves |
| A decision that is hard to reverse, surprising without context, and a real trade-off | An ADR under docs/adr/ |
| Everything else you decided | The conversation only |
The glossary goes at the repo root, or in each context's folder if a GLOSSARY-MAP.md marks the repo as multi-context. Neither file exists until the first term or decision settles, so there's nothing to set up in advance.
It is user-invoked. The frontmatter sets disable-model-invocation: true, which per the Claude Code skills docs means Claude can't invoke it on its own. You type /grill-with-docs.
How do you install it?
The README offers a plugin route and an editable-files route, and says to pick one per agent so you don't get every skill twice.
Claude Code plugin (whole set, updates itself). The collection is in Anthropic's official plugin marketplace:
claude plugin install mattpocock-skills@claude-plugins-official
Plugin skills are namespaced, so this one appears as /mattpocock-skills:grill-with-docs.
Codex plugin. From the README:
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock
Editable files with the skills CLI. The command on skills.sh is:
npx skills add https://github.com/mattpocock/skills --skill grill-with-docs
That alone is not enough. The docs say "Installing grill-with-docs alone gets you a skill that does not work." The skills CLI accepts --skill more than once, so take the two dependencies in the same command:
npx skills add https://github.com/mattpocock/skills --skill grill-with-docs --skill grilling --skill domain-modeling
Add -g to install for all projects. In Claude Code the folders land in .claude/skills/ in your project, or ~/.claude/skills/grill-with-docs/ and its siblings with -g. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
If you install the engineering set, the README also asks you to run /setup-matt-pocock-skills once per repo, which records your issue tracker, triage labels and where docs go.
How do you use it?
Start it at the beginning of a change, when the plan is still fuzzy and the words for things aren't settled. The docs position it as the single-session tool: a change you can settle in one sitting.
Example prompts (suggestions, not quotes from the repo):
/grill-with-docs I want to add team accounts so several users share one billing plan./grill-with-docs We need to support refunds. Push back on anything vague in how I describe it./grill-with-docs Help me document my repo.(the docs suggest this for a codebase with no domain docs at all)/grill-with-docs Plan the move from cron jobs to a queue for sending emails.
Answer each round, or reply "yes" to accept the agent's recommendation. The docs list signs it is working: GLOSSARY.md changes during the session term by term, questions the code can answer get answered from the code, and you get few or no ADRs.
When it ends, the docs point you to to-spec in the same conversation, so the decisions that only exist in the chat get written down. The repo's main chain is:
grill-with-docs → to-spec → to-tickets → implement → code-review → retro
Requirements: a repo where the agent may write files, plus the grilling and domain-modeling skills. No packages or API keys.
Tips and limits
From the repo's docs, not from testing:
- Most decisions stay in the chat. An ADR needs all three conditions at once, and the glossary holds only vocabulary. The docs call this "the most serious open complaint about the skill." Keep the session and hand it to
to-specrather than clearing it. - Watch for a half-loaded skill. If the agent asks everything at once with no recommendations and never mentions
GLOSSARY.md, it didn't load its two dependencies. If grilling loads but domain-modeling doesn't, you get a good interview with no files. The docs suggest asking the agent which skills it loaded. - Inside other frameworks, files may not appear. Users report that when it runs as a step in someone else's pipeline, the interview runs but nothing is written. The docs say this bug is filed and unfixed.
- Too big for one session? The docs point to the repo's
wayfinderskill for efforts that need several sessions.
The skill runs no scripts. As of 24 October 2026, skills.sh showed Pass from all three security audits (Gen Agent Trust Hub, Socket and Snyk). The repo is MIT licensed, so you can copy and change it as long as you keep the copyright notice.
Save it in your Kipt library
In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Then import grilling and domain-modeling the same way, from their own folder links, because grill-with-docs does not work without them. Your copies live as Markdown in your own private GitHub repo and install into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Matt Pocock or mattpocock/skills.
Similar skills
- Grill me skill: the same interview with no repo and no files, for non-code plans too.
- Domain modeling skill: the glossary and ADR discipline this skill drives.
- Implement spec skill: the build step further down the same chain, once the spec is split into tickets.
- Improve codebase architecture skill: the docs say users pair it with grill-with-docs to build or repair a
GLOSSARY.md.