Plugin-Referenz

Referenzdokumentation zum Erstellen, Strukturieren und Veröffentlichen von Cursor-Plugins. Plugins bündeln Regeln, Skills, Agenten, Befehle, MCP-Server und Hooks zu verteilbaren Paketen, die in der Cursor-IDE funktionieren.

Wenn du bei null anfängst, nutze das Plugin-Vorlagen-Repository.

Unterstützte Plugin-Formate

Cursor lädt Plugins in zwei Formaten, die anhand des Speicherorts ihres Manifests unterschieden werden:

Ein Plugin, das der Agent-Plugins-Spezifikation entspricht, wird in Cursor unverändert geladen. Der Rest dieser Referenz dokumentiert das Cursor-Plugin-Format, das parallel zum Standard entwickelt wird und den vollständigen Satz an Cursor-Komponenten unterstützt.

Plugin-Struktur

Ein Plugin ist ein Verzeichnis mit einer Manifestdatei und deinen Plugin-Assets:

my-plugin/├── plugin.json            # Erforderlich: Manifest für Agent Plugins├── skills/                # Agent Skills│   └── code-reviewer/│       └── SKILL.md└── mcp.json               # MCP-Server-Definitionen

Cursor-Plugin-Manifest

Jedes Cursor-Plugin benötigt eine Manifestdatei unter .cursor-plugin/plugin.json. Die folgenden Abschnitte dokumentieren Cursor-Plugin-Felder, Komponenten und Marketplace- Features. Für ein Agent-Plugins-Manifest im Stammverzeichnis verwenden Sie die Manifest-Referenz des Standards.

Erforderliche Felder

Optionale Felder

Beispielmanifest

{  "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"}

Variablen

Verwende variables, um die Namen (sowie Typen/Beschreibungen) nutzerdefinierter Konfigurationswerte zu deklarieren – beispielsweise eines API-Tokens für einen HTTP-MCP-Server. Das Plugin definiert nur das Schema; die geheimen Werte selbst enthält es nicht.

Team-Admins legen die tatsächlichen Werte im Dashboard unter Plugins fest (bei der Installation oder später über Konfigurieren im Plugin).

Speichere keine geheimen Werte im Plugin-Repo. Füge in mcp.json und anderen Plugin-Konfigurationen nur ${VAR}-Platzhalter ein, die den Eigenschaftsnamen im Schema entsprechen.

{  "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}"      }    }  }}

Die oberste Ebene muss { "type": "object", "properties": { ... } } sein. Akzeptiert wird nur ein fester Satz von JSON-Schema-Schlüsselwörtern (type, title, description, default, enum, const, properties, required, items sowie gängige Längen- und numerische Einschränkungen).

Komponentenerkennung für Cursor-Plugins

Wenn das Manifest keine expliziten Pfade für einen Komponententyp angibt, verwendet der Parser die automatische ordnerbasierte Erkennung:

Wenn ein Manifest-Feld angegeben ist (z. B. "skills": "./my-skills/"), ersetzt es die Ordnererkennung für diese Komponente. Der Standardordner wird dann nicht zusätzlich gescannt.

Regelformat

Regeln sind .mdc-Dateien mit dauerhaft verfügbaren Anweisungen für die AI. Legen Sie sie im Verzeichnis rules/ ab.

Regeln benötigen YAML-Frontmatter mit Metadaten:

