Skip to content

Commit bf795ee

Browse files
ericzakariassoncursoragent
ericzakariasson
and
cursoragent
committed
Cursor plugin template
GitHub template for building and publishing Cursor Marketplace plugins from a single repo. Includes starter-simple and starter-advanced plugin examples. Co-authored-by: Cursor <cursoragent@cursor.com>
0 parents  commit bf795ee

File tree

23 files changed

+798
-0
lines changed

23 files changed

+798
-0
lines changed

‎.cursor-plugin/marketplace.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"name": "cursor-plugin-starters",
3+
"owner": {
4+
"name": "Your Org",
5+
"email": "plugins@example.com"
6+
},
7+
"metadata": {
8+
"description": "Starter marketplace template for Cursor plugins",
9+
"version": "0.1.0",
10+
"pluginRoot": "plugins"
11+
},
12+
"plugins": [
13+
{
14+
"name": "starter-simple",
15+
"source": "./plugins/starter-simple",
16+
"description": "Minimal plugin with rules and skills only"
17+
},
18+
{
19+
"name": "starter-advanced",
20+
"source": "./plugins/starter-advanced",
21+
"description": "Full-featured plugin with rules, skills, agents, commands, hooks, and MCP"
22+
}
23+
]
24+
}

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Environment and secrets
2+
.env
3+
.env.*
4+
!.env.example
5+
6+
# OS and editor
7+
.DS_Store
8+
*.swp
9+
*.swo
10+
11+
# Logs and temp
12+
*.log
13+
tmp/
14+
temp/

‎README.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Cursor plugin template
2+
3+
Build and publish Cursor Marketplace plugins from a single repo.
4+
5+
Two starter plugins are included:
6+
7+
- **starter-simple**: rules and skills only
8+
- **starter-advanced**: rules, skills, agents, commands, hooks, MCP, and scripts
9+
10+
## Repository layout
11+
12+
```text
13+
.
14+
├── .cursor-plugin/
15+
│ └── marketplace.json
16+
├── plugins/
17+
│ ├── starter-simple/
18+
│ │ ├── .cursor-plugin/plugin.json
19+
│ │ ├── rules/
20+
│ │ ├── skills/
21+
│ │ └── assets/
22+
│ └── starter-advanced/
23+
│ ├── .cursor-plugin/plugin.json
24+
│ ├── rules/
25+
│ ├── skills/
26+
│ ├── agents/
27+
│ ├── commands/
28+
│ ├── hooks/
29+
│ ├── mcp.json
30+
│ ├── scripts/
31+
│ └── assets/
32+
├── docs/add-a-plugin.md
33+
└── scripts/validate-template.mjs
34+
```
35+
36+
## Use this template
37+
38+
1. Click **Use this template** > **Create a new repository** on GitHub.
39+
2. Choose owner, repo name, and visibility.
40+
3. Create the repository. Default branch only is recommended.
41+
4. Clone and customize.
42+
43+
## Quick customization
44+
45+
Update these files first:
46+
47+
1. `.cursor-plugin/marketplace.json`
48+
- Set marketplace `name`, `owner`, and `metadata`.
49+
- `metadata.pluginRoot` is optional. Remove it if plugin `source` paths are explicit.
50+
2. `plugins/*/.cursor-plugin/plugin.json`
51+
- Rename `name` to a unique lowercase kebab-case value.
52+
- Replace `author`, `description`, `keywords`, `license`, and `version`.
53+
- Keep logo paths relative (e.g. `assets/logo.svg`).
54+
3. Replace placeholder content:
55+
- `plugins/*/assets/logo.svg`
56+
- Rules, skills, agents, commands, hooks, and scripts
57+
58+
## Single plugin vs multi-plugin
59+
60+
Use **multi-plugin** (current setup) when one repository publishes several related plugins.
61+
62+
For a **single plugin**:
63+
64+
1. Move your plugin folder contents to the repository root.
65+
2. Keep one `.cursor-plugin/plugin.json` at the root plugin directory.
66+
3. Remove `.cursor-plugin/marketplace.json`.
67+
4. Update all component paths accordingly.
68+
69+
## Local validation
70+
71+
```bash
72+
node scripts/validate-template.mjs
73+
```
74+
75+
This checks:
76+
77+
- Marketplace and plugin manifest presence
78+
- Plugin naming format (kebab-case)
79+
- Referenced file paths in manifests
80+
- Frontmatter metadata on rules, skills, agents, and commands
81+
82+
## Submission checklist
83+
84+
- Each plugin has a valid `.cursor-plugin/plugin.json`.
85+
- Plugin names are unique, lowercase, and kebab-case.
86+
- `.cursor-plugin/marketplace.json` entries map to real plugin folders.
87+
- All frontmatter metadata is present in rule, skill, agent, and command files.
88+
- Logos are committed and referenced with relative paths.
89+
- `node scripts/validate-template.mjs` passes.
90+
- README and plugin docs describe behavior and required configuration.
91+
- Repository link is ready for submission to the Cursor team (Slack or `kniparko@anysphere.com`).
92+
93+
## Next steps
94+
95+
- Add or remove plugin folders under `plugins/`.
96+
- Follow `docs/add-a-plugin.md` for adding a new plugin entry.
97+
98+
**Create a new repo from this template:** [Use this template](https://github.com/cursor/plugin-template/generate) or click **Use this template** on the repo page.

‎docs/add-a-plugin.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Add a plugin
2+
3+
Add a new plugin under `plugins/` and register it in `.cursor-plugin/marketplace.json`.
4+
5+
## 1. Create plugin directory
6+
7+
Create a new folder:
8+
9+
```text
10+
plugins/my-new-plugin/
11+
```
12+
13+
Add the required manifest:
14+
15+
```text
16+
plugins/my-new-plugin/.cursor-plugin/plugin.json
17+
```
18+
19+
Example manifest:
20+
21+
```json
22+
{
23+
"name": "my-new-plugin",
24+
"version": "0.1.0",
25+
"description": "Describe what this plugin does",
26+
"author": {
27+
"name": "Your Org"
28+
},
29+
"logo": "assets/logo.svg"
30+
}
31+
```
32+
33+
## 2. Add plugin components
34+
35+
Add only the components you need:
36+
37+
- `rules/` with `.mdc` files (YAML frontmatter required)
38+
- `skills/<skill-name>/SKILL.md` (YAML frontmatter required)
39+
- `agents/*.md` (YAML frontmatter required)
40+
- `commands/*.(md|mdc|markdown|txt)` (frontmatter recommended)
41+
- `hooks/hooks.json` and `scripts/*` for automation hooks
42+
- `mcp.json` for MCP server definitions
43+
- `assets/logo.svg` for marketplace display
44+
45+
## 3. Register in marketplace manifest
46+
47+
Edit `.cursor-plugin/marketplace.json` and append a new entry:
48+
49+
```json
50+
{
51+
"name": "my-new-plugin",
52+
"source": "./plugins/my-new-plugin",
53+
"description": "Describe your plugin"
54+
}
55+
```
56+
57+
`source` is the relative path from the repository root to the plugin folder.
58+
59+
## 4. Validate
60+
61+
```bash
62+
node scripts/validate-template.mjs
63+
```
64+
65+
Fix all reported errors before committing.
66+
67+
## 5. Common pitfalls
68+
69+
- Plugin `name` not kebab-case.
70+
- `source` path in marketplace manifest does not match folder name.
71+
- Missing `.cursor-plugin/plugin.json` in plugin folder.
72+
- Missing frontmatter keys (`name`, `description`) in skills, agents, or commands.
73+
- Rule files missing frontmatter `description`.
74+
- Broken relative paths for `logo`, `hooks`, or `mcpServers` in manifest files.

‎plugins/starter-advanced/.cursor-plugin/plugin.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"name": "starter-advanced",
3+
"version": "0.1.0",
4+
"description": "Full-featured Cursor plugin starter with rules, skills, agents, commands, hooks, and MCP.",
5+
"author": {
6+
"name": "Your Org",
7+
"email": "plugins@example.com"
8+
},
9+
"license": "MIT",
10+
"keywords": ["cursor", "plugin", "rules", "skills", "agents", "commands", "hooks", "mcp"],
11+
"logo": "assets/logo.svg"
12+
}

