Agent skill · Skills for Real Engineers
/grill-with-docs Plan interviews that build a project glossary
The grill-with-docs skill runs a structured interview about a plan or design and, during the same session, records agreed terms in GLOSSARY.md and significant decisions as ADRs. It combines the pack's grilling and domain-modeling skills, so you leave with both a settled plan and shared vocabulary the agent reuses later.
Works with
- Claude Code
- Codex
- GitHub Copilot
- Gemini CLI
- Cursor, OpenCode, Windsurf, Amp and others
Used forPlanning and specs
When to use it
- Before starting any non-trivial change, to make sure the agent understands what you want.
- When a project's jargon is fuzzy and the agent keeps describing things at length.
- When a design choice is hard to reverse and future readers will need to know why it was made.
How it works
- 1Map the decisions
The agent treats the plan as a tree of decisions and finds the ones whose prerequisites are already settled.
- 2Ask in rounds
It asks that whole set of numbered questions at once, each with a recommended answer, then waits for yours.
- 3Look up facts itself
Questions that depend on facts in the codebase are answered by a sub-agent instead of being put to you.
- 4Sharpen terms
It challenges vague or conflicting words, tests them with edge-case scenarios and writes resolved terms to GLOSSARY.md.
- 5Record key decisions
It offers an ADR only for decisions that are hard to reverse, surprising and the result of a real trade-off.
What it steers the agent away from
- Starting to code before the plan is actually agreed
- Glossaries cluttered with implementation notes
- ADRs written for decisions that did not need one
Install this skill
It installs with the Skills for Real Engineers pack.
Claude CodeInstalled as a plugin that updates itself by default.
claude plugin install mattpocock-skills@claude-plugins-officialCodexUpdates at startup.
codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocockGitHub CopilotWorks in the CLI and VS Code; the README also shows a one-time settings.json entry to enable auto-update.
copilot plugin marketplace add mattpocock/skills
copilot plugin install mattpocock-skills@mattpocockGemini CLIRe-run both commands to update.
gemini skills install https://github.com/mattpocock/skills.git --path skills/engineering
gemini skills install https://github.com/mattpocock/skills.git --path skills/productivityCursor, OpenCode, Windsurf, Amp and othersCopies editable files into your project; update with npx skills@latest update. Use either this or a plugin per agent, not both.
npx skills@latest add mattpocock/skills -a <agent>Commands come from the author’s README; check it for changes before you run them.
Questions
How is grill-with-docs different from grill-me?
grill-me only runs the interview and suits non-code topics. grill-with-docs adds domain modeling, so it also maintains a glossary and ADRs in your repo.
Does the agent start implementing after the interview?
No. The session ends when every decision is resolved, and the agent waits for you to confirm shared understanding before acting.
More guides from Skills for Real Engineers
/diagnosing-bugsA gated debugging loop for hard bugsWorks through hard bugs and slowdowns in gated steps, starting from a reproducible failure.Read the guide →/tddTest-driven development for coding agentsBuilds features or fixes bugs test-first, one failing test and one fix at a time.Read the guide →
Also in this pack
/ask-mattSuggests which skill or workflow in the pack fits your current situation.↗/code-reviewReviews changes since a commit or branch against repo standards and the original spec.↗/codebase-designProvides shared terms for designing deep modules with small, testable interfaces.↗/implement-specImplements a whole spec on one branch, running subagents across ready tickets.↗/implementBuilds a piece of work from a spec or tickets, test-first, then reviews it.↗/prWrites a pull request body with a summary, evidence it works and merge risk.↗/prototypeBuilds a throwaway prototype to answer one design or UI question quickly.↗/researchAnswers a question from primary sources and saves cited findings as Markdown in the repo.↗/retroReviews a finished coding session and suggests improvements to the agent's environment.↗/setup-matt-pocock-skillsConfigures a repo once with its issue tracker, triage labels and doc locations.↗/to-ticketsSplits a plan or spec into small tickets that state what blocks what.↗/triageMoves issues and outside PRs through triage states and writes agent-ready briefs.↗
Summary by trendhub. The skill itself lives in mattpocock/skills/skills/engineering/grill-with-docs by Matt Pocock (MIT); read the full, current text there.