Cursor just shipped a formal plugin system designed for coding agents, not humans. The repository structure, manifest schema, and installation flow reveal how an IDE can expose new capabilities to LLMs without recompiling or restarting. This is the first major editor to treat agent extensibility as a first-class design constraint.
The architecture matters because it shows how tool boundaries shift when the primary user is a model. Plugins are not just UI extensions. They are capability bundles that agents discover, validate, and invoke through structured metadata.
Repository Structure and Trust Boundaries
Cursor maintains two plugin directories with different trust levels:
/plugins: Internal plugins authored by Cursor, installed via@claude-plugins-official/external_plugins: Third-party submissions, installed via@claude-plugins-external
Each plugin is a standalone directory at the repository root. The required file is .cursor-plugin/plugin.json. Optional files include .mcp.json for Model Context Protocol server integration, plus commands/, agents/, and skills/ directories for the three-tier capability model.
The README includes a warning: “Anthropic does not control what MCP servers, files, or other software are included in plugins.” This is a security boundary statement. Plugins can bundle arbitrary executables, shell scripts, or network-calling MCP servers. The trust model relies on namespace separation and user consent at install time. This warning becomes critical in the validation section below, where we see that Cursor performs minimal runtime sandboxing.
Manifest Schema: Machine-Parseable Capability Discovery
The plugin.json manifest is the contract between plugin author and agent runtime. Key fields:
| Field | Purpose | Agent Impact |
|---|---|---|
name | Unique identifier for installation and updates | Parsed during /plugin install {name}@{namespace} and used as tool registry key |
description | Human and LLM-readable capability summary | Injected into agent tool selection prompts and marketplace search |
author.name, author.email | Trust signal for external plugins | Displayed during install consent flow with namespace badge |
commands | Array of slash command definitions with args schema | Each command becomes an invokable tool with type-validated arguments |
agents | Array of specialized agent definitions with system prompts | Registered as delegatable sub-agents with isolated conversation state |
skills | Array of reusable patterns or templates | Indexed for semantic search when agent generates code or documentation |
The schema balances human readability (descriptions, author metadata) with machine parseability (structured command args, agent definitions). Agents parse this JSON at plugin load time to populate their available tool set.
Three-Tier Capability Model
Cursor plugins expose capabilities through three distinct layers:
Commands are single-shot actions. Example: /pr-review-canvas renders a PR diff as an interactive canvas. The agent invokes the command, passes arguments, and receives structured output. Commands are stateless.
Agents are persistent sub-agents with their own system prompts and context. Example: the agent-compatibility plugin includes a validate-startup agent that audits repository setup scripts. The parent agent delegates to the sub-agent, which maintains conversation state and can invoke its own commands.
Skills are reusable patterns or templates. Example: the cli-for-agent plugin defines a skill for designing CLI tools with agent-friendly help text, error messages, and dry-run modes. Skills are documentation artifacts that agents reference when generating code.
This three-tier model lets plugin authors expose different abstraction levels. Commands are tools. Agents are collaborators. Skills are knowledge.
MCP Server Integration
The optional .mcp.json file bridges Cursor plugins with Model Context Protocol servers. MCP is a standard for exposing tools, resources, and prompts to LLMs. When a plugin includes .mcp.json, Cursor:
- Spawns the MCP server process (local binary or remote endpoint)
- Queries the server’s capability list via JSON-RPC
- Merges those capabilities into the agent’s tool registry
- Routes tool invocations to the MCP server with structured args
This means a plugin can expose capabilities without implementing them in the plugin itself. The plugin manifest becomes a pointer to an external capability provider. The cursor-sdk plugin uses this pattern to expose Cursor’s TypeScript SDK as MCP-compatible tools.
The security implication: MCP servers can make arbitrary network calls, read files, or execute code. Cursor does not sandbox them. The trust boundary is at plugin install time, not runtime.
Installation and Discovery Flow
Agents install plugins through two paths:
Slash command: /plugin install {plugin-name}@claude-plugins-official
This is a direct invocation. The agent knows the plugin name and namespace. Cursor fetches the plugin directory from GitHub, validates the manifest, and registers capabilities.
Marketplace UI: /plugin > Discover
This opens a browsable list of available plugins with descriptions and author metadata. The agent (or human) selects a plugin, reviews the manifest, and confirms installation. This path is for discovery, not automation.
Once installed, the plugin’s commands appear in the agent’s tool list. The agent can invoke them like any other function. The plugin’s agents appear as invokable sub-agents. The plugin’s skills appear in the agent’s knowledge base.
Cursor does not currently support semantic versioning for plugins. The /plugin install command always fetches the latest version from the main branch. There is no mechanism to pin to a specific commit or tag.
Validation and Sandboxing Constraints
Cursor performs minimal validation at install time:
- Manifest JSON must parse and include required fields
- Command definitions must include valid argument schemas
- Agent definitions must include system prompts
Cursor does not:
- Sandbox plugin code execution
- Validate MCP server endpoints
- Restrict file system or network access
- Scan for malicious code
The trust model is namespace-based. Official plugins (@claude-plugins-official) are authored by Cursor. External plugins (@claude-plugins-external) require a submission form and manual review. The review checks for:
- Clear capability descriptions
- Reasonable resource usage
- No obvious malware
This is not a security sandbox. It is a quality gate. Agents can install plugins that execute arbitrary code. The risk is mitigated by namespace separation and user consent. This is why the README warning about Anthropic not controlling plugin contents matters: you are trusting the plugin author’s entire supply chain.
Example: Orchestrate Plugin
The orchestrate plugin shows how the three-tier model composes:
Command: /orchestrate plan {task-description}
Generates a parallel execution plan with planner, worker, and verifier roles.
Agent: orchestrate-planner
A specialized agent that breaks large tasks into parallelizable subtasks. It has a system prompt optimized for decomposition and dependency analysis.
Skill: parallel-handoff-pattern
A template for structuring task handoffs between agents. Includes schemas for task state, success criteria, and error recovery.
An agent using this plugin can:
- Invoke
/orchestrate planto generate a plan - Delegate subtasks to
orchestrate-plannerfor refinement - Reference
parallel-handoff-patternwhen generating worker code
The plugin exposes all three capability types. The agent composes them based on task requirements.
Here is a minimal plugin manifest structure based on the repository pattern:
{
"name": "orchestrate",
"version": "1.0.0",
"description": "Fan large tasks out across parallel Cursor cloud agents with planners, workers, verifiers, and structured handoffs.",
"author": {
"name": "Cursor",
"email": "plugins@cursor.com"
},
"commands": [
{
"name": "plan",
"description": "Generate parallel execution plan",
"args": {
"taskDescription": {
"type": "string",
"required": true
}
}
}
],
"agents": [
{
"name": "orchestrate-planner",
"systemPrompt": "You decompose large tasks into parallelizable subtasks with clear dependencies and handoff points."
}
],
"skills": [
{
"name": "parallel-handoff-pattern",
"path": "skills/parallel-handoff.md"
}
]
}Marketplace Submission Flow
External plugin authors submit via a form that collects:
- Plugin name and description
- GitHub repository URL
- Author contact information
- Capability summary (commands, agents, skills)
Cursor reviews submissions for quality and security. Approved plugins are added to /external_plugins and appear in the marketplace. The review is manual, not automated. Turnaround time is not specified.
The submission form is a bottleneck. It limits the rate at which new capabilities can be added. This is intentional. Cursor is prioritizing trust over velocity.
Known Limitations
Manifest drift: Plugin manifests can fall out of sync with actual capabilities. If the continual-learning plugin’s manifest lists a /update-memory command that was removed in a recent commit, agents will see tool invocation errors with no clear recovery path. Cursor does not validate manifest accuracy at runtime.
MCP server crashes: If an MCP server process dies, tool invocations fail. Cursor does not auto-restart MCP servers. The agent sees a tool invocation error and must handle it.
Namespace collisions: If two plugins define commands with the same name, the last-installed plugin wins. Cursor does not prevent collisions. Agents may invoke the wrong command.
Malicious plugins: External plugins can execute arbitrary code. Cursor’s review process is a speed bump, not a security boundary. Agents installing untrusted plugins risk code execution vulnerabilities.
Technical Verdict
Use Cursor plugins if:
- You have existing MCP servers and want to expose them through Cursor’s agent tool registry without rewriting them as native commands.
- Your team maintains internal CLIs and wants agents to invoke them with structured argument validation and automatic help text generation.
- You need sub-agents with isolated system prompts for specialized tasks (code review, compatibility audits, documentation generation) that should not pollute the main agent’s context.
- You are building developer tools that should be discoverable through a marketplace rather than requiring manual configuration.
Avoid Cursor plugins if:
- You require runtime code signing or cryptographic verification of plugin integrity. Cursor does not provide this.
- Your plugins need to run in a restricted execution environment. Cursor does not sandbox plugin code, MCP servers, or file system access.
- You need to distribute plugins through channels other than Cursor’s marketplace. There is no alternative distribution mechanism.
- You require semantic versioning or the ability to pin to specific plugin versions. Cursor always fetches the latest version from the main branch.
The architecture is a useful reference for anyone building agent extensibility systems. The three-tier capability model (commands, agents, skills) is a clean abstraction. The MCP integration shows how to bridge plugin systems with external capability providers. The trust boundary (namespace-based, install-time consent) is pragmatic but not secure.