[Go to site: main page, start]

Skip to main content

Command Palette

Search for a command to run...

시작하기

플러그인 레퍼런스

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 플러그인 매니페스트는 표준 매니페스트 참고 문서를 참조하세요.

필수 필드

필드유형설명
namestring플러그인 식별자입니다. 소문자 케밥 표기법(영숫자, 하이픈, 마침표)을 사용해야 합니다. 영숫자로 시작하고 끝나야 합니다. 예: my-plugin, prompts.chat

선택 필드

필드유형설명
descriptionstring플러그인에 대한 간략한 설명
versionstring시맨틱 버전(예: 1.0.0)
authorobject작성자 정보: name(필수), email(선택)
homepagestring플러그인 홈페이지 URL
repositorystring플러그인 저장소 URL
licensestring라이선스 식별자(예: MIT)
keywordsarray검색 및 분류용 태그
logostring리포지토리 내 로고 파일의 상대 경로(예: assets/logo.svg) 또는 절대 URL입니다. 상대 경로는 raw.githubusercontent.com URL로 변환됩니다. 권장: 로고를 리포지토리에 커밋하고 상대 경로를 사용하세요.
rulesstring or array규칙 파일 또는 디렉터리 경로
agentsstring or array에이전트 파일 또는 디렉터리 경로
skillsstring or array스킬 디렉터리 경로
commandsstring or array명령 파일 또는 디렉터리 경로
hooksstring or object훅 구성 파일 경로 또는 인라인 훅 구성
mcpServersstring, object, or arrayMCP 구성 파일 경로, 인라인 MCP 서버 구성 또는 이들의 배열입니다. 기본 mcp.json 디스커버리를 재정의합니다.
variablesobject변수 이름(토큰, 연결 문자열)을 선언하는 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} 자리표시자만 포함하세요.

.cursor-plugin/plugin.json
{  "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"]  }}
mcp.json
{  "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 프론트매터가 필요합니다:

rules/prefer-const.mdc
---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`.

규칙 프론트매터 필드

필드유형설명
descriptionstring규칙의 기능에 대한 간단한 설명
alwaysApply불리언true이면 규칙이 모든 파일에 적용됩니다. false이면 필요할 때 규칙을 사용할 수 있습니다.
globsstring 또는 array규칙이 적용되는 파일 패턴(예: "**/*.ts")

자세한 내용은 규칙을 참조하세요.

스킬 형식

스킬은 SKILL.md 파일에 정의된 특화된 기능입니다. 각 스킬은 skills/ 아래의 별도 디렉터리에 위치합니다.

스킬에는 메타데이터를 포함하는 YAML 프론트매터가 필요합니다:

skills/api-designer/SKILL.md
---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)

스킬 프론트매터 필드

필드유형설명
namestring스킬 식별자(소문자, 케밥 케이스)
descriptionstring스킬의 기능 및 사용 시점에 대한 설명

전체 문서는 Skills를 참조하세요.

에이전트 형식

에이전트는 사용자 정의 에이전트의 동작과 프롬프트를 정의하는 Markdown 파일입니다. agents/ 디렉터리에 저장하세요.

에이전트에는 메타데이터를 포함하는 YAML 프론트매터가 필요합니다:

agents/security-reviewer.md
---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 프론트매터 필드

필드유형설명
name문자열Agent 식별자(소문자 케밥 케이스)
description문자열Agent의 용도에 대한 간단한 설명

Commands 형식

Commands는 에이전트가 실행할 수 있는 작업을 정의하는 Markdown 또는 텍스트 파일입니다. commands/ 디렉터리에 저장하세요.

Commands는 .md, .mdc, .markdown, .txt 확장자를 지원합니다. YAML 프론트매터를 포함할 수 있습니다:

commands/deploy-staging.md
---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

명령 프론트매터 필드

필드유형설명
namestring명령 식별자(소문자, 케밥 케이스)
descriptionstring명령의 기능을 간략히 설명

훅 형식

훅은 Agent, Tab 또는 워크스페이스 이벤트에 의해 트리거되는 자동화 스크립트입니다. hooks/hooks.json에서 정의합니다:

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을 기반으로 전송 방식을 추론합니다.

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

지원되는 전송 방식, 경로, 데이터 디렉터리는 Agent 플러그인 MCP 참고 문서를 참조하세요.

전체 문서는 MCP를 참조하세요.

로고

로고를 저장소에 커밋한 후 상대 경로로 참조하세요:

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

상대 경로는 저장소와 커밋 SHA를 기준으로 raw.githubusercontent.com URL로 해석됩니다. 예를 들어 커밋 abc123acme/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"    }  ]}

마켓플레이스 매니페스트 필드

필드유형설명
namestring(필수) 마켓플레이스 식별자(kebab-case)
ownerobject(필수) name(필수), email(선택)
pluginsarray(필수) 플러그인 항목 배열(최대 500개)
metadataobject선택 사항. description, version, pluginRoot(모든 플러그인 소스의 접두사 경로)

플러그인 항목 필드

plugins 배열의 각 항목에서 지원하는 필드는 다음과 같습니다.

필드유형설명
namestring(필수) 플러그인 식별자(kebab-case)
sourcestring 또는 object플러그인 디렉터리 경로 또는 path와 옵션이 포함된 object
descriptionstring플러그인 설명
versionstring시맨틱 버전
authorobject작성자 정보
homepagestringURL
repositorystringURL
licensestring라이선스 식별자
keywordsarray검색 태그
logostring로고의 상대 경로 또는 URL
categorystring플러그인 카테고리
tagsarray추가 태그
skills, rules, agents, commandsstring 또는 arraycomponent 파일 경로
hooksstring 또는 object훅 config 경로 또는 inline config
mcpServersstring 또는 objectMCP config 경로 또는 inline config
variablesobject변수 이름을 선언하는 JSON Schema(값은 대시보드의 플러그인구성하다에서 설정). plugin.json 사용을 권장합니다. 둘 다 설정된 경우 manifest 값이 우선합니다. Variables를 참조하세요.

해석 방식

"source": "my-plugin"인 marketplace 항목의 경우:

  1. parser가 my-plugin/.cursor-plugin/plugin.json 파일을 찾습니다.
  2. 파일을 찾으면 플러그인별 매니페스트를 marketplace 항목과 머지하며, 매니페스트 값이 우선 적용됩니다.
  3. 매니페스트에 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 팀에서 검토합니다. 제출 방법은 다음과 같습니다.

1

플러그인 생성

Agent 플러그인의 경우 루트에 유효한 plugin.json을, Cursor 플러그인의 경우 .cursor-plugin/plugin.json을 추가합니다.

2

Git 저장소에 호스팅

플러그인을 공개 Git 저장소에 푸시합니다. 로고도 저장소에 커밋하세요(선택 사항이지만 권장됨).

3

플러그인 제출

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이 있음