# How hooks.json Influences Skill Execution Flow in OpenAI Plugins

> Learn how hooks.json intercepts runtime events and executes shell commands to inject validation and cleanup logic into OpenAI plugin skill execution. Enhance your plugin's workflow.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: internals
- Published: 2026-06-11

---

**Hooks defined in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) intercept specific runtime events—such as `PostToolUse`—and execute shell commands or scripts when pattern matchers succeed, allowing plugins to inject validation, cleanup, or side-effect logic without modifying core skill code.**

The openai/plugins repository implements a declarative hook system that extends skill behavior through external configuration. By referencing a [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file from the plugin's [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest, developers can register event-driven callbacks that the Codex runtime evaluates after tool execution, augmenting the standard skill flow with custom validation or cleanup routines.

## Hook Configuration Structure

Each plugin declares its hook configuration in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) via the `"hooks"` field, which points to a [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file relative to the plugin root. According to the plugin manifest specification in [`plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/plugin-json-spec.md), this field enables the runtime to locate and load event hooks before skill execution begins.

The [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file defines event-to-action mappings under a top-level `"hooks"` object. Each key represents a runtime event—such as `PostToolUse`—that triggers when specific conditions occur during skill execution. The configuration from [`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json) demonstrates this structure:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/post_write_figma_parity_check.sh"
          }
        ]
      }
    ]
  }
}

```

**Key components include:**
- **Event name** – The trigger identifier (e.g., `PostToolUse`) that fires after tool execution completes.
- **Matcher** – A regex-compatible pattern that filters which tool operations activate the hook. The Figma example uses `"Write|Edit"` to match any tool name containing either substring.
- **Hook actions** – An ordered array of operations, typically `"command"` types that execute shell scripts relative to the plugin directory.

## Event Model and Matcher Mechanism

The hook system operates on an event-driven model where the runtime emits structured events at specific execution milestones. The `PostToolUse` event fires immediately after a tool completes its primary operation, passing metadata including the tool name and execution results to the hook evaluator.

When processing `PostToolUse`, the runtime iterates through all entries in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) for that event. For each entry, it evaluates the `"matcher"` field as a regular expression against the tool identifier. If the pattern matches, the runtime executes every hook action defined in the entry's `"hooks"` array sequentially. This matcher mechanism allows fine-grained control over when auxiliary scripts run, ensuring validation logic only triggers for relevant operations like write or delete commands.

## Execution Flow: From Tool Call to Hook Processing

The integration of [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) into skill execution follows a specific lifecycle that maintains separation between core skill logic and auxiliary operations:

1. **Skill Initialization** – The user invokes a skill (e.g., `use_figma`), and the runtime loads the plugin's [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) to locate [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json).

2. **Tool Execution** – The skill executes a tool call (e.g., `figma.write`), which performs the primary API operation against the external service.

3. **Event Emission** – Upon tool completion, the runtime emits the `PostToolUse` event, attaching the tool name (`figma.write`) and result metadata.

4. **Hook Evaluation** – The runtime reads [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) and checks each `PostToolUse` entry's `"matcher"` against the tool name. For the Figma plugin, the pattern `"Write|Edit"` matches `figma.write`.

5. **Command Execution** – When matchers succeed, the runtime executes the specified commands in order. In [`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json), this triggers [`./scripts/post_write_figma_parity_check.sh`](https://github.com/openai/plugins/blob/main/./scripts/post_write_figma_parity_check.sh) with relevant context.

6. **Flow Continuation** – After all matching hooks complete, the runtime returns control to the skill, which continues with its next operation or completes execution.

This architecture ensures hooks **augment** rather than disrupt the skill flow, running validation or cleanup scripts asynchronously without blocking the primary tool response.

## Practical Implementation: The Figma Plugin Example

The Figma plugin demonstrates production-ready hook implementation for data consistency validation. Located at [`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json), this configuration automatically runs parity checks after any write or edit operation:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/post_write_figma_parity_check.sh"
          }
        ]
      }
    ]
  }
}

```

The referenced script [`post_write_figma_parity_check.sh`](https://github.com/openai/plugins/blob/main/post_write_figma_parity_check.sh) receives the file ID as an argument and performs validation:

```bash
#!/usr/bin/env bash

# Called after Figma Write/Edit operations complete

FILE_ID="$1"
echo "Running parity check for file $FILE_ID"

# API validation and hash comparison logic here

```

When a user runs a skill that triggers `figma.write`, the runtime automatically invokes this script after the API call succeeds, verifying design file integrity without requiring the skill author to embed validation logic directly in the skill definition.

## Creating Custom Hooks

To implement custom hooks for your plugin, first ensure [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) references your hooks file:

```json
{
  "hooks": "./hooks.json"
}

```

Then define event handlers in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json). For example, to run cleanup after deletion operations:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Delete",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/post_delete_cleanup.sh"
          }
        ]
      }
    ]
  }
}

```

Create the corresponding script at [`./scripts/post_delete_cleanup.sh`](https://github.com/openai/plugins/blob/main/./scripts/post_delete_cleanup.sh):

```bash
#!/usr/bin/env bash
RESOURCE_ID="$1"
echo "Cleaning up resources after deletion of $RESOURCE_ID"

# Custom cleanup implementation

```

The runtime now automatically executes this cleanup script whenever a tool with "Delete" in its name completes execution, maintaining resource consistency across your plugin's operation set.

## Summary

- **[`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json)** is declared in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) via the `"hooks"` field, establishing the hook configuration path for the runtime to load.
- **Event-driven execution** occurs when the runtime emits events like `PostToolUse` after tool completion, triggering hook evaluation.
- **Pattern matching** via regex `"matcher"` fields ensures hooks only execute for specific tool operations (e.g., `"Write|Edit"`).
- **Command execution** runs shell scripts relative to the plugin root, enabling validation, cleanup, and side-effect operations without modifying skill code.
- **Augmented flow** allows plugins to intercept the standard skill execution flow to enforce data consistency and resource management.

## Frequently Asked Questions

### How does the runtime know which hooks.json to load?

The runtime locates [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) through the `"hooks"` field specified in the plugin's [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest file. According to the plugin specification in [`plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/plugin-json-spec.md), this field accepts a relative path from the plugin root to the hook configuration file. When the skill initializes, the runtime parses this manifest and loads the referenced configuration into memory before executing any tool calls.

### What happens if multiple hooks match the same tool operation?

When multiple entries in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) contain matchers that match the same tool name, the runtime executes each matching hook sequentially in the order they appear in the configuration array. For the `PostToolUse` event, every matching entry's `"hooks"` array runs to completion before the skill resumes execution. This allows plugins to chain validation, logging, and cleanup operations for specific tool categories.

### Can hooks modify the return value of a tool operation?

While hooks can process tool output and perform side effects such as logging or validation, they typically run as auxiliary commands that do not directly modify the tool's return value passed back to the skill. The runtime executes hooks after the tool completes but before finalizing the skill step, meaning hooks can signal errors or halt execution, but the primary response data flows through the standard skill execution path unless the hook explicitly modifies shared state or files.

### Where can I find the official specification for hooks.json configuration?

The official plugin manifest specification resides in [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) within the openai/plugins repository. This document defines the schema for the `"hooks"` field in [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) and the structure of event mappings in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json). Additionally, the Figma plugin at [`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json) provides a concrete reference implementation of the `PostToolUse` event with regex matchers and command execution.