Deep Dive: Why mattpocock/skills Makes Your Agent Interview You First

Companion to the hands-on tutorial: Align with your coding agent using a grilling session on Cui.Guru. The tutorial shows how to run it. This post explains why it is built this way.

mattpocock/skills (318k stars when I read it) is a collection of small, composable agent skills. Its README names the first failure mode it targets: misalignment. You think the agent knows what you want, then you see what it built. The fix is a grilling session.

The workflow in motion

Architecture: tiny wrappers, one engine

The two best-known entry points contain almost no logic. This is the whole of grill-me:

---
name: grill-me
description: A relentless interview to sharpen a plan or design.
disable-model-invocation: true
---

Call the Skill tool with "grilling".

and grill-with-docs is the same idea with two calls:

Call the Skill tool twice, for "grilling" and "domain-modeling".

Both wrappers set disable-model-invocation: true, which in Claude Code keeps the model from triggering them on its own. Grilling is something you ask for. The behaviour lives once, in grilling, so changing it changes every entry point.

The core design idea: a design tree worked in rounds

The grilling skill defines the method precisely:

• Map the plan as a design tree: every decision branches into the decisions that hang off it.
• The frontier is every decision whose prerequisites are already settled, meaning the questions you can ask now without guessing answers you haven’t heard.
• Ask the whole frontier in one round, numbered, each with a recommended answer. Word each question so “yes” accepts the recommendation.
• After your answers, recompute the frontier and ask the next round. A question that depends on another open question in the same round belongs to a later round.
• The session is done when the frontier is empty and you confirm a shared understanding. Nothing is acted on before that.

The format of a round is spelled out in the skill:

❓ **Q1** - **<question title>**: <question body>

➡️ <your recommended answer>

Why the details matter

Facts are the agent’s job, decisions are yours. The skill says finding facts is never the user’s job. When a question needs something from the environment, it dispatches a sub-agent with a fresh context window and keeps asking the unaffected questions meanwhile. You only spend attention on decisions.

Batching by frontier cuts round trips. Asking one question at a time wastes turns on independent decisions. Asking everything at once forces guesses. The frontier is the largest set that needs no guessing.

Recommended answers lower the cost of agreeing. Every question carries a default you can accept with one word.

The companion: domain modeling

domain-modeling extends grilling with a shared vocabulary. It challenges terms that conflict with GLOSSARY.md, sharpens vague words, tests relationships with concrete scenarios, and cross-checks claims against the code. Its glossary rules are strict: define what a term is, keep it to one or two sentences, list names to avoid, and keep implementation details out. ADRs are offered only when a decision is hard to reverse, surprising without context, and the result of a real trade-off. If any of the three is missing, it skips the ADR.

Takeaways for your own agent workflows

• Put the behaviour in one skill and make entry points thin wrappers.
• Treat alignment as a tree walk, not a form to fill in.
• Let the agent find facts and keep decisions with the human.
• Attach a recommended answer to every question.
• Write the vocabulary down as you go, and keep it free of implementation detail.

Want a guided, conversational flow like this inside your product? Talk to Cui.Guru.