How to Create Netlify Deployment Plugin Configurations in the OpenAI Plugins Repository

To configure a Netlify deployment plugin in the openai/plugins repository, you define a plugin manifest in plugins/netlify/.codex-plugin/plugin.json, implement reusable skills under plugins/netlify/skills/, and supply a netlify.toml configuration that the netlify-deploy skill consumes to drive the Netlify CLI.

The openai/plugins repository ships with a self-contained Netlify plugin that bundles everything needed to deploy web projects from a conversational interface. Mastering these Netlify deployment plugin configurations lets the OpenAI Codex runtime authenticate with Netlify, resolve build commands, and publish to preview or production environments. All configuration is rooted in the plugins/netlify/ directory and is composed of three core layers: a plugin manifest, a skill set, and a site-level netlify.toml file.

Plugin Architecture and Key Files

The Netlify plugin is organized into a declarative manifest, discrete skills, and static assets. According to the openai/plugins source code, the following files control every aspect of the deployment lifecycle:

• plugins/netlify/.codex-plugin/plugin.json — Declares the plugin name, version, and skill directory.
• plugins/netlify/skills/netlify-deploy/SKILL.md — Implements the end-to-end deployment flow using the Netlify CLI.
• plugins/netlify/skills/netlify-config/SKILL.md — Documents the netlify.toml schema for builds, redirects, headers, and environment variables.
• plugins/netlify/skills/netlify-image-cdn/SKILL.md — (Optional) Configures transformed image delivery.
• plugins/netlify/skills/netlify-forms/SKILL.md — (Optional) Guides Netlify Forms integration.
• plugins/netlify/assets/app-icon.png — Icon asset rendered in the plugin UI.

When a user invokes the plugin, the runtime reads the manifest, loads the requested skill, and executes the steps defined in the corresponding SKILL.md.

Configuring the Plugin Manifest

Every Codex plugin must declare its identity and capabilities. In plugins/netlify/.codex-plugin/plugin.json, the manifest points the runtime to the ./skills/ folder and sets metadata such as category and supported capabilities.

{
  "name": "netlify",
  "version": "1.1.1",
  "description": "Deploy projects and manage preview or production releases on Netlify.",
  "skills": "./skills/",
  "interface": {
    "displayName": "Netlify",
    "shortDescription": "Deploy projects and manage releases",
    "category": "Developer Tools",
    "capabilities": ["Interactive", "Write"],
    "websiteURL": "https://www.netlify.com"
  }
}

This manifest is the entry point the Codex runtime uses to discover and register the plugin.

Structuring Skills for Deployment

Skills are reusable capabilities stored in plugins/netlify/skills/. For deployment scenarios, the primary skill is netlify-deploy, which encodes the exact CLI workflow required to push a site live.

Authentication

The skill first runs npx netlify status to verify an existing session. If the user is not authenticated, the skill prompts for npx netlify login or the presence of a NETLIFY_AUTH_TOKEN environment variable.

Site Linking

Next, the skill checks whether the current repository is linked to a Netlify site. If no link exists, it attempts npx netlify link using the Git remote URL, or falls back to npx netlify init to create a new site.

Dependency Installation

Before building, the skill detects the active package manager—npm, yarn, or pnpm—and runs the appropriate install command to ensure dependencies are present.

Deploy Execution

The skill invokes npx netlify deploy for a preview deployment, or npx netlify deploy --prod for production. The Netlify CLI resolves the build command and publish directory from netlify.toml.

Result Reporting

After deployment, the skill returns the preview URL, the production URL (when applicable), and a direct link to the Netlify dashboard.

These steps are defined in plugins/netlify/skills/netlify-deploy/SKILL.md.

Site Configuration with netlify.toml

The netlify-config skill treats netlify.toml as the single source of truth for site-level behavior. You should place this file at the repository root—or at the relevant monorepo sub-path—so the CLI can read it during deploy.

[build]
  base    = "src"
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/old-path"
  to   = "/new-path"
  status = 301

[images]
  remote_images = ["https://cdn.example.com/.*"]

This sample, drawn from plugins/netlify/skills/netlify-config/SKILL.md, demonstrates build settings, path redirects, and Image CDN allowlists.

Practical Deployment Workflow

When invoked, the netlify-deploy skill executes a deterministic sequence of shell commands. You can reproduce this workflow locally or embed it in custom automation:

# Verify authentication

npx netlify status || npx netlify login

# Link site if not already linked

git remote show origin
npx netlify link --git-remote-url https://github.com/your/repo

# Install dependencies

npm install   # or yarn / pnpm

# Preview deploy

npx netlify deploy

# Production deploy

npx netlify deploy --prod

Each command is executed in the context of the directory containing netlify.toml.

Optional Skills and Extensions

Beyond core deployment, the Netlify plugin provides auxiliary skills for specialized features.

Image CDN

The netlify-image-cdn skill, documented in plugins/netlify/skills/netlify-image-cdn/SKILL.md, enables on-the-fly image transformations via a query-string API:

<img src="/.netlify/images?url=/uploads/photo.jpg&w=800&h=600&fit=cover&q=80" />

Netlify Forms

The netlify-forms skill in plugins/netlify/skills/netlify-forms/SKILL.md guides you through adding form handling to a static site without a separate backend.

Summary

• Plugin manifest: Create plugins/netlify/.codex-plugin/plugin.json to register the plugin and point to ./skills/.
• Primary skill: The netlify-deploy skill handles authentication, site linking, dependency installation, and CLI-based deploys.
• Site config: Use netlify.toml at the repo root to define builds, redirects, headers, and environment variables as documented in the netlify-config skill.
• CLI flow: The skill runs npx netlify status, npx netlify link, installs dependencies, then calls npx netlify deploy or npx netlify deploy --prod.
• Optional capabilities: Extend the plugin with netlify-image-cdn and netlify-forms for image optimization and form handling.

Frequently Asked Questions

Where is the Netlify plugin manifest located in the openai/plugins repository?

The manifest is located at plugins/netlify/.codex-plugin/plugin.json. This file declares the plugin name, version, skill path, and interface metadata required for the OpenAI Codex runtime to load the plugin.

How does the netlify-deploy skill authenticate with Netlify?

The skill begins by running npx netlify status. If no active session is found, it instructs the user to run npx netlify login or to export a NETLIFY_AUTH_TOKEN environment variable. This ensures every subsequent CLI command executes with valid credentials.

Can I use this plugin for both preview and production deployments?

Yes. The netlify-deploy skill runs npx netlify deploy to generate a preview URL, and it runs npx netlify deploy --prod when a production release is requested. The build context and publish directory are always read from netlify.toml.

What optional skills are available in the Netlify plugin?

The plugin includes netlify-image-cdn for transformed image delivery and netlify-forms for managed form handling. Each skill is documented in its respective SKILL.md under plugins/netlify/skills/.

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