# What Is the `.agents` Directory in the OpenAI Plugins Repository?

> Discover the purpose of the .agents directory in the OpenAI plugins repository. Learn how it enables personal plugin marketplaces and scaffolding tools for enhanced functionality.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: internals
- Published: 2026-09-11

---

**The `.agents` directory stores user-level configuration and skill definitions that enable personal plugin marketplaces and scaffolding tools, operating independently from the repository’s built-in plugins.**

In the `openai/plugins` repository, the `.agents` folder serves as a dedicated namespace for runtime-specific assets used by Codex, Claude, Gemini, and Copilot. This directory houses the [marketplace.json](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) configuration file and the [plugin-creator](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md) skill template, providing a clean separation between shared code and individual developer customization.

## Core Responsibilities of the `.agents` Directory

### Personal Marketplace Configuration

The primary purpose of [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) is to define a **personal plugin marketplace**. Unlike the repository-wide `plugins/` folder, which contains built-in plugins available to all users, this JSON file lists plugins discoverable only by the local Codex UI and CLI tools. It specifies plugin names, source locations, installation policies, authentication requirements, and categorization metadata, allowing developers to curate a private catalog without modifying version-controlled files.

*Source reference:* [[`.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)

### Skill Scaffolding and Plugin Creation

The `.agents/skills/` subtree contains reusable behavior definitions called **skills**. The most significant is the **plugin-creator** skill located at `.agents/skills/plugin-creator/`. When invoked, this skill generates a complete plugin scaffold—including directory structure, [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifests, and optional subfolders for hooks, assets, and additional skills—while simultaneously registering the new plugin in the personal marketplace file.

*Source reference:* [[`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md)](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md)

### Runtime-Agnostic Asset Storage

Multiple AI runtimes treat `.agents` as a canonical alias for user-level assets. When Codex, Claude, Gemini, or Copilot resolve paths like `~/.agents/skills/...`, they point to this directory regardless of the operating environment. This standardization ensures consistent skill discovery and marketplace behavior across different tools while keeping personal configuration isolated from repository state.

## Key Files Inside `.agents`

| File | Purpose | Link |
|------|---------|------|
| [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) | Personal marketplace metadata listing privately configured plugins | [View on GitHub](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) |
| [`.agents/skills/plugin-creator/SKILL.md`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md) | Documentation for the scaffolding skill, including naming conventions and marketplace integration | [View on GitHub](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/SKILL.md) |
| [`.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) | Python script implementing the scaffold generation logic | [View on GitHub](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) |
| [`plugins/plugin-eval/README.md`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md) | Demonstrates interaction between workspace-specific `.agents` paths and the global marketplace | [View on GitHub](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md) |

## Practical Usage Examples

### Adding a New Plugin to the Personal Marketplace

The following command invokes the plugin-creator skill to scaffold a new plugin and automatically update the local marketplace configuration:

```bash

# From the repository root

python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py my-awesome-plugin \
  --with-marketplace

```

This script writes a new entry into [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) containing the proper `source.path`, `policy`, and `category` fields required for Codex UI discovery.

### Accessing the Personal Marketplace from a Runtime

Python-based runtimes can load the personal marketplace directly from the home directory alias:

```python
import json
import pathlib

# Resolve the personal marketplace path

marketplace_path = pathlib.Path.home() / ".agents" / "plugins" / "marketplace.json"
marketplace = json.loads(marketplace_path.read_text())

# Locate a specific plugin entry

plugin = next(p for p in marketplace["plugins"] if p["name"] == "my-awesome-plugin")
print(plugin["source"]["path"])   # Output: "./plugins/my-awesome-plugin"

```

This demonstrates how the `.agents` directory serves as a consistent configuration layer across different execution environments.

### Creating a Full Plugin Scaffold

To generate a comprehensive plugin structure with optional assets, hooks, and nested skills:

```bash
python3 .agents/skills/plugin-creator/scripts/create_basic_plugin.py \
  my-tool \
  --path ./plugins \
  --marketplace-path ./.agents/plugins/marketplace.json \
  --with-skills --with-hooks --with-assets --with-marketplace

```

This command populates `skills/`, `hooks/`, and `assets/` directories while ensuring the plugin appears immediately in the personal marketplace at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json).

## Summary

- **The `.agents` directory** isolates personal plugin configuration from shared repository code, residing at the intersection of user preferences and runtime requirements.
- **[`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)** functions as a private plugin catalog, distinct from the public `plugins/` folder.
- **The plugin-creator skill** uses `.agents/skills/` to provide scaffolding utilities that automatically register new plugins in the personal marketplace.
- **Cross-runtime compatibility** is achieved through standardized path resolution (e.g., `~/.agents/...`), enabling consistent behavior across Codex, Claude, Gemini, and Copilot environments.

## Frequently Asked Questions

### What is the difference between `plugins/` and `.agents/plugins/`?

The `plugins/` folder at the repository root contains built-in plugins available to all users of the codebase, while `.agents/plugins/` stores **personal** marketplace metadata specific to the local user. The `.agents` version is ignored by version control and used exclusively by the local Codex runtime to discover additional plugins not present in the shared repository.

### How does the plugin-creator skill modify the `.agents` directory?

When executed, the [create_basic_plugin.py](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/scripts/create_basic_plugin.py) script updates [[`.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) by appending a JSON object containing the new plugin's metadata. This registration enables immediate discovery by the Codex UI without requiring manual file editing.

### Can multiple AI runtimes share the same `.agents` configuration?

Yes. Codex, Claude, Gemini, and Copilot all resolve the `.agents` path as a canonical alias for user-level assets (typically mapped to `~/.agents/` in the local filesystem). This shared namespace ensures that skills and marketplace definitions remain consistent regardless of which runtime is executing the code.

### Where does the `.agents` directory reside in a local environment?

While the repository contains a `.agents` folder at the root for template purposes, runtimes typically resolve `.agents` paths to the user's home directory (`~/.agents/`). This allows personal plugins and skills to persist across different workspace clones while the repository copy serves as default scaffolding.