grill-with-docs Skill for Claude: Interview Plan, Keep Glossary and ADRs

Makes Claude interview you about a plan inside your repo, and writes the agreed terms and big decisions to files as it goes.

Installs: 1.3M; on skills.sh
Stars: 309.2K; on GitHub
Files: 1; besides SKILL.md
Updated: Nov 2026; last repo commit

grill-with-docs runs the same round-by-round interview as grill-me, but in a codebase. As terms get settled, it adds them to GLOSSARY.md. When a decision is hard to reverse and a real trade-off, it records an ADR (architecture decision record) in docs/adr/.

You start it by typing /grill-with-docs; it never starts on its own. The SKILL.md is two lines that call two other skills, grilling and domain-modeling, so install all three or it does nothing useful. It writes files in your repo, so run it somewhere you are happy to review changes.

Good for

Developers planning a change in a repo whose words are still fuzzy
Teams who want a shared glossary and decision log built during planning
Anyone adopting a codebase with no domain docs

Install grill-with-docs

Claude Code

Copy this prompt.

Install the grill-with-docs skill in Claude Code. Run this command:

claude plugin install mattpocock-skills@claude-plugins-official

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The plugin installs the whole set and updates itself. The skills CLI route must name grilling, domain-modeling too, because grill-with-docs hands work to them. Claude Code names plugin skills /plugin-name:skill-name, so after the plugin install the full name is /mattpocock-skills:grill-with-docs; the README lists /grill-with-docs, which is not confirmed for plugin installs. The README also asks you to run /setup-matt-pocock-skills once per repo.

From the project README. Source.

What's in the skill

When it loads

A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.

Key facts

Author: Matt Pocock
License: MIT
Last commit: Nov 1, 2026
Files it bundles: SKILL.md and a Codex agents/openai.yaml (no scripts)
Needs: The grilling and domain-modeling skills from the same repo
Starts: Only when you type /grill-with-docs
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass

What it includes

Starts the interview about your plan or design
The one command. It calls the grilling and domain-modeling skills.
Read · /grill-with-docs
Asks rounds of questions with suggested answers until decisions are settled
The interview itself comes from the separate grilling skill.
grilling (called)
Challenges fuzzy terms and writes the glossary and decisions down
Tells you when a word clashes with GLOSSARY.md and proposes a precise one.
Read · domain-modeling (called)
Adds each term the moment it is settled
Created at the repo root on first use. A GLOSSARY-MAP.md marks repos with several contexts.
Write · GLOSSARY.md
Records a decision that is hard to reverse, surprising and a real trade-off
Most sessions produce none, because a decision must meet all three conditions.
Write · ADR in docs/adr/

From the official docs

Questions

What does grill-with-docs do?

It interviews you about a plan or design until you and Claude share one understanding, and writes the vocabulary and hard decisions into your repo. Terms go to GLOSSARY.md and big decisions to ADR files under docs/adr/.

How do I install grill-with-docs?

Use the install box above. It installs grill-with-docs together with grilling and domain-modeling, which it calls. Installing grill-with-docs alone gives you a skill that cannot run its interview.

grill-with-docs vs grill-me?

Use grill-me when you are not working in a repo; it only asks questions and leaves nothing on disk. Use grill-with-docs when you are in a repo and want the glossary and decisions saved as files.

Does it need an API key?

No. It has no scripts and makes no network calls of its own.

Is grill-with-docs safe?

All three skills.sh audits pass. The risk is that it writes GLOSSARY.md and ADR files in your repo, so check the diff afterwards.

Will every decision become an ADR?

No. A decision only becomes an ADR if it is hard to reverse, surprising without context and a real trade-off. Everything else stays in the conversation, so hand the chat to a spec-writing step before you clear it.

Information

updated Nov 2, 2026

Repository: mattpocock/skills
Folder: skills/engineering/grill-with-docs

mattpocock/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

mattpocock/skills README · github.com
skills CLI commands · github.com
Claude Code skills · code.claude.com
grill-with-docs SKILL.md · github.com
grill-with-docs docs · github.com
grill-with-docs on skills.sh · skills.sh