Справочник по плагинам

Справочная документация по созданию, организации и публикации плагинов Cursor. Плагины объединяют правила, навыки, агентов, команды, MCP‑серверы и хуки в распространяемые пакеты, работающие в IDE Cursor.

Если вы начинаете с нуля, используйте репозиторий с шаблоном плагина.

Поддерживаемые форматы плагинов

Cursor загружает плагины двух форматов, которые различаются расположением манифеста:

Плагин, соответствующий спецификации плагина Agent, загружается в Cursor без изменений. В остальной части справочника описан формат плагинов Cursor, который разрабатывается параллельно со стандартом и поддерживает полный набор компонентов Cursor.

Структура плагина

Плагин — это каталог с файлом манифеста и ресурсами плагина:

my-plugin/├── plugin.json            # Обязательно: манифест Agent Plugins├── skills/                # Навыки агента│   └── code-reviewer/│       └── SKILL.md└── mcp.json               # Определения MCP‑серверов

Манифест плагина Cursor

Для каждого плагина Cursor требуется файл манифеста .cursor-plugin/plugin.json. В разделах ниже описаны поля, компоненты и функции маркетплейса плагинов Cursor. Для корневого манифеста плагина Agent используйте справочник по манифесту стандарта.

Обязательные поля

Необязательные поля

Пример манифеста

{  "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, чтобы задать имена (а также типы и описания) значений конфигурации, указываемых пользователями, — например, API-токена для HTTP-сервера MCP. Плагин определяет только схему и не содержит самих секретных значений.

Администраторы команды задают фактические значения на дашборде в разделе Плагины — при установке или позже через Настроить для плагина.

Не храните секретные значения в репозитории плагина. В mcp.json и другой конфигурации плагина указывайте только заполнители ${VAR}, соответствующие именам свойств в схеме.

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

На верхнем уровне должно быть { "type": "object", "properties": { ... } }. Поддерживается только фиксированный набор ключевых слов JSON Schema (type, title, description, default, enum, const, properties, required, items и распространённые ограничения длины и числовых значений).

Обнаружение компонентов плагина Cursor

Если в манифесте не указаны явные пути для определённого типа компонентов, парсер использует автоматическое обнаружение по каталогам:

Если поле в манифесте указано (например, "skills": "./my-skills/"), оно заменяет обнаружение по каталогам для этого компонента. Каталог по умолчанию при этом не сканируется.

Формат правил

Правила — это файлы .mdc с постоянными инструкциями для ИИ. Размещайте их в каталоге rules/.

Правила требуют YAML-фронтматтера с метаданными:

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

Поля фронтматтера правила

Полную документацию см. в разделе правил.

Формат навыков

Навыки — это специализированные возможности, определённые в файлах SKILL.md. Каждый навык размещается в отдельном каталоге внутри skills/.

Для навыков необходим YAML-фронтматтер с метаданными:

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

Поля фронтматтера навыка

Полную документацию см. в разделе навык.

Формат Agents

Agents — это markdown-файлы, в которых задаются поведение и промпты пользовательских Agent. Поместите их в каталог agents/.

Для Agents требуется YAML-фронтматтер с метаданными:

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

Формат команд

Команды — это файлы Markdown или текстовые файлы, определяющие действия, которые может выполнять Agent. Размещайте их в каталоге commands/.

Команды поддерживают расширения .md, .mdc, .markdown и .txt. Они могут содержать 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

Поля фронтматтера команды

Формат хуков

Хуки — это скрипты автоматизации, которые запускаются при событиях Agent, вкладки или рабочего пространства. Определите их в 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"      }    ]  }}

Доступные события хуков

• Хуки агента: sessionStart, sessionEnd, preToolUse, postToolUse, postToolUseFailure, subagentStart, subagentStop, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit, beforeSubmitPrompt, preCompact, stop, afterAgentResponse, afterAgentThought
• Хуки вкладки: beforeTabFileRead, afterTabFileEdit
• Хуки жизненного цикла приложения: workspaceOpen

Полную документацию см. в разделе Hooks.

MCP‑серверы

Оба формата размещают mcp.json в корневом каталоге плагина. плагин Agent использует схему стандарта и указывает транспорт для каждого сервера. плагин Cursor может использовать переменные Cursor и определять транспорт по command или 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}"    }  }}

Полную документацию см. в разделе MCP.

Логотипы

Добавьте логотипы в репозиторий и укажите относительные пути к ним:

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

Относительные пути преобразуются в URL-адреса raw.githubusercontent.com на основе репозитория и SHA коммита. Например, для assets/logo.svg в репозитории acme/plugins на коммите abc123 URL будет:

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

Также поддерживаются абсолютные URL пользовательского контента GitHub (начинающиеся с http:// или https://).

Репозитории Cursor с несколькими плагинами

Один Git-репозиторий может содержать несколько плагинов с манифестом маркетплейса. Разместите его в корне репозитория по пути .cursor-plugin/marketplace.json.

Формат манифеста 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"    }  ]}

Поля манифеста Marketplace

Поля записи плагина

Каждая запись в массиве plugins поддерживает следующие поля:

Как происходит разрешение

Для записи в маркетплейсе с "source": "my-plugin":

1. Парсер ищет my-plugin/.cursor-plugin/plugin.json
2. Если файл найден, манифест плагина объединяется с записью маркетплейса (значения из манифеста имеют приоритет)
3. В каталоге my-plugin/ выполняется обнаружение компонентов: используются пути из манифеста, если они указаны, иначе — поиск на основе папок в резервном режиме

Пример репозитория с несколькими плагинами

my-plugins/├── .cursor-plugin/│   └── marketplace.json       # Список всех плагинов├── eslint-rules/│   ├── .cursor-plugin/│   │   └── plugin.json        # Манифест плагина│   └── 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

Публикация плагина

Плагины проходят ревью командой Cursor. Чтобы опубликовать плагин:

Контрольный список для публикации

• Плагин содержит корректный корневой манифест plugin.json или .cursor-plugin/plugin.json
• name уникально, записано в нижнем регистре в формате kebab-case (например, my-awesome-plugin)
• description чётко описывает назначение плагина
• Все включённые компоненты имеют корректные файлы и фронтматтер
• Логотип добавлен в репозиторий коммитом и указан относительным путём (если есть)
• README.md описывает использование и конфигурацию
• Плагины Agent соответствуют схемам Agent Plugins
• Плагины Cursor, использующие переменные, объявляют в схеме манифеста все ${VAR} из mcp.json
• Все пути в манифесте относительные и корректные (без .. и абсолютных путей)
• Плагин протестирован локально
• В мультиплагиновых репозиториях Cursor файл .cursor-plugin/marketplace.json находится в корне репозитория и содержит уникальные имена плагинов