Hooks Test Skill

Demonstrates the complete hooks functionality in Claude Agent SDK. This skill showcases how PreToolUse, PostToolUse, and Stop hooks work together to provide event-driven automation.

What are Hooks?

Hooks are event-driven commands that run at specific points during skill execution:

• PreToolUse: Runs BEFORE a tool is executed
• PostToolUse: Runs AFTER a tool completes successfully
• Stop: Runs when the skill execution stops or completes

Hook Configuration

Each hook has:

• matcher: Pattern to match tool names (e.g., "Bash", "Write", "*")
• command: Shell command to execute
• once: If true, runs only once per session (default: false)
• type: Execution type - "command", "script", or "function"

Testing the Hooks

Test 1: Bash Tool Hooks

When you ask me to run a Bash command:

Please run: echo "Hello World"

Expected Output:

🔍 PreToolUse: About to execute Bash tool
[Bash command executes]
✅ PostToolUse: Bash tool executed successfully

Test 2: Write Tool Hooks

When you ask me to write a file:

Create a file named test.txt with content "Hello"

Expected Output:

📝 PreToolUse: About to write file - Write
[File is written]
💾 PostToolUse: File written successfully

Test 3: Wildcard Matcher

The * matcher with once: true will run only once for the first tool used:

Run any command

Expected Output:

⚡ PreToolUse: Tool <tool_name> is about to be used
[This message appears only once per session]

Test 4: Stop Hook

When this skill finishes execution:

Expected Output:

🛑 Stop hook: Cleaning up resources...

Hook Features Demonstrated

1. Tool-Specific Hooks

• PreToolUse and PostToolUse for specific tools (Bash, Write)
• Fine-grained control over tool execution

2. Wildcard Matching

• * matcher applies to all tools
• Useful for global hooks like logging

3. Once-Only Execution

• once: true ensures hook runs only once per session
• Perfect for initialization tasks

4. Multiple Hooks Per Event

• Can stack multiple hooks for the same event
• Run in sequence for chained operations

Advanced Usage

Pattern Matching

You can use patterns in the matcher field:

hooks:
  PreToolUse:
    # Match specific tool
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo 'Bash tool detected'"

    # Match multiple tools with wildcard
    - matcher: "Bash*"
      hooks:
        - type: command
          command: "echo 'Any Bash-related tool'"

    # Match all tools
    - matcher: "*"
      hooks:
        - type: command
          command: "echo 'Any tool'"

Environment Variables

Hooks can access environment variables:

hooks:
  PreToolUse:
    - matcher: "*"
      hooks:
        - type: command
          command: "echo 'Tool: $TOOL_NAME, Input: $TOOL_INPUT'"

Script Hooks

Instead of inline commands, use scripts:

hooks:
  PreToolUse:
    - matcher: "Write"
      hooks:
        - type: script
          command: "scripts/validate_write.sh"

With scripts/validate_write.sh:

#!/bin/bash
echo "Validating write operation..."
echo "Tool: $TOOL_NAME"
echo "Input: $TOOL_INPUT"
# Add validation logic here

Common Use Cases

1. Security Validation

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: script
          command: "scripts/security_check.sh"

2. Audit Logging

hooks:
  PostToolUse:
    - matcher: "*"
      hooks:
        - type: command
          command: "echo '$(date): Tool $TOOL_NAME used' >> audit.log"

3. Resource Cleanup

hooks:
  Stop:
    - matcher: "*"
      hooks:
        - type: script
          command: "scripts/cleanup.sh"

4. Performance Monitoring

hooks:
  PreToolUse:
    - matcher: "*"
      hooks:
        - type: command
          command: "echo $(date +%s%N) > /tmp/start_time"
  PostToolUse:
    - matcher: "*"
      hooks:
        - type: command
          command: |
            START=$(cat /tmp/start_time)
            END=$(date +%s%N)
            echo "Tool execution time: $((($END - $START) / 1000000))ms"

Testing Checklist

Test each hook type:

• PreToolUse fires before Bash
• PreToolUse fires before Write
• PostToolUse fires after Bash
• PostToolUse fires after Write
• Wildcard matcher works for all tools
• once: true prevents repeat execution
• Stop hook fires on skill completion
• Multiple hooks execute in sequence
• Hook failures don't stop main execution

Troubleshooting

Hook Not Firing

Problem: Hook command doesn't execute

Solutions:

1. Check YAML syntax (use spaces, not tabs)
2. Verify matcher pattern matches tool name
3. Ensure command is executable
4. Check hook event type (PreToolUse vs PostToolUse)

Once Flag Not Working

Problem: Hook with once: true keeps running

Solution: The once flag applies per session. Restart the session to test.

Hook Failing Silently

Problem: Hook errors not visible

Solution: Add error handling:

hooks:
  PreToolUse:
    - matcher: "*"
      hooks:
        - type: command
          command: "python scripts/hook.py 2>&1 || echo 'Hook failed'"

Best Practices

DO ✅

1. Use specific matchers when possible
2. Keep hook commands simple and fast
3. Add proper error handling
4. Use scripts for complex logic
5. Test hooks in isolation
6. Log hook execution for debugging

DON'T ❌

1. Don't put long-running commands in hooks
2. Don't use hooks for core logic (use skill execution)
3. Don't forget to make scripts executable
4. Don't assume environment variables exist
5. Don't create circular dependencies with hooks

Summary

This skill demonstrates:

• ✅ PreToolUse hooks for tool preparation
• ✅ PostToolUse hooks for tool completion
• ✅ Stop hooks for cleanup
• ✅ Pattern matching with specific tools
• ✅ Wildcard matching for all tools
• ✅ Once-only execution
• ✅ Multiple hooks per event

Try the tests above to see hooks in action!

---

Version: 1.0.0 Last Updated: 2026-01-10 Maintainer: SDK Team