askit-build-hook
Purpose
Author a plugin's hooks: event-driven enforcement or context injection (Standard sec 3.5). Hooks are an Advanced-tier capability. Two modes: create scaffolds a hook and its registration; improve raises an existing hook toward the bar (documentation, idempotency, actionable block messages). The hook SKILL is portable; what it authors is primarily a Claude capability (31 events) with a smaller Codex event set. Authoring depth is in references/authoring-hooks.md. Follows the shared builder contract (../../docs/reference/builder-pattern.md).
When to use
When the user asks to add, scaffold, author, or improve a hook (a PreToolUse / PostToolUse / Stop / SessionStart guard, a context injector, or any event-driven automation) for a plugin.
create mode
- Brief interview: the event (for example PreToolUse), the trigger or matcher, the hook type (
command / http / mcp_tool / prompt / agent), the scope (what it guards or injects), and the failure behavior (fail-safe block vs warn). Skip the interview if these are in context.
- Author the hook and its registration. A plugin registers hooks in
hooks/hooks.json using ${CLAUDE_PLUGIN_ROOT}; copy templates/hooks.json if none exists. Document the event, trigger, scope, and failure behavior (Standard sec 3.5 MUST).
- For a blocking hook (for example a PreToolUse deny), write an ACTIONABLE message that states what was blocked and how to proceed. Make the hook idempotent where the event can repeat.
- Register the hook in
library.json components.hooks as { name, version, tier, status }.
- Targets: Claude supports 31 events. Codex supports a smaller set (PreToolUse, PostToolUse, Pre/PostCompact, SessionStart, SubagentStart/Stop, UserPromptSubmit, Stop, PermissionRequest). Verify current Codex plugin-hook ingestion at build time (a known caveat) and scope
agent-targets accordingly.
- Assess with
node scripts/evaluate.mjs . --json. Hook documentation and idempotency are graded at the Advanced tier; the deterministic hook check lands with Gold self-hosting (Phase 5).
improve mode
- Run
node scripts/evaluate.mjs . --json and read the report.
- Fix what it flags. For hooks specifically, confirm the event / trigger / scope / failure are documented (sec 3.5), the block message is actionable, and the hook is idempotent.
- Re-run to confirm.
Scope
Hooks are Advanced-tier and the most agent-specific component: Claude's event set is the richest, Codex covers a subset, and the wider ecosystem does not support hooks. A hook MUST document its event, trigger, scope, and failure behavior, and a blocking hook MUST emit an actionable message (Standard sec 3.5). Least privilege applies (sec 9): a hook's command runs with the narrowest scope needed.
1---2name: askit-build-hook3description: Creates and improves event-driven hooks (Advanced tier) for a plugin to the Advanced Skill Library Standard. Use when you need to add a hook, enforce a guard on a tool or session event, inject context, or document a hook's event, scope, and failure behavior.4---56# askit-build-hook78## Purpose9Author a plugin's hooks: event-driven enforcement or context injection (Standard sec 3.5). Hooks are an Advanced-tier capability. Two modes: `create` scaffolds a hook and its registration; `improve` raises an existing hook toward the bar (documentation, idempotency, actionable block messages). The hook SKILL is portable; what it authors is primarily a Claude capability (31 events) with a smaller Codex event set. Authoring depth is in [references/authoring-hooks.md](references/authoring-hooks.md). Follows the shared builder contract ([../../docs/reference/builder-pattern.md](../../docs/reference/builder-pattern.md)).1011## When to use12When the user asks to add, scaffold, author, or improve a hook (a PreToolUse / PostToolUse / Stop / SessionStart guard, a context injector, or any event-driven automation) for a plugin.1314## create mode151. Brief interview: the event (for example PreToolUse), the trigger or matcher, the hook type (`command` / `http` / `mcp_tool` / `prompt` / `agent`), the scope (what it guards or injects), and the failure behavior (fail-safe block vs warn). Skip the interview if these are in context.162. Author the hook and its registration. A plugin registers hooks in `hooks/hooks.json` using `${CLAUDE_PLUGIN_ROOT}`; copy `templates/hooks.json` if none exists. Document the event, trigger, scope, and failure behavior (Standard sec 3.5 MUST).173. For a blocking hook (for example a PreToolUse deny), write an ACTIONABLE message that states what was blocked and how to proceed. Make the hook idempotent where the event can repeat.184. Register the hook in `library.json` `components.hooks` as `{ name, version, tier, status }`.195. Targets: Claude supports 31 events. Codex supports a smaller set (PreToolUse, PostToolUse, Pre/PostCompact, SessionStart, SubagentStart/Stop, UserPromptSubmit, Stop, PermissionRequest). Verify current Codex plugin-hook ingestion at build time (a known caveat) and scope `agent-targets` accordingly.206. Assess with `node scripts/evaluate.mjs . --json`. Hook documentation and idempotency are graded at the Advanced tier; the deterministic hook check lands with Gold self-hosting (Phase 5).2122## improve mode231. Run `node scripts/evaluate.mjs . --json` and read the report.242. Fix what it flags. For hooks specifically, confirm the event / trigger / scope / failure are documented (sec 3.5), the block message is actionable, and the hook is idempotent.253. Re-run to confirm.2627## Scope28Hooks are Advanced-tier and the most agent-specific component: Claude's event set is the richest, Codex covers a subset, and the wider ecosystem does not support hooks. A hook MUST document its event, trigger, scope, and failure behavior, and a blocking hook MUST emit an actionable message (Standard sec 3.5). Least privilege applies (sec 9): a hook's command runs with the narrowest scope needed.
product-on-purpose