June 17, 2026·4 min read

Building Common Ground With Your AI: grill-with-docs

TL;DR

grill-with-docs interviews the developer like grill-me does, but writes the results to CONTEXT.md and docs/adr/ instead of just using them for one session.
CONTEXT.md becomes a shared glossary so the AI's understanding of a term matches the developer's, not a generic training-data definition.
Architecture Decision Records capture why a choice was made, so a new Claude session can read the reasoning instead of getting it re-explained from scratch.
It barely matters in an empty project. The value shows up in a codebase that already has history worth preserving.

Two people on the same team can share one goal and still describe it differently enough to stall a project for a week before anyone notices the mismatch. That happens constantly on human teams, and most people who’ve lived through it still assume an AI coding agent somehow doesn’t have the same problem, that it just understands what they meant.

It doesn’t, by default. grill-with-docs, Matt Pocock’s follow-up to his grill-me skill, exists to build that common ground on purpose, for codebases that already exist.

What is grill-with-docs?

grill-with-docs is a Claude Code skill built for an existing codebase, not a blank project. Where grill-me is for the planning stage before any code exists, grill-with-docs is for a project already in progress, where the goal is aligning on terminology and decisions rather than starting from zero.

Running /grill-with-docs first checks whether the project already has a CONTEXT.md and a docs/ folder. If neither exists, it runs an interview similar to grill-me, but the output gets written to disk instead of just informing that one session.

How is it different from just writing everything in CLAUDE.md?

A CLAUDE.md file works fine for static, repeated instructions. What it doesn’t do well is capture a specific decision made mid-project, the kind of thing that comes up once, gets debated, and then needs to be remembered for months. grill-with-docs targets exactly that gap: detailed, per-feature plans and the terminology both sides agreed on, not a static rulebook.

The glossary lives in CONTEXT.md. When a term the developer uses doesn’t match what the AI would otherwise assume, it gets written down there once, so the next session starts from agreement instead of re-deriving it.

What does it actually generate?

Two artifacts, and they serve different jobs. CONTEXT.md holds the shared vocabulary: what a “Post” means in this specific codebase, what an “Order” is allowed to do, terms that would otherwise drift between how the developer thinks about them and how the AI would guess. It’s the same mechanism that produced this site’s own CONTEXT.md, the glossary this very post’s writing rules are pulled from.

The second artifact is an Architecture Decision Record, written to docs/adr/, generated when a specific technical choice gets made through the interview and both sides land on the same answer. It records the reasoning, not just the outcome. Open a new Claude session weeks later, run /grill-with-docs again, and the AI reads both files instead of asking to be walked through the project’s history from scratch.

How do you install and run it?

Installing it requires Node.js, same as grill-me. Run npx skills@latest add mattpocock/skills, and select grill-with-docs from the list of skills it offers. From inside the project directory, /grill-with-docs starts the process.

When does it actually pay off?

Running it in an empty directory won’t cause any harm, but there’s nothing for it to build on yet, so most of its value goes unused. The gap it closes only exists once a codebase has accumulated decisions, terminology, and history worth not repeating.

That makes it the wrong tool for day one and the right one for week three, once a project has enough of a past that re-explaining it every session has actually become the bottleneck.