How to Create Plugin Skills for Specific Development Tasks

Create plugin skills by scaffolding a new plugin with the plugin-creator script, then adding a skill folder containing SKILL.md documentation and an agents/openai.yaml policy file that defines the tool chain and invocation constraints.

The OpenAI Plugins repository provides a modular framework for extending Codex with custom capabilities. Each plugin resides in the plugins/ directory as a self-contained unit that encapsulates one or more skills for specific development tasks. By leveraging the built-in scaffolding tools and following the repository's declarative structure, you can rapidly build reusable skills for workflows like automated code review, CI/CD orchestration, or dependency auditing.

Repository Architecture

The codebase organizes functionality into discrete plugins, each declaring its capabilities through machine-readable manifests and human-readable documentation.

Directory Layout and Key Files

• plugins/ – Top-level folder where each subdirectory represents a distinct plugin (e.g., airtable, zoom).
• .codex-plugin/plugin.json – Plugin manifest defining metadata, version, author, and UI interface schema.
• skills/ – Subfolder within a plugin containing individual skill directories. Each skill is a reusable, LLM-driven unit of work.
• agents/openai.yaml – Policy configuration inside a skill that specifies invocation constraints, tool definitions, and runtime behavior.
• .agents/skills/plugin-creator/ – Helper skill containing scripts to scaffold new plugins and register them in the marketplace.

How a Skill Works

A skill integrates three core components that Codex uses to route and execute requests:

1. SKILL.md – Front-matter documentation describing the skill's purpose, input parameters, and expected outputs. Codex uses this for intent matching.
2. agents/openai.yaml – Machine-readable policy specifying allow_implicit_invocation, tool chains, and execution constraints.
3. Optional scripts/assets – Python scripts, CLI wrappers, or static assets invoked by the tools defined in the YAML policy.

When a user triggers a development task, the LLM matches the request against the SKILL.md description and validates the action against the policy constraints in agents/openai.yaml.

Creating a New Plugin Scaffold

The repository includes a plugin-creator skill that generates the required folder hierarchy, manifest files, and marketplace entries.

Run the scaffold script from the repository root:

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py dev-assistant \
  --with-skills --with-scripts --with-assets --with-marketplace

The script performs the following actions based on the implementation in create_basic_plugin.py:

1. Normalizes the plugin name to kebab-case (dev-assistant).
2. Creates the plugin directory at ~/plugins/dev-assistant/ (or a specified custom path).
3. Writes a plugin manifest (plugin.json) conforming to the schema defined 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).
4. Generates subdirectories for skills/, scripts/, and assets/ when flags are provided.
5. Updates the personal marketplace registry at ~/.agents/plugins/marketplace.json with a pointer to the new plugin path.

Adding a New Skill for a Development Task

After scaffolding the plugin, add a skill by creating a dedicated folder and declaring its interface and policy. The following example implements a code-review skill that analyzes GitHub pull requests.

Step 1: Create the Skill Folder

mkdir -p ~/plugins/dev-assistant/skills/code-review

Step 2: Add SKILL.md Documentation

Create a SKILL.md file that describes the skill's behavior and contract:

---
name: code-review
description: Analyzes a GitHub pull-request diff and returns a concise code-review report.
license: MIT
metadata:
  version: "0.1.0"
  author: dev-assistant
---

# Code Review Skill

Given a PR URL, the skill fetches the diff, runs static analysis, and returns a structured list of:
- Potential bugs
- Style violations
- Suggested refactorings

Save this file to ~/plugins/dev-assistant/skills/code-review/SKILL.md.

Step 3: Define the Agent Policy

Create agents/openai.yaml inside the skill folder to specify invocation rules and available tools:

name: code-review
description: Review a PR and suggest improvements.
policy:
  allow_implicit_invocation: false   # Requires explicit user request

  allow_multiple_invocations: true
tools:
  - name: github_diff_fetcher
    description: Retrieve the diff for a given PR URL.
    type: python
    entrypoint: scripts/fetch_diff.py
  - name: llm_review
    description: Run the LLM over the diff and format suggestions.
    type: llm

Step 4: Implement Helper Scripts

Add supporting scripts referenced in the tool definitions. For the github_diff_fetcher tool, create scripts/fetch_diff.py:

#!/usr/bin/env python3
import sys
import requests
import os

def fetch_diff(pr_url: str) -> str:
    """Fetch raw diff from GitHub API."""
    token = os.getenv("GITHUB_TOKEN")
    headers = {
        "Authorization": f"token {token}",
        "Accept": "application/vnd.github.v3.diff"
    }
    resp = requests.get(pr_url, headers=headers)
    resp.raise_for_status()
    return resp.text

if __name__ == "__main__":
    print(fetch_diff(sys.argv[1]))

Store this file at ~/plugins/dev-assistant/skills/code-review/scripts/fetch_diff.py and mark it executable with chmod +x.

Security note: Never commit secrets to the script; the helper expects GITHUB_TOKEN to be present in the runtime environment.

End-to-End Example

The following bash commands create a complete dev-assistant plugin with a functional code-review skill:

