Referencia de plugins

Documentación de referencia para crear, estructurar y enviar plugins de Cursor. Los plugins agrupan reglas, skills, agentes de programación, comandos, servidores MCP y hooks en paquetes distribuibles compatibles con el IDE de Cursor.

Si empiezas desde cero, usa el repositorio de plantilla de plugins.

Formatos de plugin compatibles

Cursor carga plugins en dos formatos, identificados por la ubicación de su manifiesto:

Un plugin que cumple con la especificación de Agent Plugins se carga en Cursor sin cambios. El resto de esta referencia documenta el formato de plugin de Cursor, que se desarrolla en paralelo con el estándar y admite el conjunto completo de componentes de Cursor.

Estructura del plugin

Un plugin es un directorio que contiene un archivo de manifiesto y los recursos del plugin:

my-plugin/├── plugin.json            # Obligatorio: manifiesto de Agent Plugins├── skills/                # Agent Skills│   └── code-reviewer/│       └── SKILL.md└── mcp.json               # Definiciones de servidores MCP

Manifiesto del plugin de Cursor

Todo plugin de Cursor requiere un archivo de manifiesto .cursor-plugin/plugin.json. Las siguientes secciones documentan los campos, componentes y funciones del marketplace de los plugins de Cursor. Para consultar el manifiesto raíz de Agent Plugins, usa la referencia del manifiesto del estándar.

Campos obligatorios

Campos opcionales

Ejemplo de manifiesto

{  "name": "enterprise-plugin",  "version": "1.2.0",  "description": "Enterprise development tools with security scanning and compliance checks",  "author": {    "name": "ACME DevTools",    "email": "devtools@acme.com"  },  "keywords": ["enterprise", "security", "compliance"],  "logo": "assets/logo.svg"}

Variables

Usa variables para declarar los nombres (y tipos/descripciones) de la configuración proporcionada por el usuario; por ejemplo, un token de API para un servidor MCP HTTP. El plugin solo define el esquema; no incluye los valores secretos.

Los administradores de equipo establecen los valores reales en el panel de control, en Plugins (durante la instalación o posteriormente mediante Configurar en el plugin).

No incluyas valores secretos en el repo del plugin. En mcp.json y otra configuración del plugin, incluye solo marcadores de posición ${VAR} que coincidan con los nombres de las propiedades del esquema.

{  "name": "example-plugin",  "variables": {    "type": "object",    "properties": {      "API_TOKEN": {        "type": "string",        "title": "API token",        "description": "Bearer token for the example HTTP MCP"      }    },    "required": ["API_TOKEN"]  }}

{  "mcpServers": {    "example-api": {      "url": "https://mcp.example.com/mcp",      "headers": {        "Authorization": "Bearer ${API_TOKEN}"      }    }  }}

El nivel superior debe ser { "type": "object", "properties": { ... } }. Solo se acepta un conjunto fijo de palabras clave de JSON Schema (type, title, description, default, enum, const, properties, required, items y restricciones habituales de longitud y valores numéricos).

Descubrimiento de componentes del plugin de Cursor

Cuando el manifiesto no especifica rutas explícitas para un tipo de componente, el analizador utiliza el descubrimiento automático basado en carpetas:

Si se especifica un campo en el manifiesto (p. ej., "skills": "./my-skills/"), este reemplaza el descubrimiento basado en carpetas para ese componente. La carpeta predeterminada no se analiza adicionalmente.

Formato de las reglas

Las reglas son archivos .mdc que proporcionan instrucciones persistentes a la IA. Colócalas en el directorio rules/.

Las reglas requieren frontmatter YAML con metadatos:

---description: Prefer const over let for variables that are never reassignedalwaysApply: true---prefer-const: Always use `const` for variables that are never reassigned.Only use `let` when the variable needs to be reassigned. Never use `var`.

Campos del frontmatter de las reglas

Para consultar la documentación completa, consulta Reglas.

Formato de skills

Los skills son capacidades especializadas definidas en archivos SKILL.md. Cada skill se encuentra en su propio directorio dentro de skills/.

Los skills requieren frontmatter de YAML con metadatos:

---name: api-designerdescription: Design RESTful APIs following OpenAPI 3.0 specification.  Use when designing new API endpoints, reviewing API contracts,  or generating API documentation.---# API Designer Skill## When to use- Designing new API endpoints- Reviewing API contracts- Generating API documentation## Instructions1. Follow REST conventions for resource naming2. Use appropriate HTTP methods (GET, POST, PUT, DELETE, PATCH)3. Include proper error responses with standard HTTP status codes4. Document all endpoints with OpenAPI 3.0 specification5. Use consistent naming conventions (kebab-case for URLs, camelCase for JSON)

Campos de frontmatter de las skills

Para obtener la documentación completa, consulta Skills.

Formato de los agentes de programación

Los agentes de programación son archivos Markdown que definen el comportamiento y las instrucciones de agentes de programación personalizados. Colócalos en el directorio agents/.

Los agentes de programación requieren frontmatter YAML con metadatos:

---name: security-reviewerdescription: Security-focused code reviewer that checks for  vulnerabilities and proven approaches---# Security ReviewerYou are a security-focused code reviewer. When reviewing code:1. Check for injection vulnerabilities (SQL, XSS, command injection)2. Verify proper authentication and authorization3. Look for sensitive data exposure (API keys, passwords, PII)4. Ensure secure cryptographic practices5. Review dependency security and known vulnerabilities6. Check for proper input validation and sanitization

