grill-with-docs
by mattpocockgrill-with-docs is a planning-and-documentation skill that pressure-tests your plan against the repo’s existing domain model, sharpens terminology, and updates CONTEXT.md and ADRs as decisions crystallize. Use it for Technical Writing, product-minded engineering, and any workflow where repo-grounded language matters more than a prompt-only brainstorm.
This skill scores 67/100, which means it is listable for directory users, but it is a limited, caution-worthy install rather than a polished flagship skill. The repository gives enough evidence of a real workflow for stress-testing plans against existing docs and updating CONTEXT/ADR artifacts inline, but it lacks supporting files and install guidance that would reduce adoption guesswork further.
- Clear trigger: the description says to use it when a user wants to stress-test a plan against the project’s language and documented decisions.
- Operational workflow is explicit: it interviews one question at a time, recommends answers, and switches to codebase exploration when a question can be answered there.
- The repo includes concrete documentation formats for CONTEXT.md and ADRs, which improves agent leverage for terminology and decision recording.
- No install command and no supporting scripts/references/resources, so users must infer setup and usage from SKILL.md alone.
- It is labeled with an experimental/test signal, so users should expect a somewhat opinionated or evolving workflow rather than a fully hardened package.
Overview of grill-with-docs skill
grill-with-docs is a planning-and-documentation skill for teams that want to pressure-test a design against the language and decisions already in their repo. It is best for Technical Writing, product-minded engineering, and AI-assisted architecture work where terms must stay aligned with CONTEXT.md and ADRs instead of drifting into vague “prompt-only” wording.
The main job is simple: interview the user one question at a time, recommend answers, and use the codebase or docs when a question can be resolved from source. That makes the grill-with-docs skill more useful than a generic brainstorm prompt when the real risk is terminology mismatch, undocumented assumptions, or stale decision records.
What makes grill-with-docs different
It is built around domain awareness, not just conversation. The skill nudges you to check existing context files, scan ADRs, and update docs as decisions become clear, which is why it works well for grill-with-docs for Technical Writing and other documentation-heavy workflows.
Best-fit use cases
Use grill-with-docs when you need to:
- validate a plan against an existing domain model,
- choose precise project terminology,
- record decisions as they are made,
- or keep a draft aligned with established docs before implementation starts.
When it is not a fit
If you only want a quick summary, a polished spec, or free-form ideation without repo grounding, this skill will feel slower than a plain prompt. The value comes from disciplined questioning and doc-aware checking.
How to Use grill-with-docs skill
Install grill-with-docs
Install the grill-with-docs skill in your skills directory with the repo’s standard skill manager, then open the skill files in the target project context. The baseline install pattern is:
npx skills add mattpocock/skills --skill grill-with-docs
Treat that as the grill-with-docs install starting point, then confirm the skill is available in the agent environment you actually use.
Start with the right input
The skill works best when your first message contains:
- the goal you are planning,
- the system or feature name,
- any known terms that matter,
- and the decision boundary you want to resolve.
A weak prompt says: “Help me design this feature.”
A stronger prompt says: “Use grill-with-docs to grill this feature plan against the current billing domain. I need the right term for ‘subscription period,’ the data shape, and any ADR-worthy decisions before I write docs.”
Read these files first
For grill-with-docs usage, start with:
SKILL.mdfor the interview behavior and workflow,CONTEXT.mdorCONTEXT-MAP.mdfor the active domain model,docs/adr/for prior decisions,ADR-FORMAT.mdandCONTEXT-FORMAT.mdif you need to create or update files.
These files tell you what can be inferred from the repository and what should be written down explicitly.
Workflow that improves output
Use the skill in a loop:
- give a concrete plan or rough draft,
- let the skill ask one question at a time,
- answer with the most specific repo-grounded detail you can,
- allow codebase exploration when the question is answerable from files,
- capture terminology and hard decisions in context or ADR notes.
The key practical tip: separate “we need a name” from “we need a decision.” That keeps the grill focused and prevents unnecessary ADRs.
grill-with-docs skill FAQ
Is grill-with-docs only for documentation teams?
No. It is useful whenever a plan must match an existing domain vocabulary, especially in product engineering, platform work, or grill-with-docs for Technical Writing workflows where wording and structure affect downstream clarity.
How is this different from a normal prompt?
A normal prompt can generate ideas, but grill-with-docs is designed to interrogate assumptions, check the repository, and tighten terms against existing context. That reduces the chance of naming collisions and docs that fight the codebase.
Do I need a mature docs setup to use it?
No, but it works best when CONTEXT.md and ADRs already exist. If they do not, the skill can still help you define them lazily as decisions appear.
When should I avoid using it?
Avoid it when the task is purely exploratory, the repository has no meaningful domain context, or you need a fast one-shot answer rather than a structured interview.
How to Improve grill-with-docs skill
Feed it better decision material
The biggest quality boost comes from giving the skill a narrow, decision-shaped prompt. Include the feature name, the part of the system it touches, and the exact ambiguity you want resolved. Example: “Should we call this invoice, billing record, or charge in the accounting context, and where should that decision live?”
Give it repo evidence early
If you already know relevant files, mention them up front. Pointing the skill at CONTEXT.md, a specific ADR, or a folder like src/billing/ helps it ask fewer generic questions and more useful ones. This matters most for grill-with-docs usage because the skill is strongest when it can compare your plan to existing terms and structure.
Watch for common failure modes
The main failure mode is under-specifying the domain so the interview stays abstract. Another is asking for implementation before the language model has the right terms. If the first output feels broad, restate the decision in narrower terms and ask the skill to continue from the last resolved branch.
Iterate from the first pass
After the first round, turn the answers into one of three outputs: a cleaned glossary entry, a short ADR, or a revised implementation brief. Then rerun grill-with-docs on the remaining open questions. That second pass is where the skill usually pays off most, because terminology and boundaries are already clearer.