# Agent plugins vs. skilder roles: what each one packages, and where it runs

> Agent plugins bundle skills, MCP servers and hooks into one install for one client. A skilder role serves skills and scoped tools to any MCP agent from a governed workspace. How they differ, and when to use which.

Language: en · Category: engineering · Author: Nicolas Corod (Founder & CEO) · Published: 2026-10-05

Every major agent client now has a plugin system. [Claude Code shipped plugins](https://claude.com/blog/claude-code-plugins) in October 2025, [OpenAI added more than 90 plugins to Codex](https://zuplo.com/blog/openai-codex-mcp-plugins-api-teams) in April 2026, and the [Agent Plugins specification](https://agent-plugins.org) now gives Skills and MCP servers a shared, vendor-neutral package format. If your team builds with agents, someone has already asked whether the company's procedures should ship as a plugin.

Sometimes they should. But a plugin answers a packaging question ("how do these files reach this client?"), and most companies are asking a control question ("which agent may do what, in which tool, and how do we know?"). A skilder **role** answers the second one. This article explains what each one is, compares them on the dimensions that matter in production, and says when to use which.

**The short answer:** a plugin is a package installed into one client, running as the person who installed it. A role is a set of skills and scoped tools held in a workspace and served over MCP to any agent at runtime. Use plugins for local developer tooling. Use roles for company know-how that must reach several clients under one set of rules.

## What an agent plugin is

An agent plugin is a directory of components that a client installs and loads as one unit. [Claude Code's documentation](https://code.claude.com/docs/en/plugins) lists what a plugin can hold:

- **Skills**: `SKILL.md` instructions the agent loads when relevant.
- **Agents**: subagent definitions the main agent can delegate to.
- **Hooks**: commands that run at points in the agent's lifecycle, such as after every edit.
- **MCP servers**: tool servers the client connects to while the plugin is enabled.

A manifest names and versions the package. In Claude Code it sits at `.claude-plugin/plugin.json`. In the [OpenAI plugin format](https://developers.openai.com/plugins/build/plugins) used by Codex and ChatGPT, it is a root `plugin.json` that points at the Agent Plugins schema:

```json
{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "support-playbook",
  "version": "1.2.0",
  "description": "Refund rules and ticket tools for the support team"
}
```

Plugins reach users through **marketplaces**. A marketplace is a catalog file in a Git repository (`.claude-plugin/marketplace.json` for Claude Code, `.agents/plugins/marketplace.json` for Codex) that lists plugins and where to fetch each one. You add the marketplace once, then install plugins by name.

On claude.ai, the same format installs from **Customize > Plugins** and follows your account into [chat, Cowork and Claude Code](https://claude.com/docs/plugins/overview). Each surface loads the components it supports: skills, commands and connectors everywhere, agents only in Cowork and Claude Code.

### The Agent Plugins specification

[Agent Plugins](https://agent-plugins.org) is the open standard underneath. Version 1.0.0 defines a required `plugin.json`, an optional `skills/` directory of Agent Skills, an optional `mcp.json` describing MCP servers, and reverse-domain namespaces for client-specific extensions. Its initial steering committee includes maintainers from Amazon, Cursor, Microsoft, OpenAI and Vercel.

The spec is deliberate about its scope: distribution, installation, permissions and user experience "remain under each client's control." It standardizes the box. It does not standardize who may open it.

## What a skilder role is

A **role** is a themed collection of skills an agent adopts: Support Engineer, Finance Controller, Site Foreman. It lives in a skilder workspace and holds:

| Part | What it does |
|---|---|
| **Name and description** | What the agent reads when it chooses a role. |
| **Instructions** | Role-level guidance, given once the agent learns the role. |
| **Skills** | The procedures the role unlocks, in the Agent Skills format. |
| **Tools** | The operations those skills may call, drawn from the workspace's internal, vetted registry of MCP servers. |
| **App** | Interactive cards the agent shows in the conversation, served as MCP Apps. |

An agent connects to the workspace over MCP (Streamable HTTP, with OAuth or an API key). It lists the roles it is allowed to see, learns one, and from then on works with that role's skills and tools only. Skills and their references load on demand, so a long process document costs nothing until the agent needs it.

Roles are configured from blueprints, edited as drafts and published with version history. Agents always work from the published version.

A role does not only answer in text. The workspace endpoint also serves [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps), the MCP extension for interactive UI: results of the `display` and `analytics` tools carry a card, delivered as a `ui://` resource. In an MCP client that renders cards, the agent opens a session or a call in place, pages through long results and offers follow-up questions, without leaving the chat. Clients that do not render cards still get the text.

## The same unit of know-how

Both models share their most important ingredient. A plugin's `skills/` directory and a role's skills are the same thing: `SKILL.md` files with references, scripts and assets, following the [Agent Skills standard](https://agentskills.io). skilder imports a `SKILL.md` from GitHub or a ZIP file and exports a skill back to the same format, so a skill written for a plugin can move into a role and back.

That is why "plugin or role" is not a question about content. It is a question about **where the content lives, who receives it, and what happens on each call**.

## Agent plugins vs. skilder roles, side by side

| | Agent plugin | skilder role |
|---|---|---|
| **What it is** | A package of files installed into a client | A configuration held in a workspace, served at runtime |
| **Where it runs** | In the client: on the user's machine or in the client's cloud session | Skills served by the workspace; tool calls executed and logged through it |
| **Reaches** | The client it was built for (format shared across clients via the Agent Plugins spec) | Any MCP client: Claude, ChatGPT, Copilot or any MCP-compatible agent |
| **Distribution** | Marketplace in a Git repo; installed per user, project or org | Published once in the workspace; agents learn it when they connect |
| **Updates** | Pulled from the marketplace (auto-update optional) | Publishing a new version changes it for every connected agent |
| **Context cost** | Each enabled plugin's skill names and descriptions sit in context every turn | Agent sees the role catalog, then only the role it learned |
| **Permissions** | Runs with the installing user's privileges | Scoped per role: an agent gets that role's tools and nothing else |
| **Interface** | Text, plus whatever UI its MCP servers ship | MCP App cards for activity and analytics, in clients that render them |
| **Local actions** | Hooks, subagents, language servers, local commands | None: a role does not run code on the user's machine |
| **Runtime control** | Client permission rules for tool calls | Workspace guardrails inspect each tool call and can refuse it |
| **Observability** | Install and usage counts (Team and Enterprise plans), OpenTelemetry events | Per-call execution log, success rates, guardrail verdicts |

The rest of this article takes the rows that decide most choices.

### Distribution: per client vs. per workspace

A plugin is installed. On Claude Code that happens per machine at user, project or local scope; on claude.ai it is saved to the account and synced to Cowork and Claude Code. Organizations on Team and Enterprise plans can make a plugin installed by default or required for every member, and can allowlist marketplaces through managed settings.

That works well inside one vendor's family of clients. It gets heavier when the same procedure has to reach Claude for the engineering team, ChatGPT for sales and Copilot for finance. The Agent Plugins spec reduces the cost of rebuilding the package, but each client still runs its own install, its own update cycle and its own admin console.

A role is not installed anywhere. It is published once, and any agent that connects to the workspace with the right access can learn it. Changing the refund rule means publishing one new version of one skill.

### Context: always listed vs. learned on demand

Claude Code's documentation is candid about this: an enabled plugin is part of every session, and "for each skill, agent, and command that Claude can invoke on its own, the name and description are in Claude's context on every turn", whether or not anything from the plugin runs. Ten plugins with eight skills each means eighty descriptions competing for attention in every prompt. Anthropic now shows a context cost estimate before install for this reason.

A role inverts the default. The agent starts with the catalog of roles it may use, learns one, and only that role's skills enter context. A support agent never reads the finance controller's procedures. We covered the mechanics in [from context bloat to context load](/en/blog/context-bloat-to-context-load/).

### Permissions: the installer's privileges vs. the role's scope

Anthropic's [plugin security page](https://code.claude.com/docs/en/plugins/security) opens with one sentence: "A Claude Code plugin you install can execute arbitrary code on your machine with your user privileges." Hooks run shell commands outside the sandbox, stdio MCP servers start as local processes, and auto-update can change the files you reviewed. The trust warning adds that Anthropic "cannot verify that they will work as intended or that they won't change."

None of that is a flaw. It is what makes plugins useful for developers: a hook that formats every file after an edit has to run on the machine. But it means a plugin's reach is the reach of whoever installed it. If that person's Salesforce token can delete accounts, so can the plugin's MCP server.

A role draws a narrower line. It grants the tools its skills need, from the workspace's internal registry, and nothing else, which is the [least-privilege model](/en/blog/least-privilege-ai-agents/) applied to agents. The same person can hold a broad account and still connect an agent through a role that only reads tickets.

We tested that boundary in a [30-page paper on arXiv](https://arxiv.org/abs/2609.28693): 13 scenarios, six models, three interfaces. When a governed call reached the authorization layer, no unauthorized tool call and no over-limit refund executed, because a tool that was never delivered inside a learned role cannot be called. The [summary of the paper](/en/blog/progressive-skill-discovery-paper/) covers the method and its limits.

### Runtime control: before the install vs. on every call

Plugin governance is mostly about the install: which marketplaces are allowed, which plugins are required, whether hooks from unmanaged sources may run. After that, each tool call is governed by the client's permission rules on that user's machine.

In skilder, the control point is the call itself. Every tool call routes through the workspace, where **guardrails** (scripts the workspace runs against the call) return a verdict and, in blocking mode, refuse the call with a reason the agent can act on. The agent working under the rules never sees them, so it cannot plan around them. Each call, its role, its outcome and any guardrail decision land in an exportable execution log.

### Observability: adoption counts vs. execution trace

Claude's Team and Enterprise plans show, per plugin, how many people used it and how many runs it had in the last 30 days, and Claude Code can export plugin load and install events over OpenTelemetry. That tells you a plugin is used.

It does not tell you what the plugin's tools did. A role's execution log answers that: which agent, which role, which skill, which tool, which outcome. For a regulated process that is the line between "people use it" and "we can show what happened."

## When to use an agent plugin

Plugins are the right tool when the work happens on the user's machine or inside one client:

- **Developer tooling**: formatters, linters and test runners wired as hooks, language servers, code review subagents.
- **Personal or team setups** that one person maintains and the team adopts from a shared marketplace.
- **One-client organizations** that already standardize on Claude Code or Codex and manage it through managed settings.
- **Vendor integrations** where a tool provider ships its MCP server and usage skills together, as most of the plugins in the Codex and Claude directories do.

## When to use a skilder role

Roles are the right tool when the know-how belongs to the company rather than to a developer's setup:

- **Several clients**: the same procedure must work in Claude, ChatGPT and Copilot, because different teams use different agents.
- **Scoped access**: an agent should reach some tools of a system and not others, regardless of the user's own account.
- **Per-call control**: a rule must hold on every call (no deletion of tickets, no payment above a threshold), not only at install.
- **Audit**: you need a record of what each agent did, attributable to a person and a role.
- **Non-developer users**: finance, support, operations staff who will never run `/plugin install`.

## Using both

The two compose. A plugin can declare a remote MCP server, and a skilder workspace is one. Developers keep the plugins that act locally, while company procedures and governed tools arrive through the workspace connection, identically in every client. The skills themselves stay portable across both, because they are the same `SKILL.md` files.

This mirrors the split we described between [MCP and skills](/en/blog/mcp-vs-skills-composing/): the package format says how capabilities travel, and the role says which agent may use them, how, and with what trace.

## Key takeaways

- An **agent plugin** packages skills, MCP servers, hooks and subagents for one client, installed from a marketplace and running as the user who installed it.
- The **Agent Plugins** spec standardizes the package across clients. It leaves permissions and distribution to each client.
- A **skilder role** serves skills and scoped tools from a workspace to any MCP agent, learned at runtime, controlled on each call and logged.
- Both use **SKILL.md**, so content moves between them.
- Pick plugins for local developer tooling, roles for company know-how across clients, and expect to run both.

To see how a role is structured, read the [role documentation](https://docs.skilder.ai/basics/role).