Hooks in skills and agents

In addition to settings files and plugins, hooks can be defined directly in skills and subagents using frontmatter, in the same configuration format as settings-based hooks. How long Claude Code keeps them registered depends on the component:

• Subagent hooks: Claude Code runs them only while that subagent is running and removes them when it finishes. Claude Code converts a Stop hook here to SubagentStop, the event it fires when a subagent completes.
• Skill hooks: Claude Code registers them when you or Claude invoke the skill and keeps running them for the rest of the session, on turns after the skill's own turn as well. To have Claude Code remove a hook after its first successful run instead, set once: true on it.

This skill defines a PreToolUse hook that runs a security validation script before each Bash command:

---
name: secure-operations
description: Perform operations with security checks
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Subagents use the same format in their YAML frontmatter.

Frontmatter hooks in a project skill follow the same workspace trust rule as hooks in settings files. Claude Code registers them when you or Claude invoke the skill, including in a -p run in a folder you haven't trusted.

Frontmatter hooks in a project subagent run only after you accept the workspace trust dialog for the folder the agent file came from. A -p session doesn't count as accepting it. What runs before you trust a folder compares this with the settings-file rule, and the subagents page lists which scopes are exempt. Before v2.1.218, these hooks could run from folders you hadn't trusted.