From forge-core
Create and validate module hooks. USE WHEN create hook, new hook, write hook, scaffold hook, validate hook, check hook, hook conventions, hook events, hook structure.
npx claudepluginhub n4m3z/forge-coreThis skill uses the workspace's default tool permissions.
Create and validate hook scripts for forge modules. Hooks are bash scripts triggered by Claude Code events, routed through the `dispatch` binary.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Processes PDFs: extracts text/tables/images, merges/splits/rotates pages, adds watermarks, creates/fills forms, encrypts/decrypts, OCRs scans. Activates on PDF mentions or output requests.
Share bugs, ideas, or general feedback.
Create and validate hook scripts for forge modules. Hooks are bash scripts triggered by Claude Code events, routed through the dispatch binary.
| Workflow | Trigger | Section |
|---|---|---|
| Create | "create hook", "new hook", "scaffold hook" | Create Workflow |
| Validate | "validate hook", "check hook" | Validate Workflow |
Every hook handles one of 9 Claude Code events. Each event has a fixed output mode that determines how module output is handled:
| Event | Mode | Behaviour |
|---|---|---|
SessionStart | Concatenate | All module outputs combined and emitted to AI context |
PreCompact | Concatenate | All module outputs combined and emitted to AI context |
PreToolUse | Gate | Exit 2 blocks the tool call; exit 0 allows |
Stop | Gate | Exit 2 blocks session exit; exit 0 allows |
SubagentStop | Gate | Exit 2 blocks subagent exit; exit 0 allows |
PostToolUse | Passive | Output discarded; runs for side effects only |
SessionEnd | Passive | Output discarded; runs for side effects only |
UserPromptSubmit | Passive | Output discarded; runs for side effects only |
Notification | Passive | Output discarded; runs for side effects only |
Use this when choosing which event to hook:
| Goal | Event | Mode | Notes |
|---|---|---|---|
| Inject context at session start | SessionStart | Concatenate | Emit markdown to stdout |
| Block a tool call (access control) | PreToolUse | Gate | Exit 2 to block, 0 to allow |
| Enforce rules before exit | Stop | Gate | Exit 2 to block, 0 to allow |
| React to a tool result | PostToolUse | Passive | Side effects only, output discarded |
| Clean up after session | SessionEnd | Passive | Side effects only, output discarded |
| Inject context before compaction | PreCompact | Passive | Emit markdown to stdout |
Hook scripts use PascalCase matching the event name:
| Event | Filename |
|---|---|
SessionStart | hooks/SessionStart.sh |
PreToolUse | hooks/PreToolUse.sh |
PostToolUse | hooks/PostToolUse.sh |
Stop | hooks/Stop.sh |
PreCompact | hooks/PreCompact.sh |
Every hook script starts with this template. It resolves the module root from either forge-core dispatch or standalone plugin context:
#!/usr/bin/env bash
set -euo pipefail
MODULE_ROOT="${FORGE_MODULE_ROOT:-${CLAUDE_PLUGIN_ROOT:-$(command cd "$(dirname "$0")/.." && pwd)}}"
Claude Code pipes a JSON payload to hook scripts on stdin. The schema varies by event:
{"tool_name":"...", "tool_input":{...}}{"stop_reason":"...", ...}{}Read stdin once: INPUT=$(cat). Parse with yq -p json or a compiled binary.
For dispatch to find a hook:
hooks/<EventName>.sh and is executablemodule.yaml lists the event in events: (Tier 1 check)defaults.yaml under modules: (Tier 0)The 3-tier event check: config.yaml override (authoritative) > module.yaml events > hook file existence (fallback).
| Mode | Exit 0 | Exit 2 | Other |
|---|---|---|---|
| Gate | Allow | Block | Treated as allow |
| Concatenate | Success | N/A | Output included regardless |
| Passive | Success | N/A | Output discarded regardless |
Gate hooks that cannot build or run should exit 0 (graceful degradation — never block Claude on infrastructure failure).
Ask the user:
Create hooks/<EventName>.sh with:
#!/usr/bin/env bash
# <EventName> hook: <brief description>.
set -euo pipefail
MODULE_ROOT="${FORGE_MODULE_ROOT:-${CLAUDE_PLUGIN_ROOT:-$(command cd "$(dirname "$0")/.." && pwd)}}"
INPUT=$(cat)
# Gate: exit 2 to block, 0 to allow | Concatenate: emit context to stdout
For Gate hooks, add exit code logic. For Passive hooks, add the side effect. For Concatenate hooks, emit context to stdout.
Make the script executable: chmod +x hooks/<EventName>.sh
Add the event to module.yaml:
events:
- <EventName>
If the module also works as a standalone Claude Code plugin, add the event to hooks/hooks.json:
{
"hooks": {
"<EventName>": [
{"hooks": [{"type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/<EventName>.sh"}]}
]
}
}
If the hook needs configurable settings:
hooks:
HookName:
key: value
Read with yq '.hooks.HookName.key' "$MODULE_ROOT/defaults.yaml". Override via config.yaml.
Run the hook manually to test:
echo '{"tool_name":"TestTool"}' | bash hooks/<EventName>.sh
Read the hook script and module.yaml.
hooks/<EventName>.shchmod +x)#!/usr/bin/env bashset -euo pipefailcommand prefix for cd, cp, mv, rmmodule.yaml events: arraydefaults.yaml modules: arrayhooks/hooks.json references correct filenameCOMPLIANT -- all checks pass.
NON-COMPLIANT -- list failures with specific fixes. Offer to fix automatically.
SessionStart.sh, not session-start.shset -euo pipefail and command prefix for aliased commandsINPUT=$(cat)) before processing