From bbb10da31d6013fe350546477cda8bb26da4e8fa Mon Sep 17 00:00:00 2001 From: ericzakariasson Date: Thu, 22 Jan 2026 17:54:49 -0800 Subject: [PATCH] Initial commit: Cursor plugin specification and boilerplate - Add plugin specification README with complete schema documentation - Include boilerplate plugin demonstrating all components: - Rules (.mdc files with frontmatter) - Agents (specialized subagent definitions) - Skills (self-contained capabilities with SKILL.md) - Hooks (pre/post event automation) - MCP servers (external tool integrations) - Extensions directory structure Co-authored-by: Cursor --- plugins/README.md | 99 +++++++++++++++++++ plugins/boilerplate/.cursor/plugin.json | 21 ++++ plugins/boilerplate/CHANGELOG.md | 25 +++++ plugins/boilerplate/LICENSE | 21 ++++ plugins/boilerplate/README.md | 67 +++++++++++++ plugins/boilerplate/agents/example-agent.md | 36 +++++++ plugins/boilerplate/extensions/.gitkeep | 1 + plugins/boilerplate/hooks/hooks.json | 20 ++++ plugins/boilerplate/mcp.json | 19 ++++ plugins/boilerplate/rules/example-rule.mdc | 36 +++++++ plugins/boilerplate/scripts/lint.sh | 23 +++++ plugins/boilerplate/scripts/mcp-server.js | 68 +++++++++++++ .../boilerplate/skills/example-skill/SKILL.md | 44 +++++++++ 13 files changed, 480 insertions(+) create mode 100644 plugins/README.md create mode 100644 plugins/boilerplate/.cursor/plugin.json create mode 100644 plugins/boilerplate/CHANGELOG.md create mode 100644 plugins/boilerplate/LICENSE create mode 100644 plugins/boilerplate/README.md create mode 100644 plugins/boilerplate/agents/example-agent.md create mode 100644 plugins/boilerplate/extensions/.gitkeep create mode 100644 plugins/boilerplate/hooks/hooks.json create mode 100644 plugins/boilerplate/mcp.json create mode 100644 plugins/boilerplate/rules/example-rule.mdc create mode 100755 plugins/boilerplate/scripts/lint.sh create mode 100644 plugins/boilerplate/scripts/mcp-server.js create mode 100644 plugins/boilerplate/skills/example-skill/SKILL.md diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 0000000..3ef0519 --- /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": "you@example.com" + }, + "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 +``` + +Or from a marketplace: + +```bash +agent install @ +``` + +## 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 0000000..ade3f1e --- /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": "you@example.com" + }, + "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 0000000..58d1b42 --- /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 0000000..a039926 --- /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 0000000..27e7e61 --- /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 0000000..ce0e889 --- /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 0000000..c6ce3f4 --- /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 0000000..85f9f87 --- /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 0000000..aaf5deb --- /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 0000000..198c5d0 --- /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 => { + 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 0000000..980c9cd --- /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 0000000..38d879e --- /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 0000000..3f0fd25 --- /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 -- 2.51.2