플러그인 레퍼런스
Cursor 플러그인을 만들고, 구성하고, 제출하는 방법을 안내하는 참고 문서입니다. 플러그인은 규칙, 스킬, 에이전트, 명령, MCP 서버, 훅을 Cursor IDE에서 사용할 수 있는 배포용 번들로 묶습니다.
처음부터 시작한다면 플러그인 템플릿 저장소를 사용하세요.
지원되는 플러그인 형식
Cursor는 매니페스트 위치에 따라 구분되는 두 가지 형식의 플러그인을 로드합니다.
| 형식 | 매니페스트 위치 | 구성 요소 |
|---|---|---|
| Agent 플러그인 (오픈 표준) | 플러그인 루트의 plugin.json | 스킬, MCP 서버 |
| Cursor 플러그인 | .cursor-plugin/plugin.json | 스킬, MCP 서버, 규칙, 에이전트, 명령어, 훅, 변수 |
Agent 플러그인 명세를 준수하는 플러그인은 변경 없이 Cursor에서 로드됩니다. 이 참고 문서의 나머지 부분에서는 표준과 병행하여 개발되며 Cursor 구성 요소 전체를 지원하는 Cursor 플러그인 형식을 설명합니다.
플러그인 구조
플러그인은 매니페스트 파일과 플러그인 리소스를 포함하는 디렉터리입니다.
my-plugin/├── plugin.json # 필수: Agent 플러그인 매니페스트├── skills/ # 에이전트 스킬│ └── code-reviewer/│ └── SKILL.md└── mcp.json # MCP 서버 정의Agent 플러그인 표준은 이식 가능한 스킬과 MCP 서버를 정의합니다. 전체 패키지 및 스키마 참고 자료는 Agent 플러그인 작성 가이드를 참조하세요.
Cursor 플러그인 매니페스트
모든 Cursor 플러그인에는 .cursor-plugin/plugin.json 매니페스트 파일이 필요합니다. 아래
섹션에서는 Cursor 플러그인의 필드, 구성 요소 및 마켓플레이스
기능을 설명합니다. 루트 Agent 플러그인 매니페스트는
표준 매니페스트 참고 문서를 참조하세요.
필수 필드
| 필드 | 유형 | 설명 |
|---|---|---|
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} 자리표시자에 값이 대입됩니다. Variables를 참조하세요. |
매니페스트 예시
{ "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 | 불리언 | 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 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)스킬 프론트매터 필드
| 필드 | 유형 | 설명 |
|---|---|---|
name | string | 스킬 식별자(소문자, 케밥 케이스) |
description | string | 스킬의 기능 및 사용 시점에 대한 설명 |
전체 문서는 Skills를 참조하세요.
에이전트 형식
에이전트는 사용자 정의 에이전트의 동작과 프롬프트를 정의하는 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 sanitizationAgent 프론트매터 필드
| 필드 | 유형 | 설명 |
|---|---|---|
name | 문자열 | Agent 식별자(소문자 케밥 케이스) |
description | 문자열 | Agent의 용도에 대한 간단한 설명 |
Commands 형식
Commands는 에이전트가 실행할 수 있는 작업을 정의하는 Markdown 또는 텍스트 파일입니다. commands/ 디렉터리에 저장하세요.
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 | 명령의 기능을 간략히 설명 |
훅 형식
훅은 Agent, 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 플러그인은
표준 스키마를 사용하며 각 서버의 전송 방식을 선언합니다. 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 플러그인 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.svg절대 GitHub 사용자 콘텐츠 URL(http:// 또는 https://로 시작하는 URL)도 사용할 수 있습니다.
Cursor 다중 플러그인 저장소
단일 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 또는 object | 플러그인 디렉터리 경로 또는 path와 옵션이 포함된 object |
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 또는 array | component 파일 경로 |
hooks | string 또는 object | 훅 config 경로 또는 inline config |
mcpServers | string 또는 object | MCP config 경로 또는 inline config |
variables | object | 변수 이름을 선언하는 JSON Schema(값은 대시보드의 플러그인 → 구성하다에서 설정). plugin.json 사용을 권장합니다. 둘 다 설정된 경우 manifest 값이 우선합니다. Variables를 참조하세요. |
해석 방식
"source": "my-plugin"인 marketplace 항목의 경우:
- parser가
my-plugin/.cursor-plugin/plugin.json파일을 찾습니다. - 파일을 찾으면 플러그인별 매니페스트를 marketplace 항목과 머지하며, 매니페스트 값이 우선 적용됩니다.
- 매니페스트에 path가 지정되어 있으면 이를 사용하고, 그렇지 않으면 folder-based discovery를 fallback으로 사용해
my-plugin/directory 내에서 컴포넌트 검색을 실행합니다.
다중 플러그인 리포지토리 예시
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 플러그인의 경우 루트에 유효한 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 플러그인이 Agent Plugins 스키마를 준수함
- 변수를 사용하는 Cursor 플러그인은
mcp.json의 모든${VAR}를 매니페스트 스키마에 선언함 - 매니페스트의 모든 경로가 상대 경로이고 유효함(
..및 절대 경로 없음) - 플러그인을 로컬에서 테스트함
- Cursor 다중 플러그인 리포지토리의 루트에 고유한 플러그인 이름이 포함된
.cursor-plugin/marketplace.json이 있음