my-plugin/
├── plugin.json            # 必需：Agent Plugins 清單
├── skills/                # 智能體技能
│   └── code-reviewer/
│       └── SKILL.md
└── mcp.json               # MCP 服務器定義

my-plugin/
├── .cursor-plugin/
│   └── plugin.json        # 必需：Cursor 插件清單
├── rules/                 # Cursor 規則（.mdc 文件）
│   ├── coding-standards.mdc
│   └── review-checklist.mdc
├── skills/                # 智能體技能
│   └── code-reviewer/
│       └── SKILL.md
├── agents/                # 自定義智能體配置
│   └── security-reviewer.md
├── commands/              # 可由智能體執行的命令
│   └── deploy.md
├── hooks/                 # 鉤子定義
│   └── hooks.json
├── mcp.json               # MCP 服務器定義
├── assets/                # 徽標和靜態資源
│   └── logo.svg
├── scripts/               # 鉤子和實用腳本
│   └── format-code.py
└── README.md

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

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

### 規則 frontmatter 字段

| 字段            | 類型             | 描述                                        |
| :------------ | :------------- | :---------------------------------------- |
| `description` | string         | 規則功能的簡要描述                                 |
| `alwaysApply` | boolean        | 如爲 `true`，規則將應用於所有文件；如爲 `false`，可按需調用該規則。 |
| `globs`       | string 或 array | 規則適用的文件模式 (例如 `"**/*.ts"`)                |

完整文檔請參閱 [Rules](https://cursor.com/docs/rules)。

## 技能格式

技能是在 `SKILL.md` 文件中定義的專門能力。每個技能在 `skills/` 下都有自己的目錄。

技能需要包含帶元數據的 YAML frontmatter：
```markdown title="skills/api-designer/SKILL.md"
---
name: api-designer
description: Design RESTful APIs following OpenAPI 3.0 specification.
  Use when designing new API endpoints, reviewing API contracts,
  or generating API documentation.
---

# API 設計器技能

## 何時使用

- 設計新的 API 端點
- 評審 API 合約
- 生成 API 文檔

## 說明

1. 資源命名遵循 REST 約定
2. 使用恰當的 HTTP 方法（GET、POST、PUT、DELETE、PATCH）
3. 使用標準 HTTP 狀態碼返回合適的錯誤響應
4. 使用 OpenAPI 3.0 規範爲所有端點編寫文檔
5. 使用一致的命名約定（URL 用 kebab-case，JSON 用 camelCase）

### 智能體 frontmatter 字段

| 字段            | 類型     | 描述                       |
| :------------ | :----- | :----------------------- |
| `name`        | string | 智能體標識符 (小寫字母，kebab-case) |
| `description` | string | 智能體用途的簡要說明               |

## 命令格式

命令是定義智能體可執行操作的 Markdown 或文本文件。請將其放在 `commands/` 目錄中。

命令支持 `.md`、`.mdc`、`.markdown` 和 `.txt` 擴展名，也可包含 YAML frontmatter：
```markdown title="commands/deploy-staging.md"
---
name: deploy-staging
description: Deploy the current branch to the staging environment
---

# Deploy to staging

Steps to deploy to staging:
1. Run tests
2. Build the project
3. Push to staging branch

### 可用鉤子事件

- **智能體鉤子**：`sessionStart`、`sessionEnd`、`preToolUse`、`postToolUse`、`postToolUseFailure`、`subagentStart`、`subagentStop`、`beforeShellExecution`、`afterShellExecution`、`beforeMCPExecution`、`afterMCPExecution`、`beforeReadFile`、`afterFileEdit`、`beforeSubmitPrompt`、`preCompact`、`stop`、`afterAgentResponse`、`afterAgentThought`
- **Tab 鉤子**：`beforeTabFileRead`、`afterTabFileEdit`
- **應用生命週期鉤子**：`workspaceOpen`

完整文檔請參閱 [Hooks](https://cursor.com/docs/hooks)。

## MCP 服務器

兩種格式都將 `mcp.json` 放在插件根目錄。Agent Plugins 使用該標準的
schema，並聲明每個服務器的傳輸協議。Cursor 插件可以使用
Cursor 變量，並根據 `command` 或 `url` 推斷傳輸協議。

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

`${POSTGRES_URL}` 是[插件變量](https://cursor.com/cn/docs/reference/plugins.md#variables)佔位符 (不是 shell `${env:...}`) 。請在 `plugin.json` 的 `variables` 下聲明變量名；插件配置中僅保留佔位符，並在儀表盤的 **插件** → **配置** 中設置其值。由插件管理的 MCP 配置在儀表盤中爲只讀。

完整文檔請參閱 [MCP](https://cursor.com/docs/mcp)。

## 徽標

將徽標文件提交到代碼倉庫，並通過相對路徑引用：
```json
{
  "name": "my-plugin",
  "logo": "assets/logo.svg"
}

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

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

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