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

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 configuration file and the plugin-creator 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 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)

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 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)

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	Personal marketplace metadata listing privately configured plugins	View on GitHub
.agents/skills/plugin-creator/SKILL.md	Documentation for the scaffolding skill, including naming conventions and marketplace integration	View on GitHub
.agents/skills/plugin-creator/scripts/create_basic_plugin.py	Python script implementing the scaffold generation logic	View on GitHub
plugins/plugin-eval/README.md	Demonstrates interaction between workspace-specific .agents paths and the global marketplace	View on GitHub

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:

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

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:

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.

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 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 script updates [.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.

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