# AskUserQuestion for Matt Pocock's Grilling Skills

Makes [Matt Pocock's grilling skills](https://github.com/mattpocock/skills)
ask their questions with Claude Code's `AskUserQuestion` tool instead of plain
text rounds. It is an add-on: the upstream skill files are never touched.

## Step by Step

### 1. Install Matt Pocock's skills (once)

Skip this if you already have them.

```bash
npx --yes skills@latest add mattpocock/skills --global --agent claude-code --skill '*' --yes
```

### 2. Install this add-on

```bash
bash -o pipefail -c 'curl -fsSL https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/raw/HEAD/install-question-tools.sh | bash'
```

It prints each file it wrote (`Updated:`) and any backup it made (`Backup:`).
If it prints `Installation failed`, nothing was changed; fix the reason it
gives and run it again.

### 3. Start a fresh Claude Code session

Hooks and `CLAUDE.md` are read when a session starts, so close any open
session and start a new one. Type `/hooks` and check you see:

- `PostToolUse` with matcher `Skill`
- `UserPromptSubmit`

Both run `grilling-question-hook.py`.

### 4. Start a grilling session

Use any of these, the same way you would without the add-on:

| You type | What it does |
| --- | --- |
| `/grill-me <your plan>` | Interview to sharpen a plan or design. |
| `/grill-with-docs <your plan>` | Same, and writes ADRs and a glossary as you go. |
| `/grilling <your plan>` | The core interview directly. |
| `/loop-me` | Grill workflow specs for recurring tasks. |
| "grill me on this" | Claude picks up the grilling skill by itself. |

Skills that grill as part of their work (`wayfinder`, `triage`,
`improve-codebase-architecture`) get the same behavior automatically.

### 5. Answer the question cards

Instead of a wall of numbered text, each round arrives as `AskUserQuestion`
cards:

- Up to 4 questions per card. A bigger round comes as several cards in a row.
- The first option is Claude's pick, marked **(Recommended)**, with the reason
  in its description.
- Pick an option, or choose **Other** to type your own answer.
- If you skip or dismiss a question, it stays open. Claude will not treat it as
  a yes.

After each round Claude works out the next questions from your answers. The
session ends when nothing is left open, and Claude asks you to confirm the
shared understanding before acting on it.

### 6. If you still get plain text questions

That is the expected fallback when `AskUserQuestion` cannot be used, for
example in non-interactive `claude -p` runs, or for a question that is truly
open ended. If it happens in a normal session:

1. Run `/hooks`. If the two hooks are missing, rerun step 2 and start a new session.
2. Check `python3 --version` works in the shell Claude Code uses.
3. Ask Claude "Did the grilling question policy load?" to see what it received.

### Update or remove

- Update: run the step 2 command again. Nothing changes if you are already current.
- Remove: see [Uninstall](#uninstall).

## Inspect Before Installing

**Trust check:** this runs remote code and downloads a policy and a hook
script from this gist. Read them first if you do not already trust the
publisher and server. `pipefail` reports download failures; it is not a
security sandbox.

Files: [installer](https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/raw/HEAD/install-question-tools.sh)
| [policy](https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/raw/HEAD/grilling-question-tools.md)
| [hook](https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/raw/HEAD/grilling-question-hook.py)

To read everything first and then install from the same gist:

```bash
base=https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056
for f in install-question-tools.sh grilling-question-tools.md grilling-question-hook.py; do
  curl -fsSL "$base/raw/HEAD/$f" -o "$f"
done
less install-question-tools.sh grilling-question-tools.md grilling-question-hook.py
bash install-question-tools.sh
```

The installer downloads the policy and hook at `HEAD`, not your inspected
copies. To pin them, take a full commit hash from the gist's
[Revisions](https://opengist.resetrix.work/weehong/9e381dc89dff4670b7232b910454f056/revisions)
and run `QUESTION_TOOLS_REVISION=<40-character-hash> bash install-question-tools.sh`.

## How It Works

Four pieces, all under your Claude config directory (`~/.claude`, or
`$CLAUDE_CONFIG_DIR` when set):

| File | Purpose |
| --- | --- |
| `grilling-question-tools/grilling-question-tools.md` | The policy: how to turn a grilling round into `AskUserQuestion` calls. |
| `grilling-question-tools/grilling-question-hook.py` | Hands the policy to Claude the moment a grilling flow starts. |
| `settings.json` | Registers the hook for two events (below). |
| `CLAUDE.md` | A short marked pointer to the policy, as a fallback. |

The hook fires on:

| Event | When |
| --- | --- |
| `PostToolUse`, matcher `Skill` | Claude loads `grilling`, `grill-me`, `grill-with-docs`, or `loop-me`. This covers `/grill-me`, `/grill-with-docs`, plugin names such as `mattpocock-skills:grilling`, and skills that call grilling (`wayfinder`, `triage`, `improve-codebase-architecture`). |
| `UserPromptSubmit` | You type `/grilling` or `/loop-me` yourself, which skips the Skill tool. |

Why a hook: the upstream `grilling` skill ships its own text format for each
round, and it arrives later in the conversation than `CLAUDE.md`, so a
`CLAUDE.md` note alone often loses. The hook adds the policy right after the
skill loads. It only adds context: it never blocks or edits anything, and any
error exits 0 silently so it cannot break a session. It reads the policy file
each time, so policy updates need no settings change.

The policy keeps the grilling flow intact: same rounds (split into calls of
up to 4 questions), a recommended option first marked `(Recommended)`, the
built-in Other answer for custom replies, skipped answers treated as
unresolved, and the upstream text format as the fallback when
`AskUserQuestion` is unavailable. It is guidance, not enforcement; Claude Code
permissions and higher priority instructions still apply.

## Requirements

- Linux, macOS, or WSL; Bash 3.2+, Python 3.8+, `curl`. `python3` must also
  be on the `PATH` Claude Code uses to run hooks.
- Run as your normal user, without `sudo`.
- Matt Pocock's skills installed separately (step 1). Use either the `npx`
  install or the Claude plugin, not both, or you may see duplicate skills.

## Updates and Safety

Rerun the quick command to update. Identical reruns change nothing and make no
backups.

- Download errors or an invalid policy or hook abort before any file is
  changed. The checks (versioned markers, title, seven rules, hook header, and
  that the hook compiles) are sanity checks, not a signature.
- Everything is checked before anything is written. Malformed or duplicate
  `CLAUDE.md` markers, a `settings.json` that is not a JSON object, or an
  unexpected `hooks` layout abort the run.
- `CLAUDE.md` bytes outside the managed block are kept exactly. The markers are
  `<!-- BEGIN MATT-POCOCK-GRILLING-QUESTION-TOOLS -->` and
  `<!-- END MATT-POCOCK-GRILLING-QUESTION-TOOLS -->`; keep them intact.
- In `settings.json`, only hook entries whose command runs
  `grilling-question-hook.py` are managed. Other settings and hooks are kept in
  order, but the file is rewritten as 2 space indented JSON when it changes.
- Every changed file gets a sibling backup named
  `<filename>.question-tools-backup-<suffix>` (mode `0600`). Old backups are
  never replaced.
- Symlinked files and directories (for example a dotfiles repo) are followed
  and kept as symlinks. Dangling symlinks and non-regular files are rejected.
- Each file is replaced atomically, but not all files as one transaction. If a
  write fails midway, restore from the printed backups and rerun.

Upgrading from the earlier multi-agent version moves the hook entry and the
`CLAUDE.md` pointer to the new paths automatically. It leaves the old files in
`~/.config/ai-agents/` and the pointer blocks in `~/.codex/AGENTS.md` and
`~/.config/opencode/AGENTS.md`; remove those by hand if you no longer want them.

## Uninstall

1. `QUESTION_TOOLS_CLAUDE_HOOK=0 bash install-question-tools.sh` removes the
   managed hook entries from `settings.json`.
2. Delete the marked block from `CLAUDE.md`.
3. Delete the `grilling-question-tools` folder in your Claude config directory.

## Tests

```bash
python3 -B -m unittest -v test_install_question_tools
```

They use temporary homes and a mocked `curl`: no network, no real install. The
permission test is skipped when running as root.