UserPromptExpansion runs when a slash command (including a skill) expands into its full prompt. It's your hook point between "user typed /foo" and "Claude starts reasoning".

What it does

The hook sees the expanded prompt from a slash command. It can modify the expansion, block the command, or attach context only relevant to that command. This is how you enforce per-skill rules - maybe your /deploy skill should always refuse on Fridays, or your /merge skill should always require a PR number.

When to use it

Enforcing constraints on specific skills (never run destructive skills in main branch).
Attaching dynamic context to certain commands (pull current config, add today's date).
Auditing slash command usage across a team.
Building guardrails around team-shared skills.

Gotchas

The hook fires for every matching expansion, including auto-invocations. Scope triggers carefully.
Blocking without explanation frustrates users. Always return a reason.
Expansion-time hooks don't see the user's raw intent, only the resolved skill body.

Official docs: https://code.claude.com/docs/en/hooks.md#userpromptexpansion