cursor-plugin

Scaffold and tooling for local Cursor plugins — skills, rules, hooks, and MCP servers installed to ~/.cursor/plugins/local/.

Quick start

git clone git@github.com:khymerao/cursor-plugin.git
cd cursor-plugin

# Create a new plugin in ../my-awesome-plugin
./scaffold.sh my-awesome-plugin "My Awesome Plugin" "What it does"

cd ../my-awesome-plugin
chmod +x scripts/*.sh hooks/* 2>/dev/null || true
./scripts/setup.sh          # if MCP enabled
./scripts/install-to-cursor.sh

Then Developer: Reload Window in Cursor and verify Settings → Plugins.

Repository layout

cursor-plugin/
├── scaffold.sh           # Bootstrap a new plugin from template/
├── template/             # Canonical plugin skeleton
│   ├── .cursor-plugin/plugin.json
│   ├── scripts/          # setup, install, validate, MCP helpers
│   ├── skills/           # optional Agent Skills
│   ├── rules/            # optional Cursor rules
│   ├── hooks/            # optional Cursor hooks
│   └── mcp/              # optional MCP server (Python + FastMCP)
└── docs/                 # Architecture, plugin types, best practices

Local plugin constraints (Cursor runtime)

Rule	Why
Real directory, not symlink	Cursor skips symlinked folders in ~/.cursor/plugins/local/
/add-plugin is Marketplace-only	Local plugins load only from disk path above
Explicit mcpServers in manifest	Use "mcpServers": "./.mcp.json" like official plugins
Absolute paths in .mcp.json	Generated by scripts/generate-mcp-config.sh after venv setup
type: "stdio" for MCP	Required for reliable MCP loading

See docs/local-install.md and docs/best-practices.md.

Plugin types

Use scaffold flags to include only what you need:

./scaffold.sh my-plugin "Display Name" "Description" \
  --skills --rules --hooks --mcp

Type	Components	Use when
skills-rules	skills + rules	Agent guidance, no runtime deps
mcp	MCP server + manifest	External tools / APIs
hooks	hooks.json + scripts	Session/prompt automation
full	all of the above	Complex integrations

Details: docs/plugin-types.md.

Scripts (in each generated plugin)

Script	Purpose
scripts/setup.sh	Create venv, install deps, generate .mcp.json
scripts/install-to-cursor.sh	rsync copy into ~/.cursor/plugins/local/<name>
scripts/validate.sh	Pre-flight checks before install
scripts/generate-mcp-config.sh	Write absolute-path .mcp.json
scripts/run-mcp-server.sh	Run MCP server locally for debugging

Verify installation

1. Output → Cursor Plugins: loadUserLocalPlugins (... 1 plugins loaded)
2. Settings → Plugins: your plugin card
3. Settings → Tools & MCP: MCP server (if enabled)
4. Settings → Hooks: hook entries (if enabled)

CI

GitHub Actions in .github/workflows/:

• ci.yml — shellcheck + scaffold matrix (full, minimal) + MCP smoke test
• actionlint.yml — validates workflow syntax and common mistakes

License

MIT — see LICENSE.