# How to Create Plugin Skills for Specific Development Tasks

> Learn how to create plugin skills for specific development tasks by scaffolding with plugin-creator, defining SKILL.md documentation, and configuring openai.yaml policies for toolchain and constraints.

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

---

**Create plugin skills by scaffolding a new plugin with the `plugin-creator` script, then adding a skill folder containing [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) documentation and an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) description and validates the action against the policy constraints in [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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:

```bash
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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)](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

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

```

### Step 2: Add SKILL.md Documentation

Create a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file that describes the skill's behavior and contract:

```markdown
---
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`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) inside the skill folder to specify invocation rules and available tools:

```yaml
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`](https://github.com/openai/plugins/blob/main/scripts/fetch_diff.py):

```python
#!/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:

```bash

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

```text
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)](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)](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md)** – Complete JSON schema for [`plugin.json`](https://github.com/openai/plugins/blob/main/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)](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)](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)](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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/SKILL.md) file that describes the development task and an [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) for documentation and [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) for policy configuration. The [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) provides the natural language description Codex uses for routing, while [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.