Creating Copilot Hooks
Use this skill when the right answer is not more advice, but deterministic behavior at a specific lifecycle point. It helps design hooks that are safe, documented, and understandable.
When to Use
Use this skill when the user asks for things like:
- "create a Copilot hook for this policy"
- "block dangerous commands before they run"
- "log or validate tool usage automatically"
- "add a reusable hook pack with docs and scripts"
- "turn this manual guardrail into a hook"
Typical scenarios:
- pre-tool checks for risky shell commands
- post-tool validation or formatting triggers
- audit or observability hooks for shared environments
- installing a documented hook bundle for reuse across workspaces
Outcome Standard
A strong hook contribution usually includes:
- the right lifecycle event and the smallest useful behavior
- explicit safety defaults and clear denial or warning messages
- a documented
hooks.jsonconfiguration - cross-platform script guidance when Windows and Bash users both matter
- a README or pack that explains purpose, setup, and limitations
Hook Design Rules
- Start with observe or warn - block only when the policy is stable and the failure message is clear.
- Keep hooks fast - long-running hooks become friction generators instead of safeguards.
- Be explicit on denial - if a hook blocks work, explain exactly why and what to do instead.
- Separate policy from docs - the script enforces behavior; the README explains it.
- Prefer deterministic checks - hooks should not depend on fuzzy interpretation when avoidable.
Workflow
Phase 0: Decide whether a hook is the right primitive
Use a hook when deterministic automation is needed at a lifecycle event. If the need is guidance only, use instructions. If the need is a reusable workflow, use a skill. If the need is a user-started task, use a prompt.
Phase 1: Choose the lifecycle event
Clarify or infer:
- what event should trigger the hook
- whether the behavior is observe, warn, mutate, or deny
- how quickly the hook must complete
- whether it needs cross-platform script support
Phase 2: Design the safety model
Before scripting:
- define the exact condition being checked
- decide what the hook should output on allow, warn, or deny
- write the denial or warning message in user language, not policy jargon
- make sure the hook fails safely when inputs are missing or malformed
Phase 3: Create the hook pack
Use the resources below as the default starting point:
./resources/hook-template-pack.md./resources/hook-example-pack.md
A complete pack should usually include:
hooks.json- one or more supporting scripts
- a README with purpose, setup, and behavior notes
Phase 4: Validate the operational fit
Check the result against ./resources/hook-quality-checklist.md.
Pay special attention to:
- whether the hook is fast enough for the event it runs on
- whether the messages are actionable
- whether Windows and non-Windows paths are addressed when required
- whether the hook blocks only what it truly means to block
Common Failure Modes
- using a hook when a normal instruction would have been enough
- blocking large classes of commands without a helpful reason
- writing scripts that are too slow for frequent lifecycle events
- shipping
hooks.jsonwithout installation or behavior documentation - creating platform-specific hooks with no fallback or adaptation guidance
Resource Map
./resources/hook-template-pack.md- template pack with README, config, and script scaffolds./resources/hook-example-pack.md- worked example of a safe, documented policy hook./resources/hook-quality-checklist.md- final review checklist before shipping
Definition of Done
A task using this skill is complete when:
- the hook behavior matches a clear lifecycle need
- the configuration, scripts, and documentation agree with each other
- failure, allow, and deny messages are understandable
- the pack is install-ready or clearly adapted for the target environment
- the final result passes the quality checklist without obvious operational risk