跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
安全

creating-claude-hooks

Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure

AgentWorkforce · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add AgentWorkforce/relay --skill creating-claude-hooks

技能说明


name: creating-claude-hooks description: Use when creating or publishing Claude Code hooks - covers executable format, event types, JSON I/O, exit codes, security requirements, and PRPM package structure skillType: skill allowed-tools: Read, Write, Edit, Grep, Glob, Bash

Creating Claude Code Hooks

Use this skill when creating, improving, or publishing Claude Code hooks. Provides essential guidance on hook format, event handling, I/O conventions, and package structure.

When to Use This Skill

Activate this skill when:

  • User asks to create a new Claude Code hook
  • User wants to publish a hook as a PRPM package
  • User needs to understand hook format or events
  • User is troubleshooting hook execution
  • User asks about hook vs skill vs command differences

Quick Reference

Hook File Format

AspectRequirement
Location.claude/hooks/<event-name>
FormatExecutable file (shell, TypeScript, Python, etc.)
PermissionsMust be executable (chmod +x)
ShebangRequired (#!/bin/bash or #!/usr/bin/env node)
InputJSON via stdin
OutputText via stdout (shown to user)
Exit Codes0 = success, 2 = block, other = error

Available Events

EventWhen It FiresCommon Use Cases
session-startNew session beginsEnvironment setup, logging, checks
user-prompt-submitBefore user input processesValidation, enhancement, filtering
tool-callBefore tool executionPermission checks, logging, modification
assistant-responseAfter assistant respondsFormatting, logging, cleanup

Hook Format Requirements

File Location

Project hooks:

.claude/hooks/session-start
.claude/hooks/user-prompt-submit

User-global hooks:

~/.claude/hooks/session-start
~/.claude/hooks/tool-call

Executable Requirements

Every hook MUST:

  1. Have a shebang line:
#!/bin/bash
# or
#!/usr/bin/env node
# or
#!/usr/bin/env python3
  1. Be executable:
chmod +x .claude/hooks/session-start
  1. Handle JSON input from stdin:
#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.input.file_path // empty')
  1. Exit with appropriate code:
exit 0  # Success
exit 2  # Block operation
exit 1  # Error (logs but continues)

Input/Output Format

JSON Input Structure

Hooks receive JSON via stdin with event-specific data:

{
  "event": "tool-call",
  "timestamp": "2025-01-15T10:30:00Z",
  "session_id": "abc123",
  "current_dir": "/path/to/project",
  "input": {
    "file_path": "/path/to/file.ts",
    "command": "npm test",
    "old_string": "...",
    "new_string": "..."
  }
}

Stdout Output

  • Normal output shows in transcript
  • Empty output runs silently
  • Use stderr (>&2) for errors

Exit Codes

CodeMeaningBehavior
0SuccessContinue normally
2BlockStop operation, show error
1 or otherErrorLog error, continue

Schema Validation

Hooks should validate against the JSON schema:

Schema URL: https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-hook.schema.json

Required frontmatter fields:

  • name - Hook identifier (lowercase, hyphens only)
  • description - What the hook does
  • event - Event type (optional, inferred from filename)
  • language - bash, typescript, javascript, python, binary (optional)
  • hookType: "hook" - For round-trip conversion

Common Mistakes

MistakeProblemSolution
Not quoting variablesBreaks on spacesAlways use "$VAR"
Missing shebangWon't executeAdd #!/bin/bash
Not executablePermission deniedRun chmod +x hook-file
Logging to stdoutClutters transcriptUse stderr: echo "log" >&2
Wrong exit codeDoesn't block when neededUse exit 2 to block
No input validationSecurity riskAlways validate JSON fields
Slow operationsBlocks ClaudeRun in background or use PostToolUse
Absolute paths missingCan't find scriptsUse $CLAUDE_PLUGIN_ROOT

Basic Hook Examples

Shell Script Hook

#!/bin/bash
# .claude/hooks/session-start

# Log session start
echo "Session started at $(date)" >> ~/.claude/session.log

# Check environment
if ! command -v node &> /dev/null; then
  echo "Warning: Node.js not installed" >&2
fi

# Output to user
echo "Development environment ready"
exit 0

TypeScript Hook

#!/usr/bin/env node
// .claude/hooks/user-prompt-submit

import { readFileSync } from 'fs';

// Read JSON from stdin
const input = readFileSync(0, 'utf-8');
const data = JSON.parse(input);

// Validate prompt
if (data.prompt.includes('API_KEY')) {
  console.error('Warning: Prompt may contain secrets');
  process.exit(2); // Block
}

console.log('Prompt validated');
process.exit(0);

Best Practices

1. Keep Hooks Fast

Target < 100ms for PreToolUse hooks:

  • Cache results where possible
  • Run heavy operations in background
  • Use specific matchers, not wildcards
阅读完整来源 ↗