UserPromptExpansion Hook - Claude Code

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