プラグインリファレンス
Cursor プラグインの作成、構成、公開に関するリファレンスドキュメントです。プラグインでは、ルール、スキル、エージェント、コマンド、MCP サーバー、フックを、Cursor IDE で利用できる配布可能なバンドルとしてパッケージ化します。
初めて作成する場合は、プラグインテンプレートリポジトリを使用してください。
サポートされているプラグイン形式
Cursor は、マニフェストの配置場所によって識別される 2 種類のプラグイン形式を読み込みます。
| 形式 | マニフェストの場所 | コンポーネント |
|---|---|---|
| Agent Plugins (オープン標準) | プラグインルートの plugin.json | スキル、MCP サーバー |
| Cursor プラグイン | .cursor-plugin/plugin.json | スキル、MCP サーバー、ルール、エージェント、コマンド、フック、変数 |
Agent Plugins specification に準拠したプラグインは、変更なしで Cursor に読み込まれます。以降のリファレンスでは、標準と並行して開発され、Cursor のすべてのコンポーネントをサポートする Cursor プラグイン形式について説明します。
プラグインの構成
プラグインは、マニフェストファイルとプラグインのアセットを含むディレクトリです。
my-plugin/├── plugin.json # 必須: Agent Plugins マニフェスト├── skills/ # Agent Skills│ └── code-reviewer/│ └── SKILL.md└── mcp.json # MCP サーバー定義Agent Plugins 標準では、ポータブルなスキルと MCP サーバーを定義します。パッケージとスキーマの詳細については、 Agent Plugins authoring guideを参照してください。
Cursor プラグインのマニフェスト
すべての Cursor プラグインには、.cursor-plugin/plugin.json マニフェストファイルが必要です。以下の
セクションでは、Cursor プラグインのフィールド、コンポーネント、マーケットプレイスの
機能について説明します。ルート Agent Plugins マニフェストについては、
標準のマニフェストリファレンスを参照してください。
必須フィールド
| フィールド | 型 | 説明 |
|---|---|---|
name | string | プラグイン識別子。小文字のケバブケース (英数字、ハイフン、ピリオド) で指定します。先頭と末尾は英数字にする必要があります。例: my-plugin, prompts.chat |
任意フィールド
| フィールド | 型 | 説明 |
|---|---|---|
description | string | プラグインの簡単な説明 |
version | string | セマンティックバージョン (例: 1.0.0) |
author | object | 作成者情報: name (必須) 、email (任意) |
homepage | string | プラグインのホームページ URL |
repository | string | プラグインリポジトリの URL |
license | string | ライセンス識別子 (例: MIT) |
keywords | array | 検索・分類用のタグ |
logo | string | リポジトリ内のロゴファイルへの相対パス (例: assets/logo.svg) 、または絶対 URL。相対パスは raw.githubusercontent.com の URL に解決されます。推奨: ロゴをリポジトリにコミットし、相対パスを使用してください。 |
rules | string or array | ルールファイルまたはディレクトリへのパス |
agents | string or array | エージェントファイルまたはディレクトリへのパス |
skills | string or array | スキルディレクトリへのパス |
commands | string or array | コマンドファイルまたはディレクトリへのパス |
hooks | string or object | フック設定ファイルへのパス、またはインラインフック設定 |
mcpServers | string, object, or array | MCP 設定ファイルへのパス、インライン MCP サーバー設定、またはそのいずれかの配列。デフォルトの mcp.json の検出を上書きします。 |
variables | object | 変数の名前 (トークン、接続文字列) を宣言する JSON Schema。プラグインはシークレット値を保存しません。ユーザーはダッシュボード (プラグイン → 設定する) で設定します。${VAR} プレースホルダーに置換されます。変数を参照してください。 |
マニフェストの例
{ "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 を使用して、ユーザーが指定する設定の名前 (および型や説明) を宣言します。たとえば、HTTP MCP サーバーの API トークンなどです。プラグインではスキーマのみを定義し、シークレット値自体は含めません。
チーム管理者は、ダッシュボードの プラグイン で実際の値を設定します (インストール時、または後からプラグインの 設定する で設定) 。
プラグインのリポジトリにシークレット値を保存しないでください。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/ | SKILL.md ファイルを含む各サブディレクトリ |
| ルール | rules/ | すべての .md、.mdc、.markdown ファイル |
| エージェント | agents/ | すべての .md、.mdc、.markdown ファイル |
| コマンド | commands/ | すべての .md、.mdc、.markdown、.txt ファイル |
| フック | hooks/hooks.json | フックイベント名を解析 |
| MCP サーバー | mcp.json | サーバーエントリを解析 |
| ルートスキル | プラグインルートの SKILL.md | 単一スキルプラグインとして扱います (skills/ ディレクトリがなく、マニフェストに skills フィールドもない場合のみ) |
マニフェストフィールドが指定されている場合 (例: "skills": "./my-skills/") 、そのコンポーネントではフォルダーベースの検出の代わりに使用されます。デフォルトフォルダーもスキャンされません。
ルールの形式
ルールは、AI に継続的な指針を与える .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`.ルールのフロントマターフィールド
| フィールド | 型 | 説明 |
|---|---|---|
description | string | ルールの概要 |
alwaysApply | boolean | true の場合、ルールはすべてのファイルに適用されます。false の場合、ルールはリクエストに応じて利用できます。 |
globs | string または array | ルールを適用するファイルパターン (例: "**/*.ts") |
詳細は、ルールを参照してください。
スキルの形式
スキルは、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 スキル## 使用する場面- 新しい API エンドポイントを設計するとき- API コントラクトを確認するとき- API ドキュメントを生成するとき## 手順1. リソースの命名は REST の規約に従う2. 適切な HTTP メソッドを使用する(GET、POST、PUT、DELETE、PATCH)3. 標準的な HTTP ステータスコードを用いた適切なエラーレスポンスを含める4. すべてのエンドポイントを OpenAPI 3.0 仕様で文書化する5. 一貫した命名規則を使用する(URL は kebab-case、JSON は camelCase)スキルのフロントマターのフィールド
| フィールド | 型 | 説明 |
|---|---|---|
name | string | スキルの識別子 (小文字、ケバブケース) |
description | string | スキルの機能と使用するタイミングの説明 |
詳細は、スキルを参照してください。
エージェントの形式
エージェントは、カスタムエージェントの挙動とプロンプトを定義するMarkdownファイルです。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エージェントのフロントマターフィールド
| フィールド | 型 | 説明 |
|---|---|---|
name | string | エージェントの識別子 (小文字、ケバブケース) |
description | string | エージェントの目的の簡単な説明 |
コマンドの形式
コマンドは、エージェントが実行可能なアクションを定義する Markdown またはテキストファイルです。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コマンドのフロントマターフィールド
| フィールド | 型 | 説明 |
|---|---|---|
name | string | コマンド識別子 (小文字、ケバブケース) |
description | string | コマンドの機能の簡単な説明 |
フックの形式
フックは、エージェント、Tab、またはワークスペースのイベントをトリガーとして実行される自動化スクリプトです。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 - Tabフック:
beforeTabFileRead,afterTabFileEdit - アプリのライフサイクルフック:
workspaceOpen
詳しくは、Hooksを参照してください。
MCP サーバー
どちらの形式でも、プラグインルートに mcp.json を配置します。Agent Plugins では標準スキーマを使用し、各サーバーのトランスポートを宣言します。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}" } }}サポートされているトランスポート、パス、データディレクトリについては、Agent Plugins MCP リファレンスを参照してください。
詳細については、MCPを参照してください。
ロゴ
ロゴをリポジトリにコミットし、相対パスで指定します。
{ "name": "my-plugin", "logo": "assets/logo.svg"}相対パスは、リポジトリとコミット SHA に基づいて raw.githubusercontent.com の URL に解決されます。たとえば、コミット abc123 時点の acme/plugins リポジトリ内の assets/logo.svg は、次の URL に解決されます。
https://raw.githubusercontent.com/acme/plugins/abc123/my-plugin/assets/logo.svghttp:// または https:// で始まる絶対 GitHub ユーザーコンテンツ URL も使用できます。
Cursor マルチプラグインリポジトリ
1 つの Git リポジトリで、マーケットプレイス マニフェストを使用して複数のプラグインを管理できます。リポジトリのルートにある .cursor-plugin/marketplace.json に配置してください。
マーケットプレイス マニフェストの形式
{ "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" } ]}マーケットプレイス マニフェストのフィールド
| フィールド | 型 | 説明 |
|---|---|---|
name | string | (必須) マーケットプレイスの識別子 (kebab-case) |
owner | object | (必須) name (必須) 、email (任意) |
plugins | array | (必須) プラグインエントリの配列 (最大500件) |
metadata | object | 任意。description、version、pluginRoot (すべてのプラグインソースに共通するプレフィックスパス) |
プラグインエントリのフィールド
plugins 配列の各エントリで指定できる項目は以下のとおりです。
| フィールド | 型 | 説明 |
|---|---|---|
name | string | ** (必須) **プラグイン識別子 (kebab-case) |
source | string or object | プラグインディレクトリへのパス、または path とオプションを含むオブジェクト |
description | string | プラグインの説明 |
version | string | セマンティックバージョン |
author | object | 作成者情報 |
homepage | string | URL |
repository | string | URL |
license | string | ライセンス識別子 |
keywords | array | 検索タグ |
logo | string | ロゴへの相対パスまたは URL |
category | string | プラグインのカテゴリ |
tags | array | 追加のタグ |
skills, rules, agents, commands | string or array | コンポーネントファイルへのパス |
hooks | string or object | フック設定へのパス、またはインライン設定 |
mcpServers | string or object | MCP 設定へのパス、またはインライン設定 |
variables | object | 変数名を宣言する JSON Schema (値はダッシュボードの プラグイン → 設定する で指定) 。plugin.json の使用を推奨します。両方が設定されている場合は、マニフェストの値が優先されます。変数を参照してください。 |
解決の仕組み
"source": "my-plugin" を含むマーケットプレイスエントリの場合:
- パーサーが
my-plugin/.cursor-plugin/plugin.jsonを探します - 見つかった場合、プラグインごとのマニフェストをマーケットプレイスエントリにマージします (マニフェストの値が優先されます)
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 チームによる審査を受けます。提出するには:
プラグインを作成
Agent Plugins 用の有効なルート plugin.json、または
Cursor プラグイン用の .cursor-plugin/plugin.json を追加します。
Git リポジトリで公開
プラグインを公開 Git リポジトリにプッシュします。ロゴもリポジトリにコミットします (任意ですが推奨) 。
プラグインを提出
cursor.com/marketplace/publish にアクセスし、リポジトリへのリンクを提出します。
提出チェックリスト
- プラグインのルートに有効な
plugin.jsonまたは.cursor-plugin/plugin.jsonマニフェストがある nameが一意で、小文字のケバブケースである (例:my-awesome-plugin)descriptionにプラグインの目的が明確に記載されている- 含まれるすべてのコンポーネントに有効なファイルとフロントマターがある
- ロゴがリポジトリにコミットされ、相対パスで参照されている (ロゴを提供する場合)
README.mdに利用方法と設定が記載されている- Agent Plugins が Agent Plugins schemas に準拠している
- 変数を使用する Cursor プラグインでは、
mcp.json内のすべての${VAR}がマニフェストスキーマで宣言されている - マニフェスト内のすべてのパスが相対パスで有効である (
..や絶対パスは不可) - プラグインがローカルでテストされている
- Cursor マルチプラグインリポジトリでは、リポジトリのルートに一意のプラグイン名を含む
.cursor-plugin/marketplace.jsonがある