> ## Documentation Index > Fetch the complete documentation index at: https://lib.findy.co.jp/llms.txt > Use this file to discover all available pages before exploring further. # What is a plugin? One installable unit of agent setup > A plugin bundles custom commands, agents, skills, hooks, and MCP configuration into one distributable, versioned unit teams can install and update together. ## 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](/ai/skill) for reusable workflow units and [MCP](/ai/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](/ai/skill). | | 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](/ai/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. ```text Claude Code theme={null} 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 ``` ```text GitHub Copilot CLI theme={null} 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 ``` ```text Codex CLI theme={null} 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: ```json Claude Code theme={null} { "name": "dev-plugins", "owner": { "name": "Your Org" }, "plugins": [ { "name": "review-plugin", "source": "./review-plugin", "description": "Self-review workflow and review commands" } ] } ``` ```json GitHub Copilot CLI theme={null} { "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" } ] } ``` ```json Codex CLI theme={null} { "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" } ] } ``` Register the marketplace once, then install plugins by name: ```text Claude Code theme={null} /plugin marketplace add your-org/dev-plugins /plugin install review-plugin@dev-plugins ``` ```text GitHub Copilot CLI theme={null} copilot plugin marketplace add your-org/dev-plugins copilot plugin install review-plugin@dev-plugins ``` ```text Codex CLI theme={null} 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. 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. 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. 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. 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: ```yaml .github/workflows/plugin-review.yml theme={null} 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](/ai/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](/ai/skill), so the plugin's total surface stays legible. A plugin distributes a workflow but does not design it. See [Agentic Workflow](/ai/agentic-workflow) for how to structure the delegation the plugin packages, and [Vibe Coding](/ai/vibe-coding) for the collaboration practices underneath. ## Related pages Package a single workflow as a reusable unit the agent loads on demand — the most common content of a plugin. Connect agents to external data sources and tools through an open standard, configured and distributed via plugins. Design the delegation model — planning, implementation, verification — that plugins standardize across a team. What to review before installing a plugin, and how permission settings are kept consistent once distributed.