Hooks Frontmatter Schema for SKILL.md Files

Hooks Frontmatter Schema for SKILL.md Files

Version: 5.0.0 Last Updated: 2026-01-24

This document defines the hooks frontmatter schema for sf-skills SKILL.md files. Starting with v5.0.0, hooks are defined directly in each skill's SKILL.md frontmatter instead of separate hooks/hooks.json files.

Quick Reference

---
name: sf-apex
description: >
  Your skill description here
license: MIT
metadata:
  version: "1.0.0"
  author: "Author Name"
hooks:
  SessionStart:
    - type: command
      command: "${SHARED_HOOKS}/check-env-weekly.sh"
      timeout: 5000
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "${SHARED_HOOKS}/scripts/guardrails.py"
          timeout: 5000
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "${SKILL_HOOKS}/apex-lsp-validate.py"
          timeout: 15000
---

Hook Event Types

Path Variables

These variables are resolved at runtime:

Hook Structure

Basic Hook (No Matcher)

For events that don't need tool matching (SessionStart):

hooks:
  SessionStart:
    - type: command
      command: "${SHARED_HOOKS}/check-env-weekly.sh"
      timeout: 5000

Matcher-Based Hook

For tool-specific events (PreToolUse, PostToolUse):

hooks:
  PostToolUse:
    - matcher: "Write|Edit"  # Regex pattern for tool names
      hooks:
        - type: command
          command: "python3 ${SKILL_HOOKS}/validate.py"
          timeout: 15000
    - matcher: "Bash"
      hooks:
        - type: command
          command: "python3 ${SKILL_HOOKS}/parse-output.py"
          timeout: 30000

Hook Configuration Fields

Common Hook Patterns

1. Environment Validation (SessionStart)

hooks:
  SessionStart:
    - type: command
      command: "${SHARED_HOOKS}/check-env-weekly.sh"
      timeout: 5000

2. PreToolUse Guardrails

hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "python3 ${SHARED_HOOKS}/scripts/guardrails.py"
          timeout: 5000

3. Code Validation (PostToolUse)

hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "python3 ${SKILL_HOOKS}/apex-lsp-validate.py"
          timeout: 15000
        - type: command
          command: "python3 ${SKILL_HOOKS}/post-tool-validate.py"
          timeout: 120000

4. Test/Build Output Parsing (PostToolUse on Bash)

hooks:
  PostToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "python3 ${SKILL_HOOKS}/parse-test-results.py"
          timeout: 30000

Complete Example: sf-apex

---
name: sf-apex
description: >
  Generates and reviews Salesforce Apex code with 2025 best practices and 150-point
  scoring. Use when writing Apex classes, triggers, test classes, batch jobs, or
  reviewing existing Apex code for bulkification, security, and SOLID principles.
license: MIT
metadata:
  version: "1.0.0"
  author: "Jag Valaiyapathy"
  scoring: "150 points across 8 categories"
hooks:
  SessionStart:
    - type: command
      command: "${SHARED_HOOKS}/check-env-weekly.sh"
      timeout: 5000
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "python3 ${SHARED_HOOKS}/scripts/guardrails.py"
          timeout: 5000
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "python3 ${SKILL_HOOKS}/apex-lsp-validate.py"
          timeout: 15000
        - type: command
          command: "python3 ${SKILL_HOOKS}/post-tool-validate.py"
          timeout: 120000
---

Hook Output Formats

PreToolUse Output (Block/Allow/Modify)

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "DELETE without WHERE detected",
    "updatedInput": {
      "command": "sf data query --query 'SELECT Id FROM Account LIMIT 200'"
    },
    "additionalContext": "Warning message for user"
  }
}

PostToolUse Output (Context Injection)

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Validation passed. Next: /sf-testing"
  }
}

PermissionRequest Output (Auto-Approval)

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "autoApprove": true,
    "reason": "Safe read-only operation"
  }
}

Migration from hooks/hooks.json

Before (hooks/hooks.json):

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "command",
        "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.py"
      }]
    }]
  }
}

After (SKILL.md frontmatter):

---
name: my-skill
hooks:
  PostToolUse:
    - matcher: Write
      hooks:
        - type: command
          command: "python3 ${SKILL_HOOKS}/validate.py"
          timeout: 15000
---

Migration Steps

1. Open skill's hooks/hooks.json
2. Copy hook configuration
3. Convert JSON to YAML format
4. Add to SKILL.md frontmatter under hooks: key
5. Update path variables (${CLAUDE_PLUGIN_ROOT} → ${SKILL_HOOKS})
6. Delete hooks/hooks.json file (keep hooks/scripts/ directory)

Troubleshooting

Hook Not Firing

1. Check YAML syntax (use a YAML validator)
2. Verify path variables resolve correctly
3. Check timeout isn't too short
4. Ensure script is executable (chmod +x script.py)

Hook Failing Silently

1. Add debug output to script (print("DEBUG: ...", file=sys.stderr))
2. Check /tmp/sf-skills-*.log for errors
3. Test script manually: echo '{}' | python3 script.py

Path Resolution Issues

1. Use absolute paths for debugging
2. Check ${SHARED_HOOKS} resolves to: ~/.claude/plugins/marketplaces/sf-skills/shared/hooks
3. Check ${SKILL_HOOKS} resolves to: ~/.claude/plugins/marketplaces/sf-skills/<skill>/hooks/scripts

Best Practices

1. Keep timeouts reasonable: 5s for simple checks, 15-30s for validation, 120s max for complex operations
2. Fail gracefully: Hooks should never break the user experience - exit 0 on errors
3. Use shared hooks: For common patterns, use ${SHARED_HOOKS} scripts
4. Order matters: Hooks execute in order - put fast checks first
5. Cache when possible: Registry loading, file parsing - cache to reduce latency
6. Provide context: Output helpful messages, not just pass/fail

Related Documentation

• skills-registry.json - Skill registry and metadata
• shared/hooks/README.md - Shared hooks documentation
• Claude Code Hooks - Official hooks reference