---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`.

Regel-Frontmatter-Felder

Die vollständige Dokumentation finden Sie unter Regeln.

Skill-Format

Skills sind spezialisierte Fähigkeiten, die in SKILL.md-Dateien definiert sind. Jeder Skill befindet sich in einem eigenen Verzeichnis unter skills/.

Skills benötigen YAML-Frontmatter mit Metadaten:

---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## Wann verwenden- Entwurf neuer API-Endpunkte- Prüfung von API-Contracts- Erstellung von API-Dokumentation## Anleitung1. REST-Konventionen für die Benennung von Ressourcen befolgen2. Passende HTTP-Methoden nutzen (GET, POST, PUT, DELETE, PATCH)3. Korrekte Fehlerantworten mit Standard-HTTP-Statuscodes enthalten4. Alle Endpunkte gemäß OpenAPI-3.0-Spezifikation dokumentieren5. Einheitliche Benennungskonventionen nutzen (kebab-case für URLs, camelCase für JSON)

Skill-Frontmatter-Felder

Die vollständige Dokumentation finden Sie unter Skills.

Agents-Format

Agents sind Markdown-Dateien, die benutzerdefiniertes Agent-Verhalten und Prompts definieren. Legen Sie sie im Verzeichnis agents/ ab.

Agents benötigen YAML-Frontmatter mit Metadaten:

---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

Agent-Frontmatter-Felder

Befehlsformat

Befehle sind Markdown- oder Textdateien, die vom Agenten ausführbare Aktionen definieren. Legen Sie sie im Verzeichnis commands/ ab.

Befehle unterstützen die Erweiterungen .md, .mdc, .markdown und .txt. Sie können YAML-Frontmatter enthalten:

---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

Frontmatter-Felder für Befehle

Hook-Format

Hooks sind Automatisierungsskripte, die durch Ereignisse von Agenten, Tabs oder im Workspace ausgelöst werden. Definieren Sie sie in 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"      }    ]  }}

Verfügbare Hook-Ereignisse

• Agent-Hooks: sessionStart, sessionEnd, preToolUse, postToolUse, postToolUseFailure, subagentStart, subagentStop, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, preCompact, stop, afterAgentResponse, afterAgentThought
• Tab-Hooks: beforeTabFileRead, afterTabFileEdit
• App-Lifecycle-Hooks: workspaceOpen

Die vollständige Dokumentation finden Sie unter Hooks.

MCP-Server

Beide Formate speichern mcp.json im Plugin-Root. Agent Plugins verwenden das Schema des Standards und geben den Transport für jeden Server an. Cursor-Plugins können Cursor-Variablen verwenden und den Transport aus command oder url ableiten.

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

Die vollständige Dokumentation findest du unter MCP.

Logos

Füge Logos zu deinem Repository hinzu und referenziere sie über einen relativen Pfad:

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

Relative Pfade werden anhand des Repositorys und des Commit-SHA in URLs zu raw.githubusercontent.com aufgelöst. Beispielsweise wird assets/logo.svg im Repo acme/plugins beim Commit abc123 wie folgt aufgelöst:

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

Absolute URLs zu GitHub-Nutzerinhalten (beginnend mit http:// oder https://) werden ebenfalls akzeptiert.

Cursor-Repositories mit mehreren Plugins

Ein einzelnes Git-Repository kann über ein Marketplace-Manifest mehrere Plugins enthalten. Legen Sie es im Root-Verzeichnis des Repositorys unter .cursor-plugin/marketplace.json ab.

Marketplace-Manifest-Format

{  "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"    }  ]}

Felder des Marketplace-Manifests

Plugin-Eintragsfelder

Jeder Eintrag im plugins-Array unterstützt:

So funktioniert die Auflösung

Für einen Marketplace-Eintrag mit "source": "my-plugin":

1. Der Parser sucht nach my-plugin/.cursor-plugin/plugin.json
2. Falls vorhanden, wird das plugin-spezifische Manifest mit dem Marketplace-Eintrag zusammengeführt (die Manifestwerte haben Vorrang)
3. Die Komponentenerkennung erfolgt im Verzeichnis my-plugin/ und verwendet, falls angegeben, die Manifestpfade; andernfalls dient die ordnerbasierte Erkennung als Fallback.

Beispiel für ein Multi-Plugin-Repo

my-plugins/├── .cursor-plugin/│   └── marketplace.json       # Listet alle Plugins auf├── eslint-rules/│   ├── .cursor-plugin/│   │   └── plugin.json        # Manifest pro 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

Ein Plugin einreichen

Plugins werden vom Cursor-Team geprüft. So reichst du ein Plugin ein:

Checkliste für die Einreichung

• Das Plugin verfügt über ein gültiges plugin.json- oder .cursor-plugin/plugin.json-Manifest
• name ist eindeutig, kleingeschrieben und im Kebab-Case (z. B. my-awesome-plugin)
• description erklärt den Zweck des Plugins eindeutig
• Alle enthaltenen Komponenten verfügen über gültige Dateien und Frontmatter
• Das Logo ist im Repo committed und über einen relativen Pfad referenziert (falls vorhanden)
• README.md dokumentiert die Nutzung und alle Konfigurationen
• Agent Plugins entsprechen den Schemas für Agent Plugins
• Cursor-Plugins, die Variablen verwenden, deklarieren jede ${VAR} aus mcp.json im Manifest-Schema
• Alle Pfade im Manifest sind relativ und gültig (kein .., keine absoluten Pfade)
• Das Plugin wurde lokal getestet
• Cursor-Multi-Plugin-Repositories enthalten im Repo-Root eine .cursor-plugin/marketplace.json mit eindeutigen Plugin-Namen