Building Plugins

Plugin Structure

A Cursorist plugin lives in a project directory with a manifest and component directories. The manifest defines metadata; component directories hold the actual content.

Manifest Location

Place your manifest at:

.cursor-plugin/plugin.json

Manifest Schema

{
  "name": "my-team-starter",
  "version": "0.1.0",
  "description": "Project bootstrap standards for this team",
  "author": "acme",
  "components": ["rules", "skills", "commands", "mcp"]
}

Field	Type	Required	Description
`name`	string	Yes	Display name of the plugin
`version`	string	Yes	Semantic version (e.g. `1.0.0`)
`description`	string	Yes	Short description
`author`	string	No	Author or organization
`components`	string[]	Yes	At least one of: `rules`, `skills`, `commands`, `mcp`, `agents`, `hooks`

Component Directories

Each component type maps to a directory at the plugin root. Only directories listed in components are included when deploying.

Directory	File Types	Purpose
`rules/`	`.mdc`	Cursor rules with frontmatter
`skills/`	`SKILL.md`	Agent skills
`commands/`	`.md`	Command documentation
`mcp/`	`.mcp.json`	MCP server configuration
`agents/`	varies	Agent definitions
`hooks/`	varies	Hook scripts

Example Layout

my-plugin/
├── .cursor-plugin/
│   └── plugin.json
├── rules/
│   ├── project-standards.mdc
│   └── code-review.mdc
├── skills/
│   └── project-lead/
│       └── SKILL.md
├── commands/
│   └── refresh-standards.md
└── mcp/
    └── cursorist.mcp.json

Writing Rules

Rules use .mdc (Markdown with frontmatter) format.

---
description: Project coding standards
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

# Project Standards

## Guidelines

- Define architecture boundaries before implementation.
- Keep modules small and testable.
- Prefer explicit interfaces for shared services.

Frontmatter fields like globs and alwaysApply control when the rule applies.

Adding Skills

Skills live in SKILL.md files under skills/. Each skill directory can contain one SKILL.md.

# Project Lead Skill

## Purpose

Keep implementation aligned with team standards and roadmap.

## When to Use

- Starting a new feature
- Reviewing architecture changes
- Updating project standards

## Checklist

1. Verify standards in `rules/project-standards.mdc`.
2. Identify breaking changes and migration notes.
3. Update docs and team guidance after changes.

MCP Configuration

Place MCP config files in mcp/ as .mcp.json files.

{
  "mcpServers": {
    "cursorist": {
      "command": "npx",
      "args": ["-y", "@cursorist/mcp-server@latest"],
      "env": {
        "CURSORIST_API_URL": "https://cursor.ist/api"
      }
    }
  }
}

Validation

Before deploying, validate your plugin:

cursorist plugin validate [--dir path]

Validation checks:

Manifest exists at .cursor-plugin/plugin.json
Manifest has required fields: name, version, description
Manifest has at least one component
At least one asset file exists under rules/, skills/, commands/, mcp/, agents/, or hooks/

Publishing

Deploy

cursorist plugin deploy --org <org> --team <team> --plugin <plugin> [options]

Option	Description
`--dir <path>`	Plugin root (default: current directory)
`--description <text>`	Override description
`--type <type>`	Plugin type (e.g. conventions, snippets)
`--stack <list>`	Comma-separated stack (e.g. typescript,react)
`--version <version>`	Version override

Versioning Strategy

Use semantic versioning: MAJOR.MINOR.PATCH
Bump patch for small fixes and content tweaks
Bump minor for new components or non-breaking changes
Bump major for breaking changes or removals

Workflow Summary

Initialize — cursorist plugin init to scaffold a starter structure
Edit — Add rules, skills, commands, and MCP config
Validate — cursorist plugin validate
Deploy — cursorist plugin deploy --org <org> --team <team> --plugin <plugin>
Upgrade — cursorist plugin upgrade to pull the latest version locally

On this page