Referensi plugin

Dokumentasi referensi untuk membuat, menyusun, dan mengirimkan plugin Cursor. Plugin mengemas aturan, skill, agent, perintah, server MCP, dan hook ke dalam bundel yang dapat didistribusikan dan berfungsi di Cursor IDE.

Jika memulai dari awal, gunakan repositori templat plugin.

Format plugin yang didukung

Cursor memuat plugin dalam dua format, yang dibedakan berdasarkan lokasi manifesnya:

Plugin yang sesuai dengan spesifikasi Agent Plugins dapat dimuat di Cursor tanpa perubahan. Selebihnya, referensi ini mendokumentasikan format plugin Cursor, yang dikembangkan secara paralel dengan standar tersebut dan mendukung rangkaian lengkap komponen Cursor.

Struktur plugin

Plugin adalah direktori yang berisi file manifes dan aset plugin Anda:

my-plugin/├── plugin.json            # Wajib: manifes Agent Plugins├── skills/                # Skill Agent│   └── code-reviewer/│       └── SKILL.md└── mcp.json               # Definisi server MCP

Manifes Plugin Cursor

Setiap Plugin Cursor memerlukan file manifes .cursor-plugin/plugin.json. Bagian di bawah mendokumentasikan field, komponen, dan fitur marketplace Plugin Cursor. Untuk manifes root Agent Plugins, gunakan referensi manifes standar.

Field wajib

Field opsional

Contoh manifes

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

Variabel

Gunakan variables untuk mendeklarasikan nama (serta jenis/deskripsi) konfigurasi yang ditentukan pengguna — misalnya token API untuk server MCP HTTP. Plugin hanya mendefinisikan schema; plugin tidak menyertakan nilai secret itu sendiri.

Admin tim menetapkan nilai sebenarnya di Dashboard, pada bagian Plugins (saat menginstal atau nanti melalui atur pada plugin).

Jangan menyimpan nilai secret di repo plugin. Dalam mcp.json dan konfigurasi plugin lainnya, sertakan hanya placeholder ${VAR} yang sesuai dengan nama properti dalam schema.

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

Level teratas harus berupa { "type": "object", "properties": { ... } }. Hanya serangkaian keyword JSON Schema tetap yang diterima (type, title, description, default, enum, const, properties, required, items, serta batasan panjang dan numerik umum).

Penemuan komponen Plugin Cursor

Jika manifes tidak menentukan path eksplisit untuk suatu jenis komponen, parser menggunakan penemuan otomatis berbasis folder:

Jika suatu field manifes memang ditentukan (misalnya, "skills": "./my-skills/"), field tersebut menggantikan penemuan berbasis folder untuk komponen itu. Folder default juga tidak dipindai.

Format aturan

Aturan adalah file .mdc yang memberikan panduan permanen kepada AI. Letakkan di direktori rules/.

Aturan memerlukan YAML frontmatter dengan metadata:

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

Field frontmatter aturan

Untuk dokumentasi lengkap, lihat Aturan.

Format Skills

Skills adalah kemampuan khusus yang didefinisikan dalam file SKILL.md. Setiap skill berada di direktori tersendiri di dalam skills/.

Skills memerlukan frontmatter YAML berisi metadata:

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

Field frontmatter Skill

Untuk dokumentasi lengkap, lihat Skills.

Format Agents

Agents adalah file Markdown yang mendefinisikan perilaku dan prompt agent kustom. Tempatkan file tersebut di direktori agents/.

Agents memerlukan YAML frontmatter yang berisi metadata:

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

Field frontmatter Agent

Format perintah

Perintah adalah file markdown atau teks yang mendefinisikan tindakan yang dapat dijalankan oleh agent. Letakkan file tersebut di direktori commands/.

Perintah mendukung ekstensi .md, .mdc, .markdown, dan .txt. File ini dapat mencakup YAML frontmatter:

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

Field frontmatter perintah

Format hook

Hook adalah skrip otomatisasi yang dipicu oleh peristiwa agent, Tab, atau workspace. Definisikan di 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"      }    ]  }}

Peristiwa hook yang tersedia

• Hook agent: sessionStart, sessionEnd, preToolUse, postToolUse, postToolUseFailure, subagentStart, subagentStop, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, preCompact, stop, afterAgentResponse, afterAgentThought
• Hook Tab: beforeTabFileRead, afterTabFileEdit
• Hook siklus hidup aplikasi: workspaceOpen

Untuk dokumentasi lengkap, lihat Hooks.

Server MCP

Kedua format menempatkan mcp.json di root plugin. Agent Plugins menggunakan schema standar dan mendeklarasikan transport untuk setiap server. Plugin Cursor dapat menggunakan variabel Cursor dan menentukan transport berdasarkan command atau 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}"    }  }}

Untuk dokumentasi lengkap, lihat MCP.

Logo

Commit logo ke repositori Anda dan rujuk menggunakan path relatif:

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

Path relatif dikonversi menjadi URL raw.githubusercontent.com berdasarkan repositori dan SHA commit. Misalnya, assets/logo.svg di repo acme/plugins pada commit abc123 dikonversi menjadi:

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

URL absolut untuk konten pengguna GitHub (yang diawali dengan http:// atau https://) juga didukung.

Repositori multi-plugin Cursor

Satu repositori Git dapat memuat beberapa plugin dengan manifes marketplace. Tempatkan manifes tersebut di .cursor-plugin/marketplace.json pada root repositori.

Format manifes 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"    }  ]}

Field manifes marketplace

Field entri plugin

Setiap entri dalam array plugins mendukung:

Cara kerja penyelesaian

Untuk entri marketplace dengan "source": "my-plugin":

1. Parser mencari my-plugin/.cursor-plugin/plugin.json
2. Jika ditemukan, manifes per-plugin digabungkan dengan entri marketplace (nilai dalam manifes diutamakan)
3. Penemuan komponen dilakukan di dalam direktori my-plugin/, menggunakan path yang ditentukan dalam manifes atau penemuan berbasis folder sebagai fallback

Contoh repo multi-plugin

my-plugins/├── .cursor-plugin/│   └── marketplace.json       # Mencantumkan semua plugin├── eslint-rules/│   ├── .cursor-plugin/│   │   └── plugin.json        # Manifes per 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

Mengirimkan plugin

Plugin ditinjau oleh tim Cursor. Untuk mengirimkannya:

Daftar periksa pengajuan

• Plugin memiliki manifes root plugin.json atau .cursor-plugin/plugin.json yang valid
• name unik, menggunakan huruf kecil dan kebab-case (misalnya, my-awesome-plugin)
• description menjelaskan tujuan plugin dengan jelas
• Semua komponen yang disertakan memiliki file dan frontmatter yang valid
• Logo telah di-commit ke repo dan direferensikan dengan path relatif (jika ada)
• README.md mendokumentasikan penggunaan dan konfigurasi
• Agent Plugins mematuhi schema Agent Plugins
• Plugin Cursor yang menggunakan variabel mendeklarasikan setiap ${VAR} dari mcp.json dalam schema manifes
• Semua path dalam manifes bersifat relatif dan valid (tanpa .. atau path absolut)
• Plugin telah diuji secara lokal
• Repo multi-plugin Cursor memiliki .cursor-plugin/marketplace.json di root repo dengan nama plugin yang unik