Cursor plugin specification and official plugins
TypeScript
Initial commit: Cursor plugin specification and boilerplate
ericzakariassonbbb10da31d60
diff --git a/plugins/README.md b/plugins/README.mdnew file mode 100644index 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 submittingdiff --git a/plugins/boilerplate/.cursor/plugin.json b/plugins/boilerplate/.cursor/plugin.jsonnew file mode 100644index 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.mdnew file mode 100644index 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 functionalitydiff --git a/plugins/boilerplate/LICENSE b/plugins/boilerplate/LICENSEnew file mode 100644index 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.mdnew file mode 100644index 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++MITdiff --git a/plugins/boilerplate/agents/example-agent.md b/plugins/boilerplate/agents/example-agent.mdnew file mode 100644index 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 themdiff --git a/plugins/boilerplate/extensions/.gitkeep b/plugins/boilerplate/extensions/.gitkeepnew file mode 100644index 00000000..c6ce3f45--- /dev/null+++ b/plugins/boilerplate/extensions/.gitkeep@@ -0,0 +1 @@+# Place .vsix extension files in this directorydiff --git a/plugins/boilerplate/hooks/hooks.json b/plugins/boilerplate/hooks/hooks.jsonnew file mode 100644index 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.jsonnew file mode 100644index 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.mdcnew file mode 100644index 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.shnew file mode 100755index 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.jsnew file mode 100644index 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.mdnew file mode 100644index 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