Initial commit

2025-11-29 18:00:36 +08:00
commit c83b4639c5
49 changed files with 18594 additions and 0 deletions
--- a/skills/hook-creator/SKILL.md
+++ b/skills/hook-creator/SKILL.md
@@ -0,0 +1,190 @@
+---
+name: hook-creator
+description: >
+  This skill should be used when the user asks to "create a hook", "write hook config", "add
+  hooks.json", "configure event hooks", "create PreToolUse hook", "add SessionStart hook",
+  "implement hook validation", "set up event-driven automation", needs guidance on hooks.json
+  structure, hook events (PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd,
+  UserPromptSubmit), or wants to automate workflows and implement event-driven behavior in Claude
+  Code plugins.
+---
+
+# Hook Creator
+
+## Overview
+
+Creates hook configurations that respond to Claude Code events automatically. Hooks
+enable automation like formatting on save, running tests after edits, or custom session
+initialization.
+
+**When to use:** User wants to automate workflows, needs event-driven behavior, or requests hooks for their plugin.
+
+**References:** Consult
+`plugins/meta/claude-docs/skills/claude-docs/reference/plugins-reference.md` for hook specifications and available
+events.
+
+## Hook Structure Requirements
+
+Hooks are defined in `hooks/hooks.json` with:
+
+1. **Event type** (SessionStart, PostToolUse, etc.)
+2. **Matcher** (optional, for filtering which tool uses trigger hook)
+3. **Hook actions** (command, validation, notification)
+4. **Proper use of** `${CLAUDE_PLUGIN_ROOT}` for plugin-relative paths
+
+## Available Events
+
+From official documentation:
+
+- `PreToolUse` - Before Claude uses any tool
+- `PostToolUse` - After Claude uses any tool
+- `UserPromptSubmit` - When user submits a prompt
+- `Notification` - When Claude Code sends notifications
+- `Stop` - When Claude attempts to stop
+- `SubagentStop` - When subagent attempts to stop
+- `SessionStart` - At session beginning
+- `SessionEnd` - At session end
+- `PreCompact` - Before conversation history compaction
+
+## Creation Process
+
+### Step 1: Identify Event and Purpose
+
+Ask the user:
+
+- What should happen automatically?
+- When should it happen (which event)?
+- What tool uses should trigger it (if PostToolUse)?
+
+### Step 2: Choose Hook Type
+
+Three hook types:
+
+- **command**: Execute shell commands/scripts
+- **validation**: Validate file contents or project state
+- **notification**: Send alerts or status updates
+
+### Step 3: Write Hook Configuration
+
+Structure for `hooks/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "ToolName1|ToolName2",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/script.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Step 4: Create Associated Scripts
+
+If using command hooks:
+
+1. Create script in plugin's `scripts/` directory
+2. Make executable: `chmod +x scripts/script.sh`
+3. Use `${CLAUDE_PLUGIN_ROOT}` for paths
+
+### Step 5: Verify Against Official Docs
+
+Check
+`plugins/meta/claude-docs/skills/claude-docs/reference/plugins-reference.md` for:
+
+- Current event names
+- Hook configuration schema
+- Environment variable usage
+
+## Key Principles
+
+- **Event Selection**: Choose most specific event for the need
+- **Matcher Precision**: Use matchers to avoid unnecessary executions
+- **Script Paths**: Always use `${CLAUDE_PLUGIN_ROOT}` for portability
+- **Error Handling**: Scripts should handle errors gracefully
+
+## Examples
+
+### Example 1: Code Formatting Hook
+
+User: "Auto-format code after I edit files"
+
+Hook configuration:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Creates `scripts/format-code.sh` that runs formatter on modified files.
+
+### Example 2: Session Welcome Message
+
+User: "Show a message when Claude starts"
+
+Hook configuration:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo 'Welcome! Plugin loaded successfully.'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Simple command hook, no external script needed.
+
+### Example 3: Test Runner Hook
+
+User: "Run tests after I modify test files"
+
+Hook configuration:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/run-tests.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Creates `scripts/run-tests.sh` that detects test file changes and runs relevant tests.