[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M783JD4ADFCK71HDQV6PE9EX":3,"skill-same:01M783JD4ADFCK71HDQV6PE9EX":75},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":29,"commitSha":30,"skillDirectory":31,"forksCount":13,"repositoryHtmlUrl":32,"repositoryHomepageUrl":6,"ownerHtmlUrl":33,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":34,"install":35,"resources":48},"01M783JD4ADFCK71HDQV6PE9EX","claude-hook-writer",null,"Expert guidance for writing secure, reliable, and performant Claude Code hooks - validates design decisions, enforces best practices, and prevents common pitfalls. Use when creating, reviewing, or debugging Claude Code hooks.","aibizmod\u002Faibizmod-service-web","aibizmod","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F295315630?v=4","01M7836CB8EQY701YQ7N88M591","01M7836CBVPZGNSJ8BRP2BT398",0,"MIT","https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fclaude-hook-writer\u002Fskills\u002Fclaude-hook-writer\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: claude-hook-writer\ndescription: Expert guidance for writing secure, reliable, and performant Claude Code hooks - validates design decisions, enforces best practices, and prevents common pitfalls. Use when creating, reviewing, or debugging Claude Code hooks.\nmetadata:\n  version: 2.0.0\n  author: Claude Skills Maintainers\n  last_verified: 2025-12-17\n  optimization_date: 2025-12-17\n  token_savings: ~55%\n  errors_prevented: 5\nlicense: MIT\n---\n\n# Claude Hook Writer\n\n**Status**: Production Ready\n**Version**: 2.0.0 (Optimized with progressive disclosure)\n**Last Updated**: 2025-12-17\n\n---\n\n## Overview\n\nExpert guidance for writing secure, reliable, and performant Claude Code hooks. This skill validates design decisions, enforces best practices, and prevents common pitfalls.\n\n---\n\n## When to Use This Skill\n\n- Designing a new Claude Code hook\n- Reviewing existing hook code\n- Debugging hook failures\n- Optimizing slow hooks\n- Securing hooks that handle sensitive data\n- Publishing hooks as PRPM packages\n\n---\n\n## Core Principles\n\n### 1. Security is Non-Negotiable\n\nHooks execute automatically with user permissions and can read, modify, or delete any file the user can access.\n\n**ALWAYS validate and sanitize all input.** Hooks receive JSON via stdin—never trust it blindly.\n\n**For complete security patterns**: Load `references\u002Fsecurity-requirements.md` when implementing validation or securing hooks.\n\n### 2. Reliability Over Features\n\nA hook that works 99% of the time is a broken hook. Edge cases (Unicode filenames, spaces in paths, missing tools) will happen.\n\n**Test with edge cases before deploying.**\n\n**For reliability patterns**: Load `references\u002Freliability-performance.md` when handling errors or edge cases.\n\n### 3. Performance Matters\n\nHooks block operations. A 5-second hook means Claude waits 5 seconds before continuing.\n\n**Keep hooks fast. Run heavy operations in background.**\n\n**For performance optimization**: Load `references\u002Freliability-performance.md` when optimizing hook speed.\n\n### 4. Fail Gracefully\n\nMissing dependencies, malformed input, and disk errors will occur.\n\n**Handle errors explicitly. Log failures. Return meaningful exit codes.**\n\n---\n\n## Hook Design Checklist\n\nBefore writing code, answer these questions:\n\n### What Event Does This Hook Target?\n\n- `PreToolUse` - Before tool execution (modify input, validate, block)\n- `PostToolUse` - After tool completes (format, log, cleanup)\n- `UserPromptSubmit` - Before user input processes (validate, enhance)\n- `SessionStart` - When Claude Code starts (setup, env check)\n- `SessionEnd` - When Claude Code exits (cleanup, persist state)\n- `Notification` - During alerts (desktop notifications, logging)\n- `Stop` \u002F `SubagentStop` - When responses finish (cleanup, summary)\n- `PreCompact` - Before context compaction (save important context)\n\n**Common mistake:** Using PostToolUse for validation (too late—tool already ran). Use PreToolUse to block operations.\n\n### Which Tools Should Trigger This Hook?\n\nBe specific. `matcher: \"*\"` runs on every tool call.\n\n**Good matchers:**\n- `\"Write\"` - Only file writes\n- `\"Edit|Write\"` - File modifications\n- `\"Bash\"` - Shell commands\n- `\"mcp__github__*\"` - All GitHub MCP tools\n\n**Bad matchers:**\n- `\"*\"` - Everything (use only for logging\u002Fmetrics)\n\n### What Input Does This Hook Need?\n\nDifferent tools provide different input. Check what's available:\n\n```bash\n# PreToolUse \u002F PostToolUse\n{\n  \"input\": {\n    \"file_path\": \"\u002Fpath\u002Fto\u002Ffile.ts\",     \u002F\u002F Read, Write, Edit\n    \"command\": \"npm test\",                \u002F\u002F Bash\n    \"old_string\": \"...\",                  \u002F\u002F Edit\n    \"new_string\": \"...\"                   \u002F\u002F Edit\n  }\n}\n```\n\n**Validate fields exist before using them:**\n\n```bash\nFILE=$(echo \"$INPUT\" | jq -r '.input.file_path \u002F\u002F empty')\nif [[ -z \"$FILE\" ]]; then\n  echo \"No file path provided\" >&2\n  exit 1\nfi\n```\n\n### Should This Be a Command Hook or Prompt Hook?\n\n**Command hooks** (`type: \"command\"`):\n- Fast (milliseconds)\n- Deterministic\n- Good for: formatting, logging, file checks\n\n**Prompt hooks** (`type: \"prompt\"`):\n- Slow (2-10 seconds)\n- Context-aware (uses LLM)\n- Good for: complex validation, security analysis, intent detection\n\n**Rule of thumb:** Use command hooks unless you need LLM reasoning.\n\n### What Exit Code Communicates Success\u002FFailure?\n\n- `exit 0` - Success (continue operation)\n- `exit 2` - Block operation (show error to Claude)\n- `exit 1` or other - Non-blocking error (log but continue)\n\n**For PreToolUse hooks:**\n- Exit 2 blocks the tool from running\n- Exit 0 allows it (optionally with modified input)\n\n**For PostToolUse hooks:**\n- Exit codes don't block (tool already ran)\n- Use exit 0 for success, 1 for logging errors\n\n---\n\n## Top 5 Pitfalls (Must Know)\n\n### Pitfall #1: Not Quoting Variables\n\n**Error**: Hooks break on filenames with spaces or special characters\n\n**Why**: Unquoted variables split on whitespace\n\n**Example**:\n```bash\n# ❌ WRONG - breaks on \"my file.txt\"\ncat $FILE\nprettier --write $FILE\nrm $FILE\n\n# ✅ RIGHT - handles spaces and special chars\ncat \"$FILE\"\nprettier --write \"$FILE\"\nrm \"$FILE\"\n```\n\n**Why this matters**: Files with spaces (`\"my file.txt\"`), Unicode (`\"文件.txt\"`), or special chars (`\"file (1).txt\"`) are common.\n\n**For quoting best practices**: Load `references\u002Fsecurity-requirements.md` for comprehensive input handling patterns.\n\n---\n\n### Pitfall #2: Trusting Input Without Validation\n\n**Error**: Hook executes on malicious or malformed input\n\n**Why**: Not validating JSON fields before using them\n\n**Example**:\n```bash\n# ❌ DANGEROUS - no validation\nFILE=$(jq -r '.input.file_path')\nrm \"$FILE\"  # Could delete ..\u002F..\u002F..\u002Fetc\u002Fpasswd\n\n# ✅ SAFE - validate first\nFILE=$(jq -r '.input.file_path \u002F\u002F empty')\n[[ -n \"$FILE\" ]] || exit 1\n[[ \"$FILE\" == \"$CLAUDE_PROJECT_DIR\"* ]] || exit 2\n[[ \"$FILE\" != *\"..\"* ]] || exit 2\nrm \"$FILE\"\n```\n\n**Why this matters**: Prevents path traversal attacks, protects files outside project, prevents malformed input crashes.\n\n**For complete security patterns**: Load `references\u002Fsecurity-requirements.md`.\n\n---\n\n### Pitfall #3: Blocking Operations Too Long\n\n**Error**: Hook takes 30+ seconds, blocking Claude\n\n**Why**: Running expensive operations (tests, builds) synchronously in hook\n\n**Example**:\n```bash\n# ❌ BLOCKS Claude for 30 seconds\nnpm test\nnpm run build\n\n# ✅ RUN IN BACKGROUND - returns immediately\n(npm test > \u002Ftmp\u002Ftest-results.log 2>&1 &)\n(npm run build > \u002Ftmp\u002Fbuild.log 2>&1 &)\nexit 0\n```\n\n**Why this matters**: Slow hooks create bad user experience. Target \u003C 100ms for PreToolUse, \u003C 500ms for PostToolUse.\n\n**For performance optimization**: Load `references\u002Freliability-performance.md`.\n\n---\n\n### Pitfall #4: Wrong Exit Code for Blocking\n\n**Error**: PreToolUse hook doesn't actually block the operation\n\n**Why**: Using exit 1 instead of exit 2\n\n**Example**:\n```bash\n# ❌ WRONG - logs error but doesn't block\nif [[ $FILE == \".env\" ]]; then\n  echo \"Don't edit .env\" >&2\n  exit 1  # Tool still runs!\nfi\n\n# ✅ RIGHT - actually blocks\nif [[ $FILE == \".env\" ]]; then\n  echo \"Blocked: .env is protected\" >&2\n  exit 2  # Tool is blocked\nfi\n```\n\n**Why this matters**: Exit 1 only logs errors. Exit 2 is required to block in PreToolUse hooks.\n\n**For exit code patterns**: Load `references\u002Fhook-templates.md` for complete hook response patterns.\n\n---\n\n### Pitfall #5: Assuming Tools Exist\n\n**Error**: Hook crashes when dependency is missing\n\n**Why**: Not checking if tool is installed before using\n\n**Example**:\n```bash\n# ❌ BREAKS if prettier not installed\nprettier --write \"$FILE\"\n\n# ✅ SAFE - check first\nif command -v prettier &>\u002Fdev\u002Fnull; then\n  prettier --write \"$FILE\"\nelse\n  echo \"prettier not installed, skipping\" >&2\n  exit 0  # Success exit, just skip\nfi\n```\n\n**Why this matters**: Users may not have all tools installed. Hooks should degrade gracefully.\n\n**For reliability patterns**: Load `references\u002Freliability-performance.md`.\n\n---\n\n## Critical Rules\n\n### Always Do\n\n✅ Validate all JSON input before using (`jq -r '... \u002F\u002F empty'`)\n✅ Quote all variables containing paths or user input\n✅ Use absolute paths for scripts (`${CLAUDE_PLUGIN_ROOT}\u002F...`)\n✅ Block sensitive files (`.env`, `*.key`, credentials)\n✅ Check if required tools exist (`command -v toolname`)\n✅ Set reasonable timeouts (\u003C 5s for PreToolUse)\n✅ Run heavy operations in background\n✅ Test with edge cases (spaces, Unicode, special chars)\n✅ Use exit 2 to block in PreToolUse hooks\n✅ Log errors to stderr or file, not stdout\n\n### Never Do\n\n❌ Trust JSON input without validation\n❌ Use unquoted variables ($FILE instead of \"$FILE\")\n❌ Use relative paths for scripts\n❌ Skip path sanitization (check for `..`, validate in project)\n❌ Assume tools are installed\n❌ Block for > 1 second in PreToolUse hooks\n❌ Use exit 1 when you mean to block (use exit 2)\n❌ Log sensitive data to stdout or files\n❌ Use `matcher: \"*\"` unless truly necessary\n\n---\n\n## When to Load References\n\nLoad reference files when working on specific hook aspects:\n\n### Security Requirements (`references\u002Fsecurity-requirements.md`)\nLoad when:\n- Implementing input validation and sanitization\n- Securing hooks that handle sensitive data\n- Blocking sensitive files (`.env`, keys, credentials)\n- Preventing path traversal attacks\n- Understanding security vulnerabilities and best practices\n- Testing security with malicious input\n\n### Reliability & Performance (`references\u002Freliability-performance.md`)\nLoad when:\n- Handling missing dependencies or tools\n- Setting timeouts and handling slow operations\n- Optimizing hook performance (\u003C 100ms target)\n- Running heavy operations in background\n- Caching expensive results\n- Testing with edge cases (Unicode, spaces, deep paths)\n- Deduplicating expensive operations\n\n### Code Templates (`references\u002Fcode-templates.md`)\nLoad when:\n- Starting a new hook and need working examples\n- Implementing format-on-save functionality\n- Blocking sensitive files from modification\n- Logging commands or operations\n- Using prompt-based security analysis\n- Customizing templates for specific use cases\n\n### Testing & Debugging (`references\u002Ftesting-debugging.md`)\nLoad when:\n- Writing test cases for hooks\n- Debugging hook failures or unexpected behavior\n- Testing with edge cases (malformed JSON, missing fields)\n- Checking hook execution in transcript (Ctrl-R)\n- Profiling hook performance\n- Creating automated test suites\n\n### Publishing Guide (`references\u002Fpublishing-guide.md`)\nLoad when:\n- Publishing hooks to PRPM registry\n- Creating package manifest (prpm.json)\n- Configuring hook.json with advanced options\n- Using `continue`, `stopReason`, `suppressOutput`, `systemMessage`\n- Writing README.md for users\n- Understanding versioning and publishing commands\n\n### Quick Reference (`references\u002Fquick-reference.md`)\nLoad when:\n- Need quick syntax lookup (exit codes, jq patterns)\n- Looking up environment variables\n- Finding common bash patterns (file validation, background execution)\n- Checking hook events and matchers\n- Need performance tips summary\n- Looking up JSON input structure\n\n---\n\n## Final Checklist\n\nBefore publishing a hook:\n\n- [ ] Validates all stdin input with jq\n- [ ] Quotes all variables\n- [ ] Uses absolute paths for scripts\n- [ ] Blocks sensitive files (`.env`, `*.key`, etc.)\n- [ ] Handles missing tools gracefully\n- [ ] Sets reasonable timeout (\u003C 5s for PreToolUse)\n- [ ] Logs errors to stderr or file, not stdout\n- [ ] Tests with edge cases (spaces, Unicode, malformed JSON)\n- [ ] Tests in real Claude Code session\n- [ ] Documents dependencies in README\n- [ ] Uses semantic versioning\n- [ ] Clear description and tags\n\n---\n\n## Using Bundled Resources\n\nThis skill includes 6 reference files for on-demand loading:\n\n**Security & Reliability** (2 files):\n- `security-requirements.md` - Input validation, path sanitization, blocking sensitive files\n- `reliability-performance.md` - Error handling, timeouts, performance optimization\n\n**Implementation** (2 files):\n- `code-templates.md` - Working hook examples (format-on-save, block-sensitive, logger, etc.)\n- `quick-reference.md` - Fast syntax lookup (exit codes, jq patterns, environment vars)\n\n**Testing & Publishing** (2 files):\n- `testing-debugging.md` - Test patterns, edge cases, debugging techniques\n- `publishing-guide.md` - PRPM packaging, advanced configuration, README template\n\nLoad references on-demand when specific knowledge is needed. See \"When to Load References\" section for triggers.\n\n---\n\n## Resources\n\n- [Claude Code Hooks Docs](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Fhooks)\n- [PRPM Hook Packages](https:\u002F\u002Fprpm.dev\u002Fpackages?format=claude&subtype=hook)\n\n---\n\n**Last verified**: 2025-12-17 | **Version**: 2.0.0\n","# Claude Hook Writer\n\n**Status**: Production Ready\n**Version**: 2.0.0 (Optimized with progressive disclosure)\n**Last Updated**: 2025-12-17\n\n---\n\n## Overview\n\nExpert guidance for writing secure, reliable, and performant Claude Code hooks. This skill validates design decisions, enforces best practices, and prevents common pitfalls.\n\n---\n\n## When to Use This Skill\n\n- Designing a new Claude Code hook\n- Reviewing existing hook code\n- Debugging hook failures\n- Optimizing slow hooks\n- Securing hooks that handle sensitive data\n- Publishing hooks as PRPM packages\n\n---\n\n## Core Principles\n\n### 1. Security is Non-Negotiable\n\nHooks execute automatically with user permissions and can read, modify, or delete any file the user can access.\n\n**ALWAYS validate and sanitize all input.** Hooks receive JSON via stdin—never trust it blindly.\n\n**For complete security patterns**: Load `references\u002Fsecurity-requirements.md` when implementing validation or securing hooks.\n\n### 2. Reliability Over Features\n\nA hook that works 99% of the time is a broken hook. Edge cases (Unicode filenames, spaces in paths, missing tools) will happen.\n\n**Test with edge cases before deploying.**\n\n**For reliability patterns**: Load `references\u002Freliability-performance.md` when handling errors or edge cases.\n\n### 3. Performance Matters\n\nHooks block operations. A 5-second hook means Claude waits 5 seconds before continuing.\n\n**Keep hooks fast. Run heavy operations in background.**\n\n**For performance optimization**: Load `references\u002Freliability-performance.md` when optimizing hook speed.\n\n### 4. Fail Gracefully\n\nMissing dependencies, malformed input, and disk errors will occur.\n\n**Handle errors explicitly. Log failures. Return meaningful exit codes.**\n\n---\n\n## Hook Design Checklist\n\nBefore writing code, answer these questions:\n\n### What Event Does This Hook Target?\n\n- `PreToolUse` - Before tool execution (modify input, validate, block)\n- `PostToolUse` - After tool completes (format, log, cleanup)\n- `UserPromptSubmit` - Before user input processes (validate, enhance)\n- `SessionStart` - When Claude Code starts (setup, env check)\n- `SessionEnd` - When Claude Code exits (cleanup, persist state)\n- `Notification` - During alerts (desktop notifications, logging)\n- `Stop` \u002F `SubagentStop` - When responses finish (cleanup, summary)\n- `PreCompact` - Before context compaction (save important context)\n\n**Common mistake:** Using PostToolUse for validation (too late—tool already ran). Use PreToolUse to block operations.\n\n### Which Tools Should Trigger This Hook?\n\nBe specific. `matcher: \"*\"` runs on every tool call.\n\n**Good matchers:**\n- `\"Write\"` - Only file writes\n- `\"Edit|Write\"` - File modifications\n- `\"Bash\"` - Shell commands\n- `\"mcp__github__*\"` - All GitHub MCP tools\n\n**Bad matchers:**\n- `\"*\"` - Everything (use only for logging\u002Fmetrics)\n\n### What Input Does This Hook Need?\n\nDifferent tools provide different input. Check what's available:\n\n```bash\n# PreToolUse \u002F PostToolUse\n{\n  \"input\": {\n    \"file_path\": \"\u002Fpath\u002Fto\u002Ffile.ts\",     \u002F\u002F Read, Write, Edit\n    \"command\": \"npm test\",                \u002F\u002F Bash\n    \"old_string\": \"...\",                  \u002F\u002F Edit\n    \"new_string\": \"...\"                   \u002F\u002F Edit\n  }\n}\n```\n\n**Validate fields exist before using them:**\n\n```bash\nFILE=$(echo \"$INPUT\" | jq -r '.input.file_path \u002F\u002F empty')\nif [[ -z \"$FILE\" ]]; then\n  echo \"No file path provided\" >&2\n  exit 1\nfi\n```\n\n### Should This Be a Command Hook or Prompt Hook?\n\n**Command hooks** (`type: \"command\"`):\n- Fast (milliseconds)\n- Deterministic\n- Good for: formatting, logging, file checks\n\n**Prompt hooks** (`type: \"prompt\"`):\n- Slow (2-10 seconds)\n- Context-aware (uses LLM)\n- Good for: complex validation, security analysis, intent detection\n\n**Rule of thumb:** Use command hooks unless you need LLM reasoning.\n\n### What Exit Code Communicates Success\u002FFailure?\n\n- `exit 0` - Success (continue operation)\n- `exit 2` - Block operation (show error to Claude)\n- `exit 1` or other - Non-blocking error (log but continue)\n\n**For PreToolUse hooks:**\n- Exit 2 blocks the tool from running\n- Exit 0 allows it (optionally with modified input)\n\n**For PostToolUse hooks:**\n- Exit codes don't block (tool already ran)\n- Use exit 0 for success, 1 for logging errors\n\n---\n\n## Top 5 Pitfalls (Must Know)\n\n### Pitfall #1: Not Quoting Variables\n\n**Error**: Hooks break on filenames with spaces or special characters\n\n**Why**: Unquoted variables split on whitespace\n\n**Example**:\n```bash\n# ❌ WRONG - breaks on \"my file.txt\"\ncat $FILE\nprettier --write $FILE\nrm $FILE\n\n# ✅ RIGHT - handles spaces and special chars\ncat \"$FILE\"\nprettier --write \"$FILE\"\nrm \"$FILE\"\n```\n\n**Why this matters**: Files with spaces (`\"my file.txt\"`), Unicode (`\"文件.txt\"`), or special chars (`\"file (1).txt\"`) are common.\n\n**For quoting best practices**: Load `references\u002Fsecurity-requirements.md` for comprehensive input handling patterns.\n\n---\n\n### Pitfall #2: Trusting Input Without Validation\n\n**Error**: Hook executes on malicious or malformed input\n\n**Why**: Not validating JSON fields before using them\n\n**Example**:\n```bash\n# ❌ DANGEROUS - no validation\nFILE=$(jq -r '.input.file_path')\nrm \"$FILE\"  # Could delete ..\u002F..\u002F..\u002Fetc\u002Fpasswd\n\n# ✅ SAFE - validate first\nFILE=$(jq -r '.input.file_path \u002F\u002F empty')\n[[ -n \"$FILE\" ]] || exit 1\n[[ \"$FILE\" == \"$CLAUDE_PROJECT_DIR\"* ]] || exit 2\n[[ \"$FILE\" != *\"..\"* ]] || exit 2\nrm \"$FILE\"\n```\n\n**Why this matters**: Prevents path traversal attacks, protects files outside project, prevents malformed input crashes.\n\n**For complete security patterns**: Load `references\u002Fsecurity-requirements.md`.\n\n---\n\n### Pitfall #3: Blocking Operations Too Long\n\n**Error**: Hook takes 30+ seconds, blocking Claude\n\n**Why**: Running expensive operations (tests, builds) synchronously in hook\n\n**Example**:\n```bash\n# ❌ BLOCKS Claude for 30 seconds\nnpm test\nnpm run build\n\n# ✅ RUN IN BACKGROUND - returns immediately\n(npm test > \u002Ftmp\u002Ftest-results.log 2>&1 &)\n(npm run build > \u002Ftmp\u002Fbuild.log 2>&1 &)\nexit 0\n```\n\n**Why this matters**: Slow hooks create bad user experience. Target \u003C 100ms for PreToolUse, \u003C 500ms for PostToolUse.\n\n**For performance optimization**: Load `references\u002Freliability-performance.md`.\n\n---\n\n### Pitfall #4: Wrong Exit Code for Blocking\n\n**Error**: PreToolUse hook doesn't actually block the operation\n\n**Why**: Using exit 1 instead of exit 2\n\n**Example**:\n```bash\n# ❌ WRONG - logs error but doesn't block\nif [[ $FILE == \".env\" ]]; then\n  echo \"Don't edit .env\" >&2\n  exit 1  # Tool still runs!\nfi\n\n# ✅ RIGHT - actually blocks\nif [[ $FILE == \".env\" ]]; then\n  echo \"Blocked: .env is protected\" >&2\n  exit 2  # Tool is blocked\nfi\n```\n\n**Why this matters**: Exit 1 only logs errors. Exit 2 is required to block in PreToolUse hooks.\n\n**For exit code patterns**: Load `references\u002Fhook-templates.md` for complete hook response patterns.\n\n---\n\n### Pitfall #5: Assuming Tools Exist\n\n**Error**: Hook crashes when dependency is missing\n\n**Why**: Not checking if tool is installed before using\n\n**Example**:\n```bash\n# ❌ BREAKS if prettier not installed\nprettier --write \"$FILE\"\n\n# ✅ SAFE - check first\nif command -v prettier &>\u002Fdev\u002Fnull; then\n  prettier --write \"$FILE\"\nelse\n  echo \"prettier not installed, skipping\" >&2\n  exit 0  # Success exit, just skip\nfi\n```\n\n**Why this matters**: Users may not have all tools installed. Hooks should degrade gracefully.\n\n**For reliability patterns**: Load `references\u002Freliability-performance.md`.\n\n---\n\n## Critical Rules\n\n### Always Do\n\n✅ Validate all JSON input before using (`jq -r '... \u002F\u002F empty'`)\n✅ Quote all variables containing paths or user input\n✅ Use absolute paths for scripts (`${CLAUDE_PLUGIN_ROOT}\u002F...`)\n✅ Block sensitive files (`.env`, `*.key`, credentials)\n✅ Check if required tools exist (`command -v toolname`)\n✅ Set reasonable timeouts (\u003C 5s for PreToolUse)\n✅ Run heavy operations in background\n✅ Test with edge cases (spaces, Unicode, special chars)\n✅ Use exit 2 to block in PreToolUse hooks\n✅ Log errors to stderr or file, not stdout\n\n### Never Do\n\n❌ Trust JSON input without validation\n❌ Use unquoted variables ($FILE instead of \"$FILE\")\n❌ Use relative paths for scripts\n❌ Skip path sanitization (check for `..`, validate in project)\n❌ Assume tools are installed\n❌ Block for > 1 second in PreToolUse hooks\n❌ Use exit 1 when you mean to block (use exit 2)\n❌ Log sensitive data to stdout or files\n❌ Use `matcher: \"*\"` unless truly necessary\n\n---\n\n## When to Load References\n\nLoad reference files when working on specific hook aspects:\n\n### Security Requirements (`references\u002Fsecurity-requirements.md`)\nLoad when:\n- Implementing input validation and sanitization\n- Securing hooks that handle sensitive data\n- Blocking sensitive files (`.env`, keys, credentials)\n- Preventing path traversal attacks\n- Understanding security vulnerabilities and best practices\n- Testing security with malicious input\n\n### Reliability & Performance (`references\u002Freliability-performance.md`)\nLoad when:\n- Handling missing dependencies or tools\n- Setting timeouts and handling slow operations\n- Optimizing hook performance (\u003C 100ms target)\n- Running heavy operations in background\n- Caching expensive results\n- Testing with edge cases (Unicode, spaces, deep paths)\n- Deduplicating expensive operations\n\n### Code Templates (`references\u002Fcode-templates.md`)\nLoad when:\n- Starting a new hook and need working examples\n- Implementing format-on-save functionality\n- Blocking sensitive files from modification\n- Logging commands or operations\n- Using prompt-based security analysis\n- Customizing templates for specific use cases\n\n### Testing & Debugging (`references\u002Ftesting-debugging.md`)\nLoad when:\n- Writing test cases for hooks\n- Debugging hook failures or unexpected behavior\n- Testing with edge cases (malformed JSON, missing fields)\n- Checking hook execution in transcript (Ctrl-R)\n- Profiling hook performance\n- Creating automated test suites\n\n### Publishing Guide (`references\u002Fpublishing-guide.md`)\nLoad when:\n- Publishing hooks to PRPM registry\n- Creating package manifest (prpm.json)\n- Configuring hook.json with advanced options\n- Using `continue`, `stopReason`, `suppressOutput`, `systemMessage`\n- Writing README.md for users\n- Understanding versioning and publishing commands\n\n### Quick Reference (`references\u002Fquick-reference.md`)\nLoad when:\n- Need quick syntax lookup (exit codes, jq patterns)\n- Looking up environment variables\n- Finding common bash patterns (file validation, background execution)\n- Checking hook events and matchers\n- Need performance tips summary\n- Looking up JSON input structure\n\n---\n\n## Final Checklist\n\nBefore publishing a hook:\n\n- [ ] Validates all stdin input with jq\n- [ ] Quotes all variables\n- [ ] Uses absolute paths for scripts\n- [ ] Blocks sensitive files (`.env`, `*.key`, etc.)\n- [ ] Handles missing tools gracefully\n- [ ] Sets reasonable timeout (\u003C 5s for PreToolUse)\n- [ ] Logs errors to stderr or file, not stdout\n- [ ] Tests with edge cases (spaces, Unicode, malformed JSON)\n- [ ] Tests in real Claude Code session\n- [ ] Documents dependencies in README\n- [ ] Uses semantic versioning\n- [ ] Clear description and tags\n\n---\n\n## Using Bundled Resources\n\nThis skill includes 6 reference files for on-demand loading:\n\n**Security & Reliability** (2 files):\n- `security-requirements.md` - Input validation, path sanitization, blocking sensitive files\n- `reliability-performance.md` - Error handling, timeouts, performance optimization\n\n**Implementation** (2 files):\n- `code-templates.md` - Working hook examples (format-on-save, block-sensitive, logger, etc.)\n- `quick-reference.md` - Fast syntax lookup (exit codes, jq patterns, environment vars)\n\n**Testing & Publishing** (2 files):\n- `testing-debugging.md` - Test patterns, edge cases, debugging techniques\n- `publishing-guide.md` - PRPM packaging, advanced configuration, README template\n\nLoad references on-demand when specific knowledge is needed. See \"When to Load References\" section for triggers.\n\n---\n\n## Resources\n\n- [Claude Code Hooks Docs](https:\u002F\u002Fdocs.claude.com\u002Fen\u002Fdocs\u002Fclaude-code\u002Fhooks)\n- [PRPM Hook Packages](https:\u002F\u002Fprpm.dev\u002Fpackages?format=claude&subtype=hook)\n\n---\n\n**Last verified**: 2025-12-17 | **Version**: 2.0.0\n",{"name":5,"license":14,"metadata":23,"description":7},{"author":24,"version":25,"last_verified":26,"token_savings":27,"errors_prevented":28,"optimization_date":26},"Claude Skills Maintainers","2.0.0",1765929600000,"~55%",5,"main","9f54582c8b485462d402d7e70feaef34801746b9",".opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fclaude-hook-writer\u002Fskills\u002Fclaude-hook-writer","https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web","https:\u002F\u002Fgithub.com\u002Faibizmod","2026-09-24 00:48:11",{"source":8,"skillName":5,"commands":36,"prompt":46,"zipAvailable":47},[37,40,43],{"tool":38,"command":39},"npx","npx skills add aibizmod\u002Faibizmod-service-web --skill claude-hook-writer",{"tool":41,"command":42},"bunx","bunx skills add aibizmod\u002Faibizmod-service-web --skill claude-hook-writer",{"tool":44,"command":45},"pnpm","pnpm dlx skills add aibizmod\u002Faibizmod-service-web --skill claude-hook-writer","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fclaude-hook-writer\u002Fskills\u002Fclaude-hook-writer\u002FSKILL.md",true,[49,55,59,63,67,71],{"path":50,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":53,"sourceHtmlUrl":54},"references\u002Fcode-templates.md","REFERENCE","参考文档",7915,"https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fclaude-hook-writer\u002Fskills\u002Fclaude-hook-writer\u002Freferences\u002Fcode-templates.md",{"path":56,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":57,"sourceHtmlUrl":58},"references\u002Fpublishing-guide.md",3954,"https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fclaude-hook-writer\u002Fskills\u002Fclaude-hook-writer\u002Freferences\u002Fpublishing-guide.md",{"path":60,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":61,"sourceHtmlUrl":62},"references\u002Fquick-reference.md",4895,"https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fclaude-hook-writer\u002Fskills\u002Fclaude-hook-writer\u002Freferences\u002Fquick-reference.md",{"path":64,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":65,"sourceHtmlUrl":66},"references\u002Freliability-performance.md",9047,"https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fclaude-hook-writer\u002Fskills\u002Fclaude-hook-writer\u002Freferences\u002Freliability-performance.md",{"path":68,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":69,"sourceHtmlUrl":70},"references\u002Fsecurity-requirements.md",6669,"https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fclaude-hook-writer\u002Fskills\u002Fclaude-hook-writer\u002Freferences\u002Fsecurity-requirements.md",{"path":72,"resourceType":51,"resourceTypeDesc":52,"sizeBytes":73,"sourceHtmlUrl":74},"references\u002Ftesting-debugging.md",3673,"https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fclaude-hook-writer\u002Fskills\u002Fclaude-hook-writer\u002Freferences\u002Ftesting-debugging.md",[76,83,90,97,104,111],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":18},"01M7846EAPZWCQ8C6G3AAMMR57","{TODO=lowercase-hyphen-case-name}","[TODO: Write comprehensive description in third-person. Start with \"This skill provides...\" or \"This skill should be used when...\"]\n\n[TODO: Add \"Use when\" scenarios - specific situations where Claude should use this skill]\n\n[TODO: Add keywords - technologies, use cases, error messages that should trigger this skill]","https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Ftemplates\u002Fskill-skeleton\u002Fskills\u002Fskill-name\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":18},"01M7846A0WGDKJTDPD5QMHQVFV","zustand-state-management","Zustand state management for React with TypeScript. Use for global state, Redux\u002FContext API migration, localStorage persistence, slices pattern, devtools, Next.js SSR, or encountering hydration errors, TypeScript inference issues, persist middleware problems, infinite render loops.","https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fzustand-state-management\u002Fskills\u002Fzustand-state-management\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":18},"01M78463GGSP9B3JSF146B2MG0","zod","TypeScript-first schema validation and type inference. Use for validating API requests\u002Fresponses, form data, env vars, configs, defining type-safe schemas with runtime validation, transforming data, generating JSON Schema for OpenAPI\u002FAI, or encountering missing validation errors, type inference issues, validation error handling problems. Zero dependencies (2kb gzipped).","https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fzod\u002Fskills\u002Fzod\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":18},"01M7845ZX17SVNNY7EDGPJHSBT","xss-prevention","XSS attack prevention with input sanitization, output encoding, Content Security Policy. Use for user-generated content, rich text editors, web application security, or encountering stored XSS, reflected XSS, DOM manipulation, script injection errors.","https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fxss-prevention\u002Fskills\u002Fxss-prevention\u002FSKILL.md",[],[],{"skillNo":105,"name":106,"nameZh":6,"description":107,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":18},"01M7845ST1H37YHSXWWQ9N0V0S","wordpress-plugin-core","WordPress plugin development with hooks, security, REST API, custom post types. Use for plugin creation, $wpdb queries, Settings API, or encountering SQL injection, XSS, CSRF, nonce errors.","https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fwordpress-plugin-core\u002Fskills\u002Fwordpress-plugin-core\u002FSKILL.md",[],[],{"skillNo":112,"name":113,"nameZh":6,"description":114,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":117,"publishedAt":18},"01M7845PTWD5HWSTGP35Q8TFNY","woocommerce-dev-cycle","Run tests, linting, and quality checks for WooCommerce development. Use when running tests, fixing code style, or following the development workflow in WooCommerce projects.","https:\u002F\u002Fgithub.com\u002Faibizmod\u002Faibizmod-service-web\u002Fblob\u002Fmain\u002F.opencode\u002Fskill\u002Fclaude-skills\u002Fplugins\u002Fwoocommerce-dev-cycle\u002Fskills\u002Fwoocommerce-dev-cycle\u002FSKILL.md",[],[]]