# How to Configure Plugin Commands and hooks.json in OpenAI Plugins

> Configure OpenAI plugin commands using Markdown and automate workflows with hooks.json. Learn to register matchers and trigger scripts for specific command patterns in your plugins.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-07

---

**Configure plugin commands by creating Markdown definition files in `plugins/<plugin-name>/commands/` and automate post-execution workflows by registering matchers in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) that trigger scripts when specific command patterns are matched.**

The openai/plugins repository powers custom Codex workflows through a declarative command system. To configure plugin commands and hooks.json effectively, you must understand how Markdown command definitions drive the runtime and how the JSON hook registry extends functionality without modifying core logic.

## Command Definition Files

Each plugin command lives as a **Markdown file** inside `plugins/<plugin-name>/commands/`. The filename (minus the `.md` extension) becomes the URL path that the Codex runtime invokes.

A command definition describes the endpoint, expected arguments, and execution workflow. For example, [`plugins/figma/commands/implement-from-figma.md`](https://github.com/openai/plugins/blob/main/plugins/figma/commands/implement-from-figma.md) defines the `/implement-from-figma` endpoint that the Figma plugin exposes.

## Hook Registration Points

The [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file tells the runtime **when** to run auxiliary scripts after a command finishes. It is a simple JSON object whose top-level keys represent hook points like `PostToolUse`.

Each hook entry contains:
- A `matcher` field that selects commands using string literals or regex patterns
- A `hooks` array specifying the hook type (`command`, `http`, etc.) and the concrete script to run

## Creating a New Plugin Command

To add a command, create a Markdown file in your plugin's commands directory:

```markdown

# /my-new-task

Do something useful with the plugin.

## Arguments

- `param1`: description (required)

## Workflow

1. Call the appropriate tool.
2. Return the result.

```

Save this file as [`plugins/figma/commands/my-new-task.md`](https://github.com/openai/plugins/blob/main/plugins/figma/commands/my-new-task.md). The runtime automatically exposes the `/my-new-task` endpoint based on the filename.

## Configuring hooks.json for Post-Execution Automation

Edit `plugins/<plugin-name>/hooks.json` to register actions that run after command completion. The following configuration triggers a parity check script after any command whose name contains "Write" or "Edit":

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

```

This pattern appears in [`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json), where the matcher fires after commands like those defined in [`plugins/figma/commands/implement-from-figma.md`](https://github.com/openai/plugins/blob/main/plugins/figma/commands/implement-from-figma.md) finish execution.

## Execution Flow and Lifecycle

The runtime processes commands and hooks in a strict sequence:

1. The user triggers a command via the chat interface.
2. Codex loads the command definition from the Markdown file and validates its arguments.
3. The runtime executes the associated skill workflow defined in the file.
4. After the skill finishes, the system checks [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) for the `PostToolUse` hook point.
5. If a `matcher` matches the command name, the listed hooks execute in order.

## Real-World Example: Figma Post-Write Parity Checks

The Figma plugin demonstrates practical hook usage. According to the source in [`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json), when a user runs a command matching the "Write|Edit" pattern—such as the workflow defined in [`plugins/figma/commands/implement-from-figma.md`](https://github.com/openai/plugins/blob/main/plugins/figma/commands/implement-from-figma.md)—the runtime automatically executes [`./scripts/post_write_figma_parity_check.sh`](https://github.com/openai/plugins/blob/main/./scripts/post_write_figma_parity_check.sh).

You can implement similar post-processing by placing shell scripts in your plugin's `scripts/` directory and referencing them in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json):

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

# Example post-processing script for the Figma plugin

echo "Running post-processing for my-new-task..."

# Insert custom logic here, e.g., validate output, generate a report, etc.

```

Ensure the script is executable with `chmod +x scripts/post_write_figma_parity_check.sh`.

## Key Files in the Repository

Understanding the plugin structure requires familiarity with these specific paths:

- **[`plugins/figma/hooks.json`](https://github.com/openai/plugins/blob/main/plugins/figma/hooks.json)** – The hook registry that defines `PostToolUse` matchers and associated scripts for the Figma plugin.
- **[`plugins/figma/commands/implement-from-figma.md`](https://github.com/openai/plugins/blob/main/plugins/figma/commands/implement-from-figma.md)** – An example command definition that triggers the "Write|Edit" matcher.
- **[`plugins/figma/commands/review-design-parity.md`](https://github.com/openai/plugins/blob/main/plugins/figma/commands/review-design-parity.md)** – Another command definition demonstrating the Markdown structure.
- **[`plugins/figma/.app.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.app.json)** – The app-level manifest linking the plugin to the underlying Figma integration.
- **[`plugins/figma/README.md`](https://github.com/openai/plugins/blob/main/plugins/figma/README.md)** – Documentation covering where commands and hooks reside within the plugin directory.

## Summary

- **Command definitions** are Markdown files stored in `plugins/<plugin-name>/commands/` that describe endpoints, arguments, and workflows.
- **Hook registration** occurs in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) using matchers that filter commands by name or regex pattern.
- **PostToolUse** hooks execute after command completion, enabling post-processing without modifying core command logic.
- The **Figma plugin** provides a production example of parity checking through `PostToolUse` matchers that target "Write|Edit" command patterns.

## Frequently Asked Questions

### What file format does the OpenAI Plugins repository use for command definitions?

The repository uses **Markdown files** for command definitions. Each file resides in `plugins/<plugin-name>/commands/` and contains sections for Arguments and Workflow. The filename (without `.md`) becomes the command's URL path that Codex can invoke.

### How does hooks.json match specific commands?

The `matcher` field in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) supports string literals and regex patterns. When a command finishes, the runtime evaluates the `PostToolUse` hook entries and executes any hooks whose `matcher` pattern matches the command name that was just executed.

### Can multiple hooks run after a single command?

Yes. The `hooks` array in each [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) entry can contain multiple hook objects. When a matcher succeeds, the runtime executes each listed hook in the order they appear in the array, allowing chained post-processing workflows.

### Where should hook scripts be stored within a plugin directory?

Hook scripts should be stored in a `scripts/` subdirectory within the plugin folder, such as `plugins/figma/scripts/`. Reference these scripts in [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) using relative paths like [`./scripts/post_write_figma_parity_check.sh`](https://github.com/openai/plugins/blob/main/./scripts/post_write_figma_parity_check.sh). Ensure scripts have executable permissions before deployment.