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