# Scaffold the plugin with all optional components

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py dev-assistant \
  --with-skills --with-scripts --with-assets --with-marketplace

# Create the skill directory and documentation

mkdir -p ~/plugins/dev-assistant/skills/code-review
cat > ~/plugins/dev-assistant/skills/code-review/SKILL.md <<'EOF'
---
name: code-review
description: Analyzes a GitHub PR diff and returns a concise review.
license: MIT
metadata:
  version: "0.1.0"
  author: dev-assistant
---

# Code Review Skill

Analyzes pull request diffs for potential bugs, style issues, and refactoring opportunities.
EOF

# Define the agent policy

cat > ~/plugins/dev-assistant/skills/code-review/agents/openai.yaml <<'EOF'
name: code-review
description: Review a PR and suggest improvements.
policy:
  allow_implicit_invocation: false
  allow_multiple_invocations: true
tools:
  - name: github_diff_fetcher
    description: Retrieve the diff for a given PR URL.
    type: python
    entrypoint: scripts/fetch_diff.py
EOF

# Add the helper script

mkdir -p ~/plugins/dev-assistant/skills/code-review/scripts
cat > ~/plugins/dev-assistant/skills/code-review/scripts/fetch_diff.py <<'EOF'
#!/usr/bin/env python3
import sys, requests, os

def fetch_diff(pr_url: str) -> str:
    token = os.getenv("GITHUB_TOKEN")
    headers = {"Authorization": f"token {token}", "Accept": "application/vnd.github.v3.diff"}
    resp = requests.get(pr_url, headers=headers)
    resp.raise_for_status()
    return resp.text

if __name__ == "__main__":
    print(fetch_diff(sys.argv[1]))
EOF
chmod +x ~/plugins/dev-assistant/skills/code-review/scripts/fetch_diff.py

After execution, the plugin appears in ~/.agents/plugins/marketplace.json. Codex can now invoke the skill explicitly using a prompt such as:

Review this PR: https://github.com/example/repo/pull/42

Key Files Referenced

Understanding these source files is essential when you create plugin skills for specific development tasks:

• [.agents/skills/plugin-creator/scripts/create_basic_plugin.py](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) – CLI tool that generates plugin scaffolding, manifests, and marketplace entries.
• [.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) – Complete JSON schema for plugin.json and marketplace specifications.
• [plugins/airtable/skills/airtable-overview/SKILL.md](https://github.com/openai/plugins/blob/main/plugins/airtable/skills/airtable-overview/SKILL.md) – Reference implementation showing proper front-matter and documentation structure.
• [plugins/zoom/skills/start/agents/openai.yaml](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/start/agents/openai.yaml) – Example policy file demonstrating invocation constraints and tool definitions.
• [.agents/plugins/marketplace.json](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) – Central registry file that aggregates available plugins for the Codex UI.

Summary

• Use the scaffold script at .agents/skills/plugin-creator/scripts/create_basic_plugin.py to generate the plugin folder, manifest, and marketplace entry.
• Create a skill folder under plugins/<name>/skills/<skill-name>/ containing a SKILL.md file that describes the development task and an agents/openai.yaml file that defines the policy.
• Define tools in YAML pointing to executable scripts or LLM invocations, specifying type: python for external scripts or type: llm for model-driven analysis.
• Reference existing examples like the Airtable and Zoom plugins to ensure your skill structure conforms to the expected schema.
• Register via marketplace by ensuring the scaffold updates ~/.agents/plugins/marketplace.json, making the skill discoverable by Codex.

Frequently Asked Questions

What is the minimum file structure needed for a functional skill?

A functional skill requires only two files: SKILL.md for documentation and agents/openai.yaml for policy configuration. The SKILL.md provides the natural language description Codex uses for routing, while agents/openai.yaml specifies whether implicit invocation is allowed and which tools are available. Optional Python scripts or assets inside the skill folder provide runtime functionality but are not required if the skill uses built-in LLM capabilities only.

How do I prevent a skill from being invoked automatically?

Set policy.allow_implicit_invocation: false in your agents/openai.yaml file. According to the schema used in the Zoom plugin examples, this setting forces Codex to wait for an explicit user request rather than auto-triggering the skill when the LLM detects a matching intent. You can also restrict tool usage or set allow_multiple_invocations to control execution scope.

Can I share my plugin with other developers?

Yes. After creating your plugin with the --with-marketplace flag, the scaffold updates your local ~/.agents/plugins/marketplace.json file. To distribute the plugin, commit the entire plugin folder to a Git repository. Other users can clone it and either manually append the path to their marketplace file or run the scaffold script targeting the cloned directory. Ensure all scripts use relative paths and environment variables for secrets rather than hard-coded values.

What is the difference between a plugin and a skill?

A plugin is a top-level container defined by a plugin.json manifest that groups related capabilities. A skill is a discrete, reusable unit of work inside a plugin that handles a specific task. One plugin can contain multiple skills (e.g., a "dev-assistant" plugin might have separate skills for code review, linting, and deployment). The plugin provides shared assets and metadata, while each skill defines its own documentation, policy, and tool chain in its respective skills/<name>/ folder.

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