What is a plugin? One installable unit of agent setup

Overview

A plugin is a unit of distribution that bundles extensions for an AI coding agent — custom commands, agent definitions, skills, hooks, and MCP configuration — into a single installable package. Instead of copying individual configuration files between machines, a team member installs the plugin once and gets the same working setup. The mechanism is not specific to one product. This page treats the plugin as a general pattern — packaging and distributing agent extensions — and shows each tool’s concrete directory layout in Core components. The scope of a plugin is packaging and distribution. What each bundled extension does is covered on its own page: Skills for reusable workflow units and MCP for connecting agents to external systems. This page explains why plugins matter, what a plugin consists of, how to roll one out, and what to consider when operating plugins as a team.

Why plugins matter

Agent configuration tends to stay personal. Custom commands, skills, and MCP settings accumulate on each developer’s machine, and a workflow that works well for one person is never shared with other developers’ machines. With documentation-based sharing — “copy these files into your settings” — each copy is edited independently, and the versions quietly diverge. A plugin turns that personal setup into a managed artifact with a name, a version, and a distribution channel. The gains show up in three places:

Standardization. Everyone who installs the plugin runs the same commands, the same review procedures, and the same conventions, so the practice itself — not just the code — becomes shared across the team.
One-step onboarding. A new member installs one plugin instead of assembling settings file by file, and reaches the team’s standard environment on day one.
Maintainable updates. Improvements are made once, in the plugin repository, and reach every installation through an update — instead of being re-announced and re-copied by hand.

Core components

A plugin is a directory containing a manifest and any combination of five extension types. None of them is mandatory — a plugin can ship a single command — but the value grows when the extensions that make up one workflow travel together.

Component	Role
Custom commands	Named entry points the user invokes explicitly (slash commands). Package the team’s routine requests in a fixed form.
Agents	Definitions of sub-agents with their own instructions and tool scopes, used for role-specific work such as reviewing or exploring.
Skills	Reusable workflow units the agent loads on demand. The structure and design principles are covered in Skills.
Hooks	Scripts that run automatically at fixed lifecycle events, such as before a tool call or after an edit, to enforce checks and conventions.
MCP configuration	Pre-configured connections to MCP servers, so installing the plugin also connects the external systems the workflow needs. The protocol is covered in MCP.

The concrete layout differs by tool, but the shape is the same everywhere: a manifest that identifies the plugin, plus files and directories for the bundled extensions. The repository that hosts the plugins additionally holds a catalog file (marketplace.json), whose contents are covered in the Marketplace section below.

dev-plugins/                   # Marketplace repository
├── .claude-plugin/
│   └── marketplace.json       # Marketplace catalog
└── my-dev-plugin/
    ├── .claude-plugin/
    │   └── plugin.json        # Name, description, version, author
    ├── commands/              # Custom slash commands
    ├── agents/                # Agent definitions
    ├── skills/                # Skills (each with its own SKILL.md)
    ├── hooks/                 # Hook configuration and scripts
    └── .mcp.json              # MCP server configuration

dev-plugins/                   # Marketplace repository
├── .github/
│   └── plugin/
│       └── marketplace.json   # Marketplace catalog
└── plugins/
    └── my-plugin/
        ├── plugin.json        # Manifest at the plugin root
        ├── agents/            # Agent definitions (*.agent.md)
        ├── skills/            # Skills (each with its own SKILL.md)
        ├── hooks/
        │   └── hooks.json     # Hook configuration
        └── .mcp.json          # MCP server configuration

dev-plugins/                   # Marketplace repository
├── .agents/
│   └── plugins/
│       └── marketplace.json   # Marketplace catalog
└── plugins/
    └── my-plugin/
        ├── .codex-plugin/
        │   └── plugin.json    # Name, description, version
        ├── skills/            # Skills (each with its own SKILL.md)
        ├── .mcp.json          # MCP server configuration
        └── .app.json          # App integration mappings

Marketplace

A marketplace is the distribution side of the plugin model: a catalog that lists one or more plugins, so clients can discover and install them by name. In most tools the catalog is a file in an ordinary Git repository, and one repository can host many plugins. The catalog file lists each plugin as an entry: its name, the source it is fetched from, and metadata such as a description or version. The exact schema differs by tool, but the role is the same — clients read this one file to know what the marketplace offers:

{
  "name": "dev-plugins",
  "owner": {
    "name": "Your Org"
  },
  "plugins": [
    {
      "name": "review-plugin",
      "source": "./review-plugin",
      "description": "Self-review workflow and review commands"
    }
  ]
}

{
  "name": "dev-plugins",
  "owner": {
    "name": "Your Org",
    "email": "plugins@example.com"
  },
  "metadata": {
    "description": "Curated plugins for the team",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "review-plugin",
      "description": "Self-review workflow and review commands",
      "version": "1.0.0",
      "source": "./plugins/review-plugin"
    }
  ]
}

{
  "name": "dev-plugins",
  "interface": {
    "displayName": "Dev Plugins"
  },
  "plugins": [
    {
      "name": "review-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/review-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_FIRST_USE"
      },
      "category": "Development"
    }
  ]
}

/plugin marketplace add your-org/dev-plugins
/plugin install review-plugin@dev-plugins

copilot plugin marketplace add your-org/dev-plugins
copilot plugin install review-plugin@dev-plugins

codex plugin marketplace add your-org/dev-plugins
codex plugin add review-plugin@dev-plugins