‎plugins/starter-advanced/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# starter-advanced
2+
3+
Full-featured Cursor plugin starter.
4+
5+
## Included
6+
7+
- `rules/`: coding standards and review checklist
8+
- `skills/code-reviewer/`: code review skill
9+
- `agents/`: security reviewer agent
10+
- `commands/`: deploy-staging command
11+
- `hooks/hooks.json`: hook definitions
12+
- `scripts/`: hook script placeholders
13+
- `mcp.json`: MCP server config

‎plugins/starter-advanced/agents/security-reviewer.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
name: security-reviewer
3+
description: Security-focused reviewer that checks for common vulnerabilities and unsafe defaults.
4+
---
5+
6+
# Security reviewer
7+
8+
You are a security-focused reviewer. Prioritize concrete, high-impact findings.
9+
10+
## Review focus
11+
12+
1. Injection risks in SQL, shell commands, and rendered HTML content.
13+
2. Sensitive data handling (tokens, credentials, personal data).
14+
3. Authentication and authorization checks on privileged operations.
15+
4. Safe defaults in configuration and network-facing behavior.
16+
5. Dependency and supply-chain hygiene where relevant.

‎plugins/starter-advanced/assets/logo.svg‎

Lines changed: 7 additions & 0 deletions
Loading

‎plugins/starter-advanced/commands/deploy-staging.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
name: deploy-staging
3+
description: Deploy the current branch to the staging environment after validation.
4+
---
5+
6+
# Deploy to staging
7+
8+
1. Run project validation checks and tests.
9+
2. Build artifacts for the target environment.
10+
3. Publish or deploy to staging.
11+
4. Run smoke checks and report status.

‎plugins/starter-advanced/hooks/hooks.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"hooks": {
3+
"afterFileEdit": [
4+
{
5+
"command": "./scripts/format-code.sh"
6+
}
7+
],
8+
"beforeShellExecution": [
9+
{
10+
"command": "./scripts/validate-shell.sh",
11+
"matcher": "rm|curl|wget"
12+
}
13+
],
14+
"sessionEnd": [
15+
{
16+
"command": "./scripts/audit.sh"
17+
}
18+
]
19+
}
20+
}

0 commit comments

Comments
 (0)