Hooks in Skills

What the hooks Frontmatter Field Does

The hooks frontmatter field registers Claude Code hooks the moment a skill is invoked. Unlike hooks declared in settings.json — which run for every session unconditionally — skill hooks activate on demand when you invoke the skill, then stay active for the rest of that session.

The configuration format is identical to the Claude Code hooks system, declared inside the skill's YAML frontmatter. Any hook event the hooks system supports can be registered from a skill: file-change events, tool events, session events, and notification events.

Session Scope and the once Option

Once registered, skill hooks persist across all subsequent turns — not just during the skill's own turn. A /tdd skill that registers a FileChanged hook keeps running that hook on every file save for the rest of the session, even as you switch tasks and topics.

The once: true option changes this behavior: the hook runs exactly once, then removes itself. Only a successful run triggers removal — a failed, blocked (exit code 2), or timed-out run leaves the hook in place. This option is honored in skill frontmatter only; it has no effect in settings.json hooks.

Supported Hook Events

Skill hooks can register against any Claude Code hook event. Key events for skill use cases include:

• FileChanged — fires when Claude edits a file during the session. Register linters, test runners, or validators to run automatically on every save.
• PreToolUse / PostToolUse — fires before or after any tool call. Use matchers to scope to specific tools: matcher: "Bash" intercepts only shell commands; matcher: "Edit|Write" intercepts file edits only.
• UserPromptSubmit — fires each time the user submits a prompt. Use it for continuous monitoring or context injection before each response.
• SessionStart / SessionEnd — fires at session boundaries for setup and teardown actions.
• Stop / StopFailure — fires when Claude finishes responding, including on rate-limit and error conditions.

Four Use-Case Patterns

Auto-test on save. Invoke a /tdd skill that registers a hook on on-file-changed. Every file Claude edits for the rest of the session triggers a test run automatically:

---
name: tdd
description: Enable TDD mode — runs npm test on every file save for this session
hooks:
  on-file-changed:
    - run: npm test
      once: false
---

Behavioral enforcement. Invoke a /safe-mode skill that hooks PreToolUse on Bash. A safety-check script runs before every shell command in the session:

---
name: safe-mode
description: Register Bash safety checks for this session
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: ".claude/hooks/safety-check.sh"
---

Continuous monitoring. Invoke a /watch-logs skill that registers a command on UserPromptSubmit to tail error logs and inject context before each response — active throughout the session without further user action.

Post-review formatting. Invoke a /pr-workflow skill that hooks PostToolUse on Bash to auto-format diff output after each git command, producing consistent summaries throughout a review session.

Design Implication: Skills as Session Configuration

A skill with a hooks: block is a session configuration tool, not just an instruction document. Invoking it installs persistent automated behavior that changes what happens on every subsequent turn. Document this in the skill's description so users understand what they are activating. A description like "Enable TDD mode: registers a test-run hook on every file save for this session" signals the behavioral change rather than hiding it.

Hermes Analog

Hermes does not have a hooks frontmatter field. The equivalent is instructed: a skill's procedure can direct the agent to register a session event hook via hermes hooks add. The resulting behavior is similar — a persistent automated action within the session — triggered by the skill's instructions rather than by frontmatter configuration.

Safety Considerations for Community Skills

Session-wide hooks from community skills run until the session ends. They can intercept tool calls, read command output, or execute shell commands with your session's full permissions. Before invoking any community skill with a hooks: block, audit it:

• Read every hook that will be registered and confirm you understand what each does
• Check the matchers — matcher: "*" on PreToolUse intercepts every tool call in your session
• Inspect any commands referenced — they execute on your machine under your account
• Test in an isolated session before adding the skill to your personal library