# 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.

## Quick Install

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

Then start a fresh Claude Code session. `/hooks` should list the two hooks.

**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)

### Download and Inspect Instead

```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, for example:

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

Avoid installing the Claude plugin alongside those files, which can expose
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.