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

Configure plugin commands by creating Markdown definition files in plugins/<plugin-name>/commands/ and automate post-execution workflows by registering matchers in 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 defines the /implement-from-figma endpoint that the Figma plugin exposes.

Hook Registration Points

The 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:

# /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. 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":

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

This pattern appears in plugins/figma/hooks.json, where the matcher fires after commands like those defined in 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 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, when a user runs a command matching the "Write|Edit" pattern—such as the workflow defined in plugins/figma/commands/implement-from-figma.md—the runtime automatically executes ./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:

#!/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 – The hook registry that defines PostToolUse matchers and associated scripts for the Figma plugin.
• plugins/figma/commands/implement-from-figma.md – An example command definition that triggers the "Write|Edit" matcher.
• plugins/figma/commands/review-design-parity.md – Another command definition demonstrating the Markdown structure.
• plugins/figma/.app.json – The app-level manifest linking the plugin to the underlying Figma integration.
• 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 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 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 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 using relative paths like ./scripts/post_write_figma_parity_check.sh. Ensure scripts have executable permissions before deployment.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}