> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up your plugin ecosystem

> Build, host, and govern a shared set of Devin plugins for your organization or enterprise, with managed distribution and policy controls.

This guide walks through standing up your own **plugin ecosystem**: a repo of plugins your organization owns, distributed to every Devin session and CLI user through a managed manifest, with required, optional, and forbidden plugins as the governance controls.

Two template repos accompany this guide:

* [**plugin-template**](https://github.com/CognitionAI/plugin-template) — a starter for authoring a single plugin (or a couple of them).
* [**team-marketplace-template**](https://github.com/CognitionAI/team-marketplace-template) — the full ecosystem pattern: a monorepo of plugins plus a **meta-plugin** whose manifest defines your baseline and policy.

## 1. Author your plugins

A plugin is a directory with a `.devin-plugin/plugin.json` manifest; everything else is optional:

```
my-plugin/
├── .devin-plugin/
│   └── plugin.json     # name, version, dependency + policy lists
├── AGENTS.md           # always-on rule
├── rules/              # triggered rules
├── agents/<name>.md   # custom subagents (CLI/Desktop-only today); agents/<name>/AGENT.md also works
├── hooks.json          # lifecycle hooks
├── .mcp.json           # MCP servers
└── skills/<name>/SKILL.md   # skills, exposed as /<plugin>:<skill>
```

Fork [plugin-template](https://github.com/CognitionAI/plugin-template) to start, and see the [CLI plugins reference](/cli/extensibility/plugins/overview) for the full format. Keep `AGENTS.md` short — it costs context in every session for everyone who has the plugin.

## 2. Validate and test locally

Both templates ship a validator (`node scripts/validate-template.mjs`) and a CI workflow that runs it on every PR. For a live test, install from a local folder with the [Devin CLI](/cli/index):

```bash theme={null}
devin plugins install --local ./plugins/my-plugin   # linked, this machine only: edits apply on the next session
devin plugins list
```

You can also upload a plugin folder or `.zip` to your personal scope from [Customize → Plugins](/product-guides/plugins#from-a-repository-a-zip-or-the-editor) and try it in a cloud session.

## 3. Host them in one repo

Put all of your org's plugins in a single repo as subfolders (`plugins/<name>/`), each referenced with its own `git-subdir` source. The repo can stay private: cloud sessions fetch it through your Git integration, and CLI users fetch with their own git credentials (so they need repo access too).

Fork [team-marketplace-template](https://github.com/CognitionAI/team-marketplace-template) for this layout — and update its meta-plugin's `git-subdir` URLs to point at your fork. In the template the meta-plugin lives at the **repo root**, so the repo itself is the installable unit: requiring `your-org/your-marketplace` installs the whole baseline.

## 4. Define your baseline with a meta-plugin

The **meta-plugin** pattern turns your whole ecosystem into one installable unit. It's a plugin with little or no content of its own — its manifest does the work. Put it at the repo root so the repo itself is the meta-plugin:

```jsonc theme={null}
// .devin-plugin/plugin.json (repo root)
{
  "name": "team-starter-pack",
  "requiredPlugins": [
    // auto-installed for everyone, recursively
    { "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/engineering-baseline" },
    { "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/security-guardrails" }
  ],
  "optionalPlugins": [
    // endorsed, not auto-installed; also a carve-out from this manifest's forbids
    { "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/frontend-standards" }
  ],
  "forbiddenPlugins": [
    "untrusted-vendor/*"
  ]
}
```

## 5. Distribute from Customize

An admin installs the marketplace repo from [**Customize → Plugins → Add plugin → From repository**](https://app.devin.ai/customize) at the organization or enterprise scope — see the [Plugins guide](/product-guides/plugins). That adds one entry to the scope's managed manifest:

```json theme={null}
{
  "requiredPlugins": ["acme/plugins"]
}
```

Requiring the marketplace repo installs its root meta-plugin, which pulls in the whole baseline recursively. Customize then indexes the scope and lists every plugin it pulled in, with their skills, MCPs, hooks, and rules.

Everyone in scope now gets the baseline automatically — in cloud sessions, the Devin CLI, and Devin Desktop. Pick the scope deliberately:

* The **enterprise** manifest reaches every organization in the enterprise.
* An **organization** manifest reaches that organization's cloud sessions, and the CLI/Desktop of members whose primary organization it is.

If the baseline ships MCP servers that need credentials, finish setup on the [MCPs tab](/product-guides/plugins#mcps) after indexing. For OAuth servers with **Organization** access, connect a service account for members to share; with **Personal** access, each member connects their own account. If the baseline's content is missing, follow [Resolve indexing issues](/product-guides/plugins#resolve-indexing-issues).

## 6. Govern

The three lists are the policy language, at every level (managed manifests, repo config, plugin manifests). Higher authority wins — enterprise/account over org over repo over user — and a lower level can never re-permit what a higher level forbids, nor forbid what it requires.

To lock an account down to an approved set only:

```json theme={null}
{
  "forbiddenPlugins": ["*"],
  "requiredPlugins": [
    "acme/plugins",
    { "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/engineering-baseline" },
    { "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/security-guardrails" }
  ],
  "optionalPlugins": [
    { "source": "git-subdir", "url": "https://github.com/acme/plugins.git", "path": "plugins/frontend-standards" }
  ]
}
```

The manifest's own required/optional entries are exempt from its own `"*"` forbid; nothing else is, and no lower level can widen the carve-out. The exemption covers only *directly listed* entries — a required plugin's transitive dependencies aren't exempt — so under a lockdown, list everything the meta-plugin pulls in (here `engineering-baseline` and `security-guardrails`) explicitly. See [dependencies and governance](/cli/extensibility/plugins/overview#dependencies) for the full semantics.

## 7. Evolve

* Merging to your plugin repo's default branch **is** the release: new sessions pick it up automatically — see [how updates roll out](/product-guides/plugins#how-updates-roll-out).
* Teams add plugins by PR to the marketplace repo; the template's CI validates the layout on every PR.
* Existing Claude plugins install as-is (Devin falls back to `.claude-plugin/plugin.json`), so you can endorse community plugins in `optionalPlugins` without vendoring them.

## Current limitations

* Plugins load in cloud sessions, the [Devin CLI](/cli/index), and Devin Desktop (when using Devin Local); they do not apply to the classic Cascade agent.
* **Subagents** (`agents/<name>.md` or `agents/<name>/AGENT.md`) load in local Devin agents only (CLI and Devin Desktop), not in cloud sessions.
* **Hooks** are currently **best effort and fail open** — a hook that fails to load or run doesn't stop the session — so don't rely on them for crucial guardrails yet. See the [CLI hooks reference](/cli/extensibility/hooks/overview) for local configuration.
* **Governance fails open**: if a managed manifest can't be fetched at session start, that level's plugins aren't installed and its forbids aren't enforced for that session.
* Plugin content from a **private repo** appears in Customize only for organizations whose Git integration can reach the repo; elsewhere it's withheld until the repo is granted on Settings → Repositories.

## Learn more

* [Plugins guide](/product-guides/plugins) — the web app side: Customize, scopes, indexing, MCPs
* [CLI plugins reference](/cli/extensibility/plugins/overview) — file format, authoring, per-user installs
* [Skills](/product-guides/skills) — the `SKILL.md` procedures plugins bundle


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.