| | @@ -1,6 +1,6 @@ |
| 1 | 1 | --- |
| 2 | 2 | name: Hook Development |
| 3 | | -description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, PreTeleport, PostTeleport). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API. |
| 3 | +description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", "teleport hook", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API. |
| 4 | 4 | version: 0.1.0 |
| 5 | 5 | --- |
| 6 | 6 | |
| | @@ -239,7 +239,12 @@ |
| 239 | 239 | |
| 240 | 240 | Execute when Claude Code session begins. Use to load context and set environment. |
| 241 | 241 | |
| 242 | | -**Example:** |
| 242 | +**Matchers for SessionStart:** |
| 243 | +- `*` - All session starts |
| 244 | +- `teleport` - Only when session started via teleport (web → CLI) |
| 245 | +- `fresh` - Only for fresh sessions (not teleported) |
| 246 | + |
| 247 | +**Example (general context loading):** |
| 243 | 248 | ```json |
| 244 | 249 | { |
| 245 | 250 | "SessionStart": [ |
| | @@ -256,82 +261,15 @@ |
| 256 | 261 | } |
| 257 | 262 | ``` |
| 258 | 263 | |
| 259 | | -**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`: |
| 260 | | -```bash |
| 261 | | -echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE" |
| 262 | | -``` |
| 263 | | - |
| 264 | | -See `examples/load-context.sh` for complete example. |
| 265 | | - |
| 266 | | -### SessionEnd |
| 267 | | - |
| 268 | | -Execute when session ends. Use for cleanup, logging, and state preservation. |
| 269 | | - |
| 270 | | -### PreCompact |
| 271 | | - |
| 272 | | -Execute before context compaction. Use to add critical information to preserve. |
| 273 | | - |
| 274 | | -### Notification |
| 275 | | - |
| 276 | | -Execute when Claude sends notifications. Use to react to user notifications. |
| 277 | | - |
| 278 | | -### PreTeleport |
| 279 | | - |
| 280 | | -Execute before a session teleports (transfers from web to CLI or vice versa). Use to prepare the environment, sync state, or validate teleport conditions. |
| 281 | | - |
| 282 | | -**Example:** |
| 264 | +**Example (teleport-specific setup):** |
| 283 | 265 | ```json |
| 284 | 266 | { |
| 285 | | - "PreTeleport": [ |
| 267 | + "SessionStart": [ |
| 286 | 268 | { |
| 287 | | - "matcher": "*", |
| 269 | + "matcher": "teleport", |
| 288 | 270 | "hooks": [ |
| 289 | 271 | { |
| 290 | 272 | "type": "command", |
| 291 | | - "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/pre-teleport.sh" |
| 292 | | - } |
| 293 | | - ] |
| 294 | | - } |
| 295 | | - ] |
| 296 | | -} |
| 297 | | -``` |
| 298 | | - |
| 299 | | -**Example script (pre-teleport.sh):** |
| 300 | | -```bash |
| 301 | | -#!/bin/bash |
| 302 | | -# Stash any uncommitted changes before teleporting |
| 303 | | -cd "$CLAUDE_PROJECT_DIR" || exit 0 |
| 304 | | - |
| 305 | | -if [ -d ".git" ] && [ -n "$(git status --porcelain)" ]; then |
| 306 | | - echo "📦 Stashing uncommitted changes before teleport..." |
| 307 | | - git stash push -m "pre-teleport-stash-$(date +%s)" |
| 308 | | -fi |
| 309 | | -``` |
| 310 | | - |
| 311 | | -**Input fields:** |
| 312 | | -- `source`: The origin of the teleport ("web" or "cli") |
| 313 | | -- `destination`: Where the session is going ("web" or "cli") |
| 314 | | -- `branch`: The git branch being teleported (if applicable) |
| 315 | | - |
| 316 | | -**Use for:** |
| 317 | | -- Stashing uncommitted work before teleporting |
| 318 | | -- Syncing local state with remote |
| 319 | | -- Validating prerequisites before teleport |
| 320 | | -- Cleaning up temporary files |
| 321 | | - |
| 322 | | -### PostTeleport |
| 323 | | - |
| 324 | | -Execute after a session successfully teleports. Use to set up the environment in the new context, run dev servers, or restore state. |
| 325 | | - |
| 326 | | -**Example:** |
| 327 | | -```json |
| 328 | | -{ |
| 329 | | - "PostTeleport": [ |
| 330 | | - { |
| 331 | | - "matcher": "*", |
| 332 | | - "hooks": [ |
| 333 | | - { |
| 334 | | - "type": "command", |
| 335 | 273 | "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/post-teleport.sh" |
| 336 | 274 | } |
| 337 | 275 | ] |
| | @@ -364,19 +302,30 @@ |
| 364 | 302 | fi |
| 365 | 303 | ``` |
| 366 | 304 | |
| 367 | | -**Input fields:** |
| 368 | | -- `source`: Where the session came from ("web" or "cli") |
| 369 | | -- `destination`: The current context ("web" or "cli") |
| 370 | | -- `branch`: The git branch that was teleported |
| 371 | | -- `teleport_success`: Boolean indicating if teleport completed successfully |
| 305 | +**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`: |
| 306 | +```bash |
| 307 | +echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE" |
| 308 | +``` |
| 372 | 309 | |
| 373 | | -**Use for:** |
| 374 | | -- Pulling latest changes after teleporting |
| 375 | | -- Installing/updating dependencies |
| 376 | | -- Starting development servers |
| 377 | | -- Restoring stashed work |
| 378 | | -- Running project-specific setup scripts |
| 310 | +**Teleport-specific input fields:** |
| 311 | +- `is_teleport`: Boolean indicating if this session started via teleport |
| 312 | +- `source`: Where the session came from ("web" or "cli") - only present for teleports |
| 313 | +- `branch`: The git branch that was teleported - only present for teleports |
| 379 | 314 | |
| 315 | +See `examples/load-context.sh` and `examples/post-teleport.sh` for complete examples. |
| 316 | + |
| 317 | +### SessionEnd |
| 318 | + |
| 319 | +Execute when session ends. Use for cleanup, logging, and state preservation. |
| 320 | + |
| 321 | +### PreCompact |
| 322 | + |
| 323 | +Execute before context compaction. Use to add critical information to preserve. |
| 324 | + |
| 325 | +### Notification |
| 326 | + |
| 327 | +Execute when Claude sends notifications. Use to react to user notifications. |
| 328 | + |
| 380 | 329 | ## Hook Output Format |
| 381 | 330 | |
| 382 | 331 | ### Standard Output (All Hooks) |
| | @@ -740,12 +689,10 @@ |
| 740 | 689 | | UserPromptSubmit | User input | Context, validation | |
| 741 | 690 | | Stop | Agent stopping | Completeness check | |
| 742 | 691 | | SubagentStop | Subagent done | Task validation | |
| 743 | | -| SessionStart | Session begins | Context loading | |
| 692 | +| SessionStart | Session begins | Context loading (use `teleport` matcher for teleport-specific setup) | |
| 744 | 693 | | SessionEnd | Session ends | Cleanup, logging | |
| 745 | 694 | | PreCompact | Before compact | Preserve context | |
| 746 | 695 | | Notification | User notified | Logging, reactions | |
| 747 | | -| PreTeleport | Before teleport | Stash work, sync state | |
| 748 | | -| PostTeleport | After teleport | Setup env, start servers | |
| 749 | 696 | |
| 750 | 697 | ### Best Practices |
| 751 | 698 | |
| | @@ -783,8 +730,7 @@ |
| 783 | 730 | - **`validate-write.sh`** - File write validation example |
| 784 | 731 | - **`validate-bash.sh`** - Bash command validation example |
| 785 | 732 | - **`load-context.sh`** - SessionStart context loading example |
| 786 | | -- **`pre-teleport.sh`** - PreTeleport state preservation example |
| 787 | | -- **`post-teleport.sh`** - PostTeleport environment setup example |
| 733 | +- **`post-teleport.sh`** - SessionStart teleport matcher setup example |
| 788 | 734 | |
| 789 | 735 | ### Utility Scripts |
| 790 | 736 | |