Because a marketplace is an ordinary repository, distribution reuses infrastructure the team already has. Access control is repository permission, review is a pull request, and publishing an update is a push to the default branch. Repository visibility also controls the distribution scope. Host the marketplace in a private repository, and the plugins can be installed only by members with access to it — an organization-internal distribution channel with no additional infrastructure.

Adoption process

Rolling out a plugin works best as a staged process. The stages move a workflow from one person’s machine to the organization, validating it at each step.

Prove the workflow individually

Start from commands and skills that already work in daily use. A plugin multiplies whatever it contains, so package procedures that have earned repetition — not ideas that have never run.

Package it as a plugin

Move the proven pieces into the plugin directory structure and write the manifest. Remove machine-specific paths and personal assumptions so the plugin runs on any member’s environment.

Publish to a marketplace

Create or reuse a marketplace repository, add the plugin to the catalog, and have a first group of users install it. Their friction points — unclear names, missing prerequisites — are the review feedback for this stage.

Roll out and iterate

Announce the plugin to the wider team and treat it as a product: collect feedback through issues and pull requests on the plugin repository, and ship improvements as versioned updates.

The process is incremental by design. A marketplace with one small, genuinely useful plugin beats a large catalog nobody has validated.

Running plugins from CI

A plugin is not limited to interactive sessions. CI can install the same plugin and invoke its skills, which applies the team’s standard procedures — reviews, checks, report generation — automatically and on schedule, including to code no one is actively touching. For example, a GitHub Actions workflow can fetch the marketplace repository, install the plugin, and invoke its skill on every pull request:

.github/workflows/plugin-review.yml

name: Plugin review

on:
  pull_request:
    types: [opened, reopened, ready_for_review]

jobs:
  review:
    if: github.event.pull_request.draft == false
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0

      # Fetch the (private) marketplace repository with a read-only token
      - name: Clone the plugin marketplace
        run: |
          git clone https://x-access-token:${{ secrets.PLUGIN_REPO_TOKEN }}@github.com/your-org/dev-plugins.git /tmp/dev-plugins

      # Install the same plugin definition used locally, then run its skill
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ github.token }}
          plugin_marketplaces: |
            /tmp/dev-plugins
          plugins: |
            review-plugin@dev-plugins
          claude_args: >-
            --allowedTools Read
            --allowedTools "Bash(git diff*)"
            --allowedTools "Bash(gh pr view*)"
            --allowedTools "Bash(gh pr comment*)"
          prompt: /review-plugin:self-review --no-interactive

Two details keep a job like this reliable. The prompt passes a non-interactive flag, so the skill never stops to wait for human input, and the allowed tools are narrowed to exactly what the skill needs. Running the exact same plugin in both places is the point: local runs and CI runs share one definition, so the standard cannot drift between them. When a CI job creates commits or pull requests, give it credentials with the narrowest workable scope, and prefer tokens whose activity triggers the same checks as a human’s.

Operational considerations

Once a plugin is shared infrastructure, three concerns dominate its operation: how updates propagate, who contributes improvements, and who reviews what it can do.

Versioning and updates

A plugin’s version lives in its manifest, and each release should change it deliberately. Semantic versioning gives installers a signal for how safe an update is, and a short changelog tells them what changed and why. Distribution follows the repository: pushing to the marketplace’s default branch makes a release available, and installations pick it up when they update. Two habits keep this reliable:

Encourage regular updates, so installations do not silently fall behind the team standard the plugin exists to maintain.
Announce breaking changes — renamed commands, changed output formats — before shipping them, because installed plugins are part of other people’s daily workflow.

Open contribution and ownership

Run the marketplace as a repository every member can contribute to, not just install from. Installation is one command, and because the marketplace is an ordinary repository, adding a new skill or improving an existing one is an ordinary pull request. Open contribution changes who owns the standard. When only its introducer can change a plugin, every improvement waits on one person; when anyone can, improving the shared workflow becomes part of everyone’s work. A marketplace operated this way keeps receiving improvements even in periods when the person who introduced it is not contributing. This is also why plugins work as an enablement mechanism. The role of whoever drives AI adoption in an organization is not to push usage case by case, but to build mechanisms through which usage spreads on its own. A plugin marketplace that every member can install from and contribute to is such a mechanism.

Trust and review

Installing a plugin hands it real capability: hooks execute scripts, MCP configuration connects external servers, and commands direct the agent. Treat a plugin like any other dependency with code-execution rights. What that capability can be turned into, and how to bound it, is covered in Security.

Install only from marketplaces the team controls or explicitly trusts.
Review what a plugin bundles — especially hooks and MCP configuration — before adding it to the catalog, and re-review on updates.
Keep each bundled skill’s tool permissions minimal, as described in Skills, so the plugin’s total surface stays legible.

A plugin distributes a workflow but does not design it. See Agentic Workflow for how to structure the delegation the plugin packages, and Vibe Coding for the collaboration practices underneath.

Skills

Package a single workflow as a reusable unit the agent loads on demand — the most common content of a plugin.

MCP

Connect agents to external data sources and tools through an open standard, configured and distributed via plugins.

Agentic Workflow

Design the delegation model — planning, implementation, verification — that plugins standardize across a team.

Security

What to review before installing a plugin, and how permission settings are kept consistent once distributed.

​Overview

​Why plugins matter

​Core components

​Marketplace

​Adoption process

​Running plugins from CI

​Operational considerations

​Versioning and updates

​Open contribution and ownership

​Trust and review

​Related pages

Skills

MCP

Agentic Workflow

Security

Overview

Why plugins matter

Core components

Marketplace

Adoption process

Running plugins from CI

Operational considerations

Versioning and updates

Open contribution and ownership

Trust and review

Related pages