What is writing-hooks?

This Claude skill provides a standardized framework for developing event-driven hooks that intercept prompts, manage permissions, and automate workflows. It empowers developers to build more responsive and secure AI agents by injecting custom logic into the agent's execution lifecycle, complete with robust timeout management and error-handling mechanisms to ensure system stability.

When should I use writing-hooks?

writing-hooks is useful in the following scenarios: • Automated Prompt Enhancement: Intercept user inputs to automatically inject relevant context or suggest specific skills, significantly improving the accuracy of agent responses. • Security & Permission Guardrails: Implement hooks that evaluate tool requests in real-time to auto-approve safe actions (like reading files) while flagging or blocking high-risk operations. • Event-Triggered Workflow Automation: Create seamless background processes that trigger automatically when specific events occur, reducing the need for manual user intervention. • Resilient System Integration: Define hooks with explicit timeouts and bypass conditions to ensure the agent remains responsive and functional even if external scripts or services fail.

name	writing-hooks
description	"Use when creating hooks for prompt interception, permission handling, or event-triggered automation with timeout and bypass handling."

Writing Hooks

Overview

Hooks intercept events (prompts, permissions, tool calls) to inject behavior. Good hooks are fast, have graceful failures, and define bypass conditions.

When to Create

Create a hook when:

Behavior should apply to ALL relevant events
Pre-processing or validation is needed
Automation can replace manual steps
Skill activation should be automatic

Don't create for:

Occasional interventions (use rules)
Complex logic (use commands or skills)
User-initiated workflows (use commands)

Structure Template

---
name: hook-name
type: [UserPromptSubmit | PermissionRequest | ToolExecution]
timeout_ms: [number]
---

# Hook Name

## Purpose
[What this hook accomplishes]

## Trigger Event
[Exact event type and conditions]

## Input Format
[JSON structure received]

## Processing Logic
[What the hook does]

## Output Format
[JSON structure returned or modification made]

## Timeout Handling
[What happens if hook exceeds timeout]

## Bypass Conditions
[When hook should be skipped]

## Error Handling
[Graceful failure behavior]

Quality Checklist

Hook type correctly identified
Timeout is reasonable (< 5000ms for prompt hooks)
Input/output JSON formats defined
Bypass conditions explicit
Error handling prevents blocking
Graceful degradation (fails open, not closed)
No side effects on main context
Cross-platform if using scripts

Testing Requirements

Trigger test - Hook fires on correct events
Timeout test - Behavior when timeout exceeded
Bypass test - Skipped when conditions met
Error test - Graceful failure on exceptions
Performance test - Stays within timeout
Platform test - Works on Windows/Mac/Linux

Examples

Good Hook (Skill Activation):

---
name: skill-activation
type: UserPromptSubmit
timeout_ms: 3000
---

## Purpose
Analyze prompts and recommend relevant skills.

## Trigger Event
Every UserPromptSubmit event.

## Input Format
{
  "session_id": "string",
  "prompt": "string"
}

## Processing Logic
1. Parse prompt for keywords
2. Match against skill-rules.json
3. Append skill recommendations to prompt

## Output Format
{
  "prompt": "original + skill recommendations"
}

## Timeout Handling
Return original prompt unchanged.

## Bypass Conditions
- Prompt starts with /command
- Prompt is < 5 characters

## Error Handling
Log error, return original prompt.

Good Hook (Permission):

---
name: safe-permissions
type: PermissionRequest
timeout_ms: 5000
---

## Purpose
Auto-approve safe operations, block dangerous ones.

## Processing Logic
Tier 1 (fast approve): Read, Write, Glob, Grep
Tier 2 (fast deny): rm -rf /, force push main
Tier 3 (analyze): Everything else via LLM

## Bypass Conditions
- User in --dangerous mode

Bad Hook:

---
name: helper-hook
---

Does helpful things when stuff happens.

(No type, no timeout, no error handling)

Common Mistakes

Mistake	Fix
No timeout defined	Add reasonable timeout_ms
Fails closed	Fail open (return unchanged input)
No bypass conditions	Define when to skip
Platform-specific	Use cross-platform scripts
Side effects	Hooks should be pure/stateless
Too slow	Optimize or move logic elsewhere

writing-hooks

When & Why to Use This Skill

Use Cases