What Is the grill-with-docs Skill for Claude Code?

Claude Code will happily implement a plan that quietly contradicts decisions your team wrote down months ago. The grill-with-docs skill closes that gap: it interrogates your plan against the repo's own documentation before any production code gets written, and it is the stateful sibling of the grill-me skill.

Key takeaways

• grill-with-docs has 823,985 installs on the skills.sh registry, second among the grilling skills behind grill-me's 966,885 installs and still adding 143 installs in the last recorded day (skills.sh registry).
• It ships in the mattpocock/skills repository, which holds 235,544 GitHub stars and was last pushed on 2026-08-24 (GitHub).
• Unlike a plain grilling, it leaves a paper trail: resolved terminology is written into CONTEXT.md and hard-to-reverse decisions become ADRs, driven through the repo's /domain-modeling skill.
• The repo recommends it as the first step of its idea-to-ship flow whenever a codebase already exists; /grill-me covers the greenfield case.
• Skillselion classifies it under Productivity & Planning at the validate stage; you can compare it with the other top skills for the validate stage across the catalog's 59,746 skills (skills.sh registry).

What is the grill-with-docs skill?

grill-with-docs runs a relentless interview, called a /grilling session, that pressure-tests a plan or design against your live codebase and its living documentation before you write production code. It is one of the most-installed skills in the entire catalog at 823,985 installs (skills.sh registry), and it sits in mattpocock/skills, the 235,544-star repository that also contains tdd, handoff, and grill-me (GitHub). The grill-with-docs listing carries the full SKILL.md and file tree.

How is grill-with-docs different from grill-me?

The difference is state. grill-me, covered in our grill-me skill guide, is stateless: it grills your idea and the sharpened thinking lives only in the conversation. grill-with-docs retains what it learns. During the session it drives the /domain-modeling skill, so terminology you resolve is recorded in CONTEXT.md and decisions that would be expensive to reverse are captured as Architecture Decision Records. grill-me has more installs overall, 966,885 to 823,985 (skills.sh registry), because it works in any conversation, but when a repository exists, the repo's own docs recommend starting with grill-with-docs.

How do you install grill-with-docs?

One command installs the whole collection, grill-with-docs included:

npx skills@latest add mattpocock/skills

Then invoke it in Claude Code with /grill-with-docs and describe the feature or refactor you are planning. The skill takes over the interview from there.

What happens during a grilling session with docs?

The skill asks pointed questions one at a time and refuses to accept vague answers. Because this variant reads your documentation, its questions cite the language your project already uses: if your CONTEXT.md defines a term one way and your plan uses it another way, the session forces you to reconcile the two. When a question surfaces a decision with real switching costs, the skill records it as an ADR instead of letting it evaporate. The result is a sharper plan plus updated docs, which is why the repo positions it before spec and ticket writing in its idea-to-ship flow.

When should developers reach for grill-with-docs?

Reach for it when a codebase exists and the plan touches architecture. It is classified at the validate stage in Skillselion's Docs & Planning category, and that placement matches its job: stress-testing direction before implementation. For a brand-new idea with no repo, use /grill-me instead. For a full tour of the ecosystem these skills come from, see the Matt Pocock skills map.

A complete starter stack

• grill-with-docs: interrogate the plan against your repo's documented decisions first.
• domain-modeling: invoked automatically during the session; keeps CONTEXT.md and ADRs current.
• tdd skill: implement the sharpened plan red-green-refactor, with 767,086 installs of its own (skills.sh registry).
• grill-me: keep it installed for greenfield ideas that have no codebase yet.

Common pitfalls

• Running it in a repo with no CONTEXT.md or ADR directory and expecting deep doc-aware questions; seed minimal docs first or the session degrades toward a stateless grilling.
• Treating the interview as a formality and giving one-line answers; the skill's value scales with how honestly you engage, as Anthropic's own skills documentation notes that skills are instructions, not magic.
• Grilling a trivial change; a 20-question interview about a copy tweak wastes tokens, so save it for decisions with switching costs.

If your plans keep drifting from your docs, an 823,985-install interviewer that reads those docs before you code is the cheapest correction available.

Common questions