Campos del frontmatter del agente

Formato de comandos

Los comandos son archivos Markdown o de texto que definen acciones que los agentes pueden ejecutar. Colócalos en el directorio commands/.

Los comandos admiten las extensiones .md, .mdc, .markdown y .txt. Pueden incluir frontmatter YAML:

---name: deploy-stagingdescription: Deploy the current branch to the staging environment---# Deploy to stagingSteps to deploy to staging:1. Run tests2. Build the project3. Push to staging branch

Campos del frontmatter de los comandos

Formato de los hooks

Los hooks son scripts de automatización que se activan mediante eventos del agente, Tab o el espacio de trabajo. Defínelos en hooks/hooks.json:

{  "hooks": {    "afterFileEdit": [      {        "command": "./scripts/format-code.sh"      }    ],    "beforeShellExecution": [      {        "command": "./scripts/validate-shell.sh",        "matcher": "rm|curl|wget"      }    ],    "sessionEnd": [      {        "command": "./scripts/audit.sh"      }    ]  }}

Eventos de hook disponibles

• Hooks del agente: sessionStart, sessionEnd, preToolUse, postToolUse, postToolUseFailure, subagentStart, subagentStop, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, preCompact, stop, afterAgentResponse, afterAgentThought
• Hooks de Tab: beforeTabFileRead, afterTabFileEdit
• Hooks del ciclo de vida de la app: workspaceOpen

Para consultar la documentación completa, consulta Hooks.

Servidores MCP

Ambos formatos colocan mcp.json en la raíz del plugin. Agent Plugins usan el esquema del estándar y declaran el transporte de cada servidor. Los plugins de Cursor pueden usar variables de Cursor e inferir el transporte a partir de command o url.

{  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",  "mcpServers": {    "code-review": {      "type": "stdio",      "command": "./bin/code-review",      "cwd": "${PLUGIN_ROOT}"    }  }}

Para obtener la documentación completa, consulta MCP.

Logotipos

Incluye los logotipos en tu repositorio y haz referencia a ellos mediante una ruta relativa:

{  "name": "my-plugin",  "logo": "assets/logo.svg"}

Las rutas relativas se resuelven en URL de raw.githubusercontent.com según el repositorio y el SHA del commit. Por ejemplo, assets/logo.svg en el repositorio acme/plugins en el commit abc123 se resuelve en:

https://raw.githubusercontent.com/acme/plugins/abc123/my-plugin/assets/logo.svg

También se aceptan las URL absolutas de contenido de usuarios de GitHub (que comienzan por http:// o https://).

Repositorios de varios plugins de Cursor

Un único repositorio de Git puede contener varios plugins mediante un manifiesto del marketplace. Colócalo en .cursor-plugin/marketplace.json, en la raíz del repositorio.

Formato del manifiesto del marketplace

{  "name": "my-marketplace",  "owner": {    "name": "Your Org",    "email": "plugins@yourorg.com"  },  "metadata": {    "description": "A collection of developer tool plugins"  },  "plugins": [    {      "name": "plugin-one",      "source": "plugin-one",      "description": "First plugin"    },    {      "name": "plugin-two",      "source": "plugin-two",      "description": "Second plugin"    }  ]}

Campos del manifiesto de Marketplace

Campos de las entradas de plugins

Cada entrada del array plugins admite:

Cómo funciona la resolución

Para una entrada del marketplace con "source": "my-plugin":

1. El parser busca my-plugin/.cursor-plugin/plugin.json
2. Si lo encuentra, el manifiesto específico del plugin se fusiona con la entrada del marketplace (los valores del manifiesto tienen prioridad)
3. El descubrimiento de componentes se realiza en el directorio my-plugin/, usando las rutas del manifiesto si se especifican o el descubrimiento basado en carpetas como alternativa

Ejemplo de repositorio multi-plugin

my-plugins/├── .cursor-plugin/│   └── marketplace.json       # Enumera todos los plugins├── eslint-rules/│   ├── .cursor-plugin/│   │   └── plugin.json        # Manifiesto de cada plugin│   └── rules/│       ├── prefer-const.mdc│       └── no-any.mdc├── docker/│   ├── .cursor-plugin/│   │   └── plugin.json│   ├── skills/│   │   ├── containerize-app/│   │   │   └── SKILL.md│   │   └── setup-docker-compose/│   │       └── SKILL.md│   └── mcp.json└── README.md

Enviar un plugin

El equipo de Cursor revisa los plugins. Para enviar el tuyo:

Lista de verificación para el envío

• El plugin tiene un manifiesto válido en la raíz: plugin.json o .cursor-plugin/plugin.json
• name es único, está en minúsculas y usa kebab-case (p. ej., my-awesome-plugin)
• description explica claramente el propósito del plugin
• Todos los componentes incluidos tienen archivos y frontmatter válidos
• El logo está incluido en el repositorio y se referencia mediante una ruta relativa (si se proporciona)
• README.md documenta el uso y cualquier configuración
• Los Agent Plugins cumplen con los schemas de Agent Plugins
• Los plugins de Cursor que usan variables declaran cada ${VAR} de mcp.json en el schema del manifiesto
• Todas las rutas del manifiesto son relativas y válidas (sin .. ni rutas absolutas)
• El plugin se ha probado localmente
• Los repositorios multi-plugin de Cursor tienen .cursor-plugin/marketplace.json en la raíz del repositorio con nombres de plugin únicos