Plugin Architecture
How Cursorist plugins are structured, versioned, and distributed.
This page explains the data model behind Cursorist plugins — how they are organized, what they contain, and how they move from a developer's machine to a team member's Cursor project.
The Big Picture
Cursorist organizes everything into a hierarchy:
Organizations represent companies or communities. Teams are groups within an org (e.g. "frontend", "backend", "mobile"). Plugins belong to a team and contain versioned bundles of Cursor configuration files.
What Goes Into a Plugin
A plugin bundles one or more of these component types:
| Component | File Format | What It Does |
|---|---|---|
| Rules | .mdc | Cursor rules with frontmatter — coding standards, architecture guidelines, review checklists |
| Skills | SKILL.md | Agent skills that teach Cursor's AI how to perform domain-specific tasks |
| Commands | .md | Reusable command templates for common operations |
| MCP Config | .mcp.json | MCP server configuration for connecting external tools |
| Agents | varies | Custom agent definitions |
| Hooks | varies | Lifecycle scripts that run on plugin events |
You choose which components to include when you create a plugin. A minimal plugin might contain just one rule file. A comprehensive one might have rules, skills, MCP config, and hooks.
The Plugin Manifest
Every plugin has a manifest at .cursor-plugin/plugin.json:
{
"name": "acme-frontend-starter",
"version": "1.0.0",
"description": "Frontend team coding standards and tools",
"author": "acme",
"components": ["rules", "skills", "mcp"]
}The components array tells the CLI which directories to include when deploying. Only files in listed component directories are uploaded.
Versioning
Plugins use semantic versioning (MAJOR.MINOR.PATCH):
- Patch (1.0.0 → 1.0.1): Typo fixes, small content tweaks
- Minor (1.0.0 → 1.1.0): New rules or skills added, no breaking changes
- Major (1.0.0 → 2.0.0): Rules removed or renamed, breaking changes
Each cursorist plugin deploy creates a new version. Old versions are preserved — team members on older versions can upgrade when ready.
How Distribution Works
Three distribution channels, one source of truth. The plugin page on cursor.ist shows install counts, versions, and a one-click install button.
Database Model (Simplified)
For contributors who want to understand the backend:
| Table | Purpose |
|---|---|
organizations | Top-level grouping |
teams | Groups within an org |
plugins | Plugin metadata (name, slug, description, status) |
plugin_versions | Version records with manifest snapshots |
plugin_assets | Individual files (content, hash, size, type) |
plugin_installs | Install tracking per user/project |
plugin_favorites | User bookmarks |
See Database Schema for the full table definitions.
Product Intent
Cursorist exists to solve three problems:
- Onboarding friction — New developers should get the full project setup in one command, not a 20-step wiki page
- Standards drift — When a team lead updates standards, every project should get the update, not just new ones
- Tool fragmentation — Rules, skills, MCP configs, and commands should travel together, not be scattered across docs
Plugins are the answer to all three. They are the unit of distribution for Cursor project standards.
Next Steps
- Building Plugins — Step-by-step guide to creating a plugin
- API Reference — REST endpoints for plugin operations
- CLI Commands — Full command reference