Skip to content

Cursor plugin specification and official plugins

TypeScript

Initial commit: Cursor plugin specification and boilerplate

ericzakariassonbbb10da31d60
diff --git a/plugins/README.md b/plugins/README.md
new file mode 100644
index 00000000..3ef0519b
--- /dev/null
+++ b/plugins/README.md
@@ -0,0 +1,99 @@
+# Cursor Plugins
+
+This directory contains official plugins for Cursor.
+
+## Plugin Structure
+
+Each plugin follows a standard structure:
+
+```
+plugin-name/
+├── .cursor/
+│ └── plugin.json # Plugin manifest (required)
+├── README.md # Plugin documentation
+├── rules/ # Cursor rules (.mdc files)
+├── agents/ # Subagents (markdown files)
+├── skills/ # Agent skills (directories with SKILL.md)
+├── hooks/
+│ └── hooks.json # Hook configuration
+├── mcp.json # MCP server definitions (optional)
+├── extensions/ # VS Code extensions (.vsix files)
+├── scripts/ # Utility scripts for hooks
+├── LICENSE
+└── CHANGELOG.md
+```
+
+## Plugin Components
+
+| Component | Location | Purpose |
+|:----------------|:----------------------|:-----------------------------------------|
+| **Manifest** | `.cursor/plugin.json` | Required metadata file |
+| **Rules** | `rules/` | Cursor rules (.mdc files) |
+| **Agents** | `agents/` | Subagent Markdown files |
+| **Skills** | `skills/` | Agent Skills with SKILL.md files |
+| **Hooks** | `hooks/hooks.json` | Hook configuration |
+| **MCP servers** | `mcp.json` | MCP server definitions |
+| **Extensions** | `extensions/` | VS Code extension bundles (.vsix files) |
+
+## Creating a Plugin
+
+1. Create a new directory under `plugins/`
+2. Add a `.cursor/plugin.json` manifest file
+3. Add your components (rules, agents, skills, hooks, etc.)
+4. Add a `README.md` documenting your plugin
+
+See the `boilerplate` directory for a complete example.
+
+## Plugin Manifest
+
+The `.cursor/plugin.json` manifest is required and defines your plugin's metadata:
+
+```json
+{
+ "name": "my-plugin",
+ "version": "1.0.0",
+ "description": "A brief description of what your plugin does",
+ "author": {
+ "name": "Your Name",
+ "email": "[email protected]"
+ },
+ "license": "MIT",
+ "keywords": ["example"],
+ "agents": "./agents/",
+ "skills": "./skills/",
+ "rules": "./rules/",
+ "hooks": "./hooks/hooks.json",
+ "mcpServers": "./mcp.json",
+ "extensions": "./extensions/"
+}
+```
+
+## Available Plugins
+
+| Plugin | Description |
+|:--------------|:---------------------------------------------------------|
+| `boilerplate` | Complete example plugin demonstrating all components |
+
+## Installation
+
+Plugins can be installed via CLI:
+
+```bash
+agent install <plugin-name>
+```
+
+Or from a marketplace:
+
+```bash
+agent install <plugin-name>@<marketplace>
+```
+
+## Contributing
+
+When adding a new plugin:
+
+1. Follow the standard directory structure
+2. Include a comprehensive README.md
+3. Use semantic versioning (MAJOR.MINOR.PATCH)
+4. Include a LICENSE file
+5. Test your plugin thoroughly before submitting
diff --git a/plugins/boilerplate/.cursor/plugin.json b/plugins/boilerplate/.cursor/plugin.json
new file mode 100644
index 00000000..ade3f1e1
--- /dev/null
+++ b/plugins/boilerplate/.cursor/plugin.json
@@ -0,0 +1,21 @@
+{
+ "name": "boilerplate",
+ "version": "1.0.0",
+ "description": "A boilerplate Cursor plugin demonstrating all available plugin components",
+ "author": {
+ "name": "Your Name",
+ "email": "[email protected]"
+ },
+ "homepage": "https://github.com/your-org/boilerplate-plugin",
+ "repository": "https://github.com/your-org/boilerplate-plugin",
+ "license": "MIT",
+ "keywords": ["boilerplate", "template", "example"],
+ "category": "utilities",
+ "tags": ["starter", "template"],
+ "agents": "./agents/",
+ "skills": "./skills/",
+ "rules": "./rules/",
+ "hooks": "./hooks/hooks.json",
+ "mcpServers": "./mcp.json",
+ "extensions": "./extensions/"
+}
diff --git a/plugins/boilerplate/CHANGELOG.md b/plugins/boilerplate/CHANGELOG.md
new file mode 100644
index 00000000..58d1b42d
--- /dev/null
+++ b/plugins/boilerplate/CHANGELOG.md
@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this plugin will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-01-22
+
+### Added
+- Initial plugin structure with `.cursor/plugin.json` manifest
+- Example rule in `rules/example-rule.mdc`
+- Example agent in `agents/example-agent.md`
+- Example skill in `skills/example-skill/SKILL.md`
+- Hook configuration in `hooks/hooks.json`
+- MCP server configuration in `mcp.json`
+- Utility scripts in `scripts/`
+- MIT License
+- This changelog
+
+### Notes
+- This is a boilerplate plugin for demonstration purposes
+- Replace example components with your actual plugin functionality
diff --git a/plugins/boilerplate/LICENSE b/plugins/boilerplate/LICENSE
new file mode 100644
index 00000000..a039926f
--- /dev/null
+++ b/plugins/boilerplate/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/plugins/boilerplate/README.md b/plugins/boilerplate/README.md
new file mode 100644
index 00000000..27e7e610
--- /dev/null
+++ b/plugins/boilerplate/README.md
@@ -0,0 +1,67 @@
+# Boilerplate Plugin
+
+A boilerplate Cursor plugin demonstrating all available plugin components.
+
+## Installation
+
+```bash
+agent install boilerplate
+```
+
+## Components
+
+| Component | Description |
+|:----------|:------------|
+| **Rules** | Cursor rules for coding standards and conventions |
+| **Agents** | Specialized subagents for specific tasks |
+| **Skills** | Reusable agent skills with tools and scripts |
+| **Hooks** | Pre/post execution hooks for automation |
+| **MCP Servers** | Model Context Protocol server integrations |
+| **Extensions** | VS Code extension bundles |
+
+## Directory Structure
+
+```
+boilerplate/
+├── .cursor/
+│ └── plugin.json # Plugin manifest (required)
+├── rules/ # Cursor rules
+│ └── example-rule.mdc
+├── agents/ # Subagent definitions
+│ └── example-agent.md
+├── skills/ # Agent skills
+│ └── example-skill/
+│ └── SKILL.md
+├── hooks/ # Hook configurations
+│ └── hooks.json
+├── mcp.json # MCP server definitions
+├── extensions/ # VS Code extensions (.vsix)
+├── scripts/ # Utility scripts for hooks
+├── LICENSE
+├── CHANGELOG.md
+└── README.md
+```
+
+## Rules
+
+Rules in the `rules/` directory are automatically applied based on their configuration. Each rule is a `.mdc` file with frontmatter defining when it applies.
+
+## Agents
+
+Agents in the `agents/` directory define specialized subagents that can be invoked for specific tasks.
+
+## Skills
+
+Skills in the `skills/` directory are self-contained capabilities that agents can use. Each skill has a `SKILL.md` file that describes what it does and how to use it.
+
+## Hooks
+
+Hooks in `hooks/hooks.json` define automation that runs before or after certain events.
+
+## MCP Servers
+
+MCP server configurations in `mcp.json` define integrations with external tools and services.
+
+## License
+
+MIT
diff --git a/plugins/boilerplate/agents/example-agent.md b/plugins/boilerplate/agents/example-agent.md
new file mode 100644
index 00000000..ce0e8892
--- /dev/null
+++ b/plugins/boilerplate/agents/example-agent.md
@@ -0,0 +1,36 @@
+# Code Reviewer Agent
+
+You are a code review specialist focused on providing actionable, constructive feedback.
+
+## Responsibilities
+
+1. **Code Quality** - Identify potential bugs, logic errors, and edge cases
+2. **Best Practices** - Suggest improvements based on language/framework conventions
+3. **Security** - Flag potential security vulnerabilities
+4. **Performance** - Identify performance bottlenecks and optimization opportunities
+5. **Readability** - Suggest improvements for code clarity and maintainability
+
+## Review Process
+
+1. First, understand the context and purpose of the code
+2. Identify the most critical issues first (bugs, security)
+3. Then address code quality and style concerns
+4. Provide specific, actionable suggestions with examples
+5. Be constructive and explain the reasoning behind suggestions
+
+## Output Format
+
+For each finding, provide:
+- **Severity**: Critical / Warning / Suggestion
+- **Location**: File and line number
+- **Issue**: Clear description of the problem
+- **Recommendation**: Specific fix or improvement
+- **Example**: Code snippet showing the fix (when applicable)
+
+## Guidelines
+
+- Be respectful and constructive
+- Focus on the code, not the author
+- Prioritize issues by impact
+- Provide clear explanations for non-obvious suggestions
+- Acknowledge good patterns when you see them
diff --git a/plugins/boilerplate/extensions/.gitkeep b/plugins/boilerplate/extensions/.gitkeep
new file mode 100644
index 00000000..c6ce3f45
--- /dev/null
+++ b/plugins/boilerplate/extensions/.gitkeep
@@ -0,0 +1 @@
+# Place .vsix extension files in this directory
diff --git a/plugins/boilerplate/hooks/hooks.json b/plugins/boilerplate/hooks/hooks.json
new file mode 100644
index 00000000..85f9f873
--- /dev/null
+++ b/plugins/boilerplate/hooks/hooks.json
@@ -0,0 +1,20 @@
+{
+ "$schema": "https://cursor.com/schemas/hooks.json",
+ "hooks": [
+ {
+ "name": "pre-commit-lint",
+ "description": "Run linting before commits",
+ "trigger": "pre-commit",
+ "command": "./scripts/lint.sh",
+ "enabled": true
+ },
+ {
+ "name": "post-save-format",
+ "description": "Format files after saving",
+ "trigger": "post-save",
+ "pattern": "**/*.{ts,tsx,js,jsx}",
+ "command": "npx prettier --write",
+ "enabled": false
+ }
+ ]
+}
diff --git a/plugins/boilerplate/mcp.json b/plugins/boilerplate/mcp.json
new file mode 100644
index 00000000..aaf5deb4
--- /dev/null
+++ b/plugins/boilerplate/mcp.json
@@ -0,0 +1,19 @@
+{
+ "$schema": "https://cursor.com/schemas/mcp.json",
+ "mcpServers": {
+ "example-server": {
+ "command": "node",
+ "args": ["./scripts/mcp-server.js"],
+ "description": "Example MCP server for demonstration",
+ "env": {
+ "NODE_ENV": "production"
+ }
+ },
+ "external-api": {
+ "command": "npx",
+ "args": ["-y", "@example/mcp-server"],
+ "description": "External API integration via MCP",
+ "disabled": true
+ }
+ }
+}
diff --git a/plugins/boilerplate/rules/example-rule.mdc b/plugins/boilerplate/rules/example-rule.mdc
new file mode 100644
index 00000000..198c5d06
--- /dev/null
+++ b/plugins/boilerplate/rules/example-rule.mdc
@@ -0,0 +1,36 @@
+---
+description: Example rule demonstrating Cursor rule structure
+globs:
+ - "**/*.ts"
+ - "**/*.tsx"
+alwaysApply: false
+---
+
+# Example Coding Standards
+
+When working with TypeScript files, follow these conventions:
+
+1. **Use explicit types** - Avoid `any` unless absolutely necessary
+2. **Prefer `const` over `let`** - Use immutable bindings when possible
+3. **Use async/await** - Prefer async/await over raw Promises
+4. **Handle errors explicitly** - Always catch and handle errors appropriately
+
+## Example
+
+```typescript
+// ✅ Good
+const fetchData = async (id: string): Promise<Data> => {
+ try {
+ const response = await api.get(`/data/${id}`);
+ return response.data;
+ } catch (error) {
+ console.error('Failed to fetch data:', error);
+ throw error;
+ }
+};
+
+// ❌ Bad
+const fetchData = (id) => {
+ return api.get('/data/' + id).then(r => r.data);
+};
+```
diff --git a/plugins/boilerplate/scripts/lint.sh b/plugins/boilerplate/scripts/lint.sh
new file mode 100755
index 00000000..980c9cd0
--- /dev/null
+++ b/plugins/boilerplate/scripts/lint.sh
@@ -0,0 +1,23 @@
+#!/bin/bash
+# Pre-commit lint hook script
+# This script runs linting checks before commits
+
+set -e
+
+echo "Running lint checks..."
+
+# TypeScript/JavaScript linting
+if command -v npx &> /dev/null; then
+ if [ -f "package.json" ]; then
+ echo "Running ESLint..."
+ npx eslint . --ext .ts,.tsx,.js,.jsx --max-warnings 0 || exit 1
+ fi
+fi
+
+# Python linting
+if command -v ruff &> /dev/null; then
+ echo "Running Ruff..."
+ ruff check . || exit 1
+fi
+
+echo "Lint checks passed!"
diff --git a/plugins/boilerplate/scripts/mcp-server.js b/plugins/boilerplate/scripts/mcp-server.js
new file mode 100644
index 00000000..38d879ea
--- /dev/null
+++ b/plugins/boilerplate/scripts/mcp-server.js
@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Example MCP Server
+ *
+ * This is a minimal MCP server demonstrating the structure.
+ * Replace with your actual MCP server implementation.
+ */
+
+const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+
+const server = new Server(
+ {
+ name: 'example-mcp-server',
+ version: '1.0.0',
+ },
+ {
+ capabilities: {
+ tools: {},
+ },
+ }
+);
+
+// Register example tool
+server.setRequestHandler('tools/list', async () => {
+ return {
+ tools: [
+ {
+ name: 'example_tool',
+ description: 'An example tool that echoes input',
+ inputSchema: {
+ type: 'object',
+ properties: {
+ message: {
+ type: 'string',
+ description: 'Message to echo',
+ },
+ },
+ required: ['message'],
+ },
+ },
+ ],
+ };
+});
+
+server.setRequestHandler('tools/call', async (request) => {
+ if (request.params.name === 'example_tool') {
+ const message = request.params.arguments?.message || 'Hello, World!';
+ return {
+ content: [
+ {
+ type: 'text',
+ text: `Echo: ${message}`,
+ },
+ ],
+ };
+ }
+ throw new Error(`Unknown tool: ${request.params.name}`);
+});
+
+// Start server
+async function main() {
+ const transport = new StdioServerTransport();
+ await server.connect(transport);
+ console.error('Example MCP server running on stdio');
+}
+
+main().catch(console.error);
diff --git a/plugins/boilerplate/skills/example-skill/SKILL.md b/plugins/boilerplate/skills/example-skill/SKILL.md
new file mode 100644
index 00000000..3f0fd25a
--- /dev/null
+++ b/plugins/boilerplate/skills/example-skill/SKILL.md
@@ -0,0 +1,44 @@
+# Example Skill
+
+A demonstration skill showing the structure and capabilities of Cursor Agent Skills.
+
+## When to Use
+
+Use this skill when the user asks to:
+- Demonstrate skill functionality
+- Test skill integration
+- Learn about skill structure
+
+## Instructions
+
+When this skill is activated:
+
+1. **Acknowledge** - Confirm the skill has been activated
+2. **Gather Context** - Understand what the user needs
+3. **Execute** - Perform the requested action
+4. **Report** - Provide a summary of what was done
+
+## Available Tools
+
+This skill can use:
+- File reading and writing tools
+- Shell commands for system operations
+- Search tools for codebase exploration
+
+## Example Usage
+
+User: "Use the example skill to analyze this file"
+
+Response: The skill will read the file, analyze its contents, and provide relevant insights based on the skill's capabilities.
+
+## Configuration
+
+This skill accepts the following configuration:
+- `verbose`: Enable detailed output (default: false)
+- `format`: Output format - "text" | "json" | "markdown" (default: "markdown")
+
+## Notes
+
+- Skills are self-contained and should not depend on external state
+- Always provide clear feedback about what the skill is doing
+- Handle errors gracefully and inform the user of any issues