> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velt.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Plugins
> Install the Velt plugin in Cursor or Claude Code to get skills, rules, an expert agent, and MCP servers for building with the Velt SDK.
Add Velt collaboration knowledge directly into your AI coding editor. The Velt AI plugin gives your AI agent access to slash-command skills, 13 bundled agent-skills (277 implementation rules), 6 embedded best-practice rules, a `velt-expert` agent persona, and two MCP servers, so it can scaffold, debug, and extend Velt features with accurate, up-to-date patterns.
velt-js/velt-plugin-cursor
velt-js/velt-plugin-claude
## When to Use AI Plugins
* You are building with Velt in Cursor or Claude Code and want your AI agent to have deep Velt SDK knowledge
* You want slash-command skills like `/install-velt`, `/add-comments`, or `/velt-help` available in your editor
* You want always-on rules that prevent common Velt integration mistakes (e.g., incorrect `VeltProvider` placement, missing `setDocuments`)
* You want the `velt-expert` agent persona for architecture and integration guidance
AI plugins bundle MCP servers, skills, rules, and an agent into a single installable package. If you only need one of these:
* **MCP servers only**: See the [MCP Installer](/get-started/mcp-installer)
* **Skills only** (for any AI agent): See [Agent Skills](/get-started/skills)
* **No AI agent**: See the [CLI](/get-started/cli)
## Prerequisites
* **Node.js** 18+
* **Cursor** or **Claude Code** with plugin support
* A [Velt API key](https://console.velt.dev)
## Quickstart
### Option 1: Local Plugin Directory
1. Clone the Cursor plugin repository:
```bash theme={null}
git clone https://github.com/velt-js/velt-plugin-cursor.git
```
2. Open Cursor Settings → Plugins
3. Add the local plugin path (the repo root is the plugin):
```
/velt-plugin-cursor
```
4. Restart Cursor.
### Option 2: Marketplace CLI
From within Cursor, run:
```
/plugin marketplace add /velt-plugin-cursor
```
Clone the Claude Code plugin repository and point Claude Code at it:
```bash theme={null}
git clone https://github.com/velt-js/velt-plugin-claude.git
claude --plugin-dir velt-plugin-claude
```
After installation, verify by typing `/velt-help` in your editor's AI chat. The agent should respond using Velt-specific knowledge.
## What's Included
The plugin bundles four types of resources:
| Resource | Count | Description |
| ------------------------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Skills** | 2 | Slash commands: `/install-velt` and `/velt-help` |
| **Bundled Agent-Skills** | 13 | Full implementation rules (277 rules across setup, comments, CRDT, notifications, recorder, single editor mode, self-hosting data, activity logs, presence, cursors, huddle, REST APIs, proxy server) |
| **Rules** | 6 | Embedded best practices (3 always-on, 3 glob-triggered) |
| **Agent** | 1 | `velt-expert` persona for architecture guidance |
| **MCP Servers** | 2 | `velt-installer` (guided setup) and `velt-docs` (documentation search) |
## Available Skills
| Skill | Description | MCP Tool Used |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `/install-velt` | Full guided Velt SDK installation with feature selection (comments, presence, cursors, notifications, recorder, CRDT, single editor mode, self-hosting data, activity logs, huddle) | `install_velt_interactive` |
| `/velt-help` | Answer questions about the Velt SDK | `velt-docs` MCP |
## Embedded Rules
The plugin includes 6 rules distilled from the most critical agent-skills patterns. Three are always active; three activate when your AI agent works on matching files.
| Rule | Covers | Activation |
| ----------------------------- | ---------------------------------------------------------- | -------------- |
| `velt-core-setup` | Installation, `VeltProvider`, API key, domain safelist | Always on |
| `velt-auth-patterns` | User object, `authProvider`, JWT, auth provider mapping | Always on |
| `velt-document-identity` | `setDocuments`, document ID strategies, anti-patterns | Always on |
| `velt-comments-patterns` | All comment modes, component placement, editor integration | Glob-triggered |
| `velt-crdt-patterns` | CRDT stores, Tiptap integration, history disable | Glob-triggered |
| `velt-notifications-patterns` | Setup, panel config, hooks, email, webhooks | Glob-triggered |
## How It Works
The plugin follows a three-tier priority chain when answering questions or generating code:
1. **Embedded rules** (always loaded): distilled best practices that cover the most common mistakes
2. **Bundled agent-skills** (13 skills with 277 rules): full detailed patterns with code examples from the [agent-skills repository](https://github.com/velt-js/agent-skills)
3. **velt-docs MCP** (live query): fetches the latest API details or topics not covered by the first two tiers
This means the agent can answer most questions instantly from local knowledge, and only reaches out to the live docs API when needed.
## Cursor Plugin Structure
The Cursor plugin lives in its own repository at [`velt-plugin-cursor`](https://github.com/velt-js/velt-plugin-cursor). The repo root is the plugin directory.
```
velt-plugin-cursor/
├── .plugin/
│ └── plugin.json # Open Plugins standard manifest
├── .cursor-plugin/
│ └── plugin.json # Cursor backward-compat manifest
├── .mcp.json # MCP server configuration
├── agents/
│ └── velt-expert.md # Expert agent persona
├── assets/
│ └── velt.svg # Plugin logo
├── rules/ # 6 individual .mdc rule files
│ ├── velt-core-setup.mdc
│ ├── velt-auth-patterns.mdc
│ ├── velt-document-identity.mdc
│ ├── velt-comments-patterns.mdc
│ ├── velt-crdt-patterns.mdc
│ └── velt-notifications-patterns.mdc
├── skills/ # Core skills + 12 bundled agent-skills
│ ├── install-velt/SKILL.md
│ ├── velt-help/SKILL.md
│ ├── velt-setup-best-practices/
│ ├── velt-comments-best-practices/
│ ├── velt-crdt-best-practices/
│ ├── velt-notifications-best-practices/
│ ├── velt-recorder-best-practices/
│ ├── velt-single-editor-mode-best-practices/
│ ├── velt-self-hosting-data-best-practices/
│ ├── velt-activity-best-practices/
│ ├── velt-presence-best-practices/
│ ├── velt-cursors-best-practices/
│ ├── velt-huddle-best-practices/
│ ├── velt-rest-apis-best-practices/
│ └── velt-proxy-server-best-practices/
└── packages/shared/ # Source of truth (used by build)
```
## Claude Code Implementation
The Claude Code plugin lives in its own repository at [`velt-plugin-claude`](https://github.com/velt-js/velt-plugin-claude) and follows the Claude Code plugin specification.
### Plugin Structure
```
velt-plugin-claude/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── .mcp.json # MCP server configuration
├── agents/
│ └── velt-expert.md # Expert agent persona
├── guides/
│ └── velt-rules.md # Combined best-practices guide (all 6 rules)
├── skills/
│ ├── install-velt/SKILL.md
│ ├── velt-help/SKILL.md
│ ├── velt-setup-best-practices/ # 24 rules
│ ├── velt-comments-best-practices/ # 71 rules
│ ├── velt-crdt-best-practices/ # 44 rules
│ ├── velt-notifications-best-practices/ # 17 rules
│ ├── velt-recorder-best-practices/ # 21 rules
│ ├── velt-single-editor-mode-best-practices/ # 14 rules
│ ├── velt-self-hosting-data-best-practices/ # 13 rules
│ ├── velt-activity-best-practices/ # 11 rules
│ ├── velt-presence-best-practices/ # 13 rules
│ ├── velt-cursors-best-practices/ # 11 rules
│ ├── velt-huddle-best-practices/ # 10 rules
│ ├── velt-rest-apis-best-practices/ # 9 rules
│ └── velt-proxy-server-best-practices/ # 14 rules
└── README.md
```
### Plugin Manifest
The manifest at `.claude-plugin/plugin.json` registers the plugin with Claude Code:
```json theme={null}
{
"name": "velt",
"description": "Add real-time collaboration (comments, presence, cursors, CRDT editing, notifications) to React and Next.js apps using the Velt SDK.",
"version": "1.0.0",
"author": { "name": "Velt", "email": "support@velt.dev" },
"homepage": "https://docs.velt.dev",
"repository": "https://github.com/velt-js/velt-plugin-claude",
"license": "MIT",
"keywords": ["velt", "collaboration", "comments", "presence", "cursors", "crdt", "real-time", "react", "nextjs"]
}
```
### MCP Server Configuration
The `.mcp.json` file configures two MCP servers that Claude Code connects to automatically:
```json theme={null}
{
"mcpServers": {
"velt-installer": {
"command": "npx",
"args": ["-y", "@velt-js/mcp-installer"]
},
"velt-docs": {
"type": "http",
"url": "https://docs.velt.dev/mcp"
}
}
}
```
* **`velt-installer`**: runs locally via `npx`, exposes `install_velt_interactive`, `take_project_screenshot`, and `detect_comment_placement` tools
* **`velt-docs`**: connects to the remote Velt docs API over HTTP for live documentation queries
### Agent Persona
The `velt-expert` agent at `agents/velt-expert.md` is a Velt SDK specialist. It uses frontmatter to register with Claude Code:
```yaml theme={null}
---
name: velt-expert
description: Velt collaboration SDK expert for architecture, setup, and integration guidance.
---
```
The agent follows these key principles:
* `VeltProvider` goes in `page.tsx`, not `layout.tsx` (Next.js App Router)
* All files importing `@veltdev/react` need `"use client"` directive
* Authenticate users before setting documents
* `setDocuments` in a child component, never in `VeltProvider`'s component
* For Tiptap CRDT: always disable history (`StarterKit.configure({ history: false })`)
### Combined Rules Guide
Unlike Cursor (which uses individual `.mdc` rule files with `alwaysApply` and glob triggers), the Claude Code plugin combines all 6 rules into a single `guides/velt-rules.md` file. This guide covers:
1. **Core setup**: `VeltProvider`, API key, domain safelist
2. **Authentication**: user object, `authProvider`, JWT, provider mapping
3. **Document identity**: `setDocuments`, ID strategies, anti-patterns
4. **Comments**: all modes (freestyle, popover, text, stream, page, editor-integrated)
5. **CRDT**: store types, Tiptap integration, history disable
6. **Notifications**: panel config, hooks, email via SendGrid, webhooks
Every skill's `SKILL.md` includes a footer that references this guide:
```
**Important**: Always consult `guides/velt-rules.md` for embedded best practices before querying external sources.
```
### Skill Format
Each Claude Code skill uses `description` frontmatter (Cursor uses both `name` and `description`):
```yaml theme={null}
---
description: Full guided installation of the Velt collaboration SDK into a React or Next.js project.
---
```
Skills follow a consistent structure: **Trigger** (when to activate), **Workflow** (step-by-step instructions), **Guardrails** (constraints), **Priority Chain** (where to look for answers), and **Output** (what gets delivered).
### Differences from Cursor Plugin
| Aspect | Cursor ([`velt-plugin-cursor`](https://github.com/velt-js/velt-plugin-cursor)) | Claude Code ([`velt-plugin-claude`](https://github.com/velt-js/velt-plugin-claude)) |
| --------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| **Repository** | Separate repo with build system and shared source | Separate standalone repo (no build system needed) |
| **Manifest** | `.plugin/plugin.json` + `.cursor-plugin/plugin.json` (Open Plugins standard) | `.claude-plugin/plugin.json` with simpler schema |
| **Rules** | 6 individual `.mdc` files with `alwaysApply` / glob frontmatter | Single `guides/velt-rules.md` combining all 6 rules |
| **MCP config** | `.mcp.json` (dotfile) | `.mcp.json` (dotfile), `velt-docs` uses `"type": "http"` |
| **Skill frontmatter** | `name` + `description` | `description` only |
| **Agent footer** | No rules reference footer | Appends `guides/velt-rules.md` reference to agent and all skills |
| **Logo** | `assets/velt.svg` included | Not included |
| **Build system** | `npm run build` from `packages/shared/` source | Static, no build required |
## Contributing
If you are contributing to the Cursor plugin, the [`velt-plugin-cursor`](https://github.com/velt-js/velt-plugin-cursor) repository uses a shared-source architecture. All canonical content lives in `packages/shared/` and is built into the Cursor plugin at the repo root.
### Build Workflow
```bash theme={null}
# 1. Sync the agent-skills reference (from a sibling ../agent-skills directory)
npm run sync
# 2. Generate the Cursor plugin from shared source
npm run build
# 3. Validate the Cursor plugin is complete
npm run validate
# Or run all three:
npm run all
```
### Sync Options
By default, `npm run sync` looks for the agent-skills repository at `../agent-skills`. To override:
```bash theme={null}
node scripts/sync-agent-skills.mjs /path/to/agent-skills
```
### What the Build Does
* Adds platform-specific frontmatter to skills and agents
* Converts shared rules to `.mdc` files with `alwaysApply` and glob frontmatter
* Copies bundled agent-skills into the plugin
* Generates `.plugin/plugin.json` and `.cursor-plugin/plugin.json` manifests
### Validation Checks
`npm run validate` verifies:
* All core skills and 13 bundled agent-skills present
* Both MCP servers configured
* Agent persona present
* JSON manifests valid and free of path traversal
* Logo asset present
## Troubleshooting
### Plugin not loading after installation
Restart your editor after adding the plugin path. Verify the plugin directory contains a `.cursor-plugin/plugin.json` (Cursor) or `.claude-plugin/plugin.json` (Claude Code) manifest file.
### Skills not appearing
Confirm the plugin directory points to the correct repository root (`velt-plugin-cursor` or `velt-plugin-claude`), not `packages/shared`.
### Stale rules or skills
If you updated the shared source, re-run the build:
```bash theme={null}
npm run build
```
Then restart your editor to pick up the changes.
### MCP servers not connecting
The plugin configures two MCP servers automatically. If they fail to connect, verify that `npx -y @velt-js/mcp-installer` runs successfully in your terminal:
```bash theme={null}
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx -y @velt-js/mcp-installer
```
For the docs MCP server, verify `https://docs.velt.dev/mcp` is reachable from your network.
### Claude Code: `guides/velt-rules.md` not found
Ensure you are pointing at `velt-plugin-claude`, not `velt-plugin-cursor`. The Claude Code plugin uses a combined rules guide at `guides/velt-rules.md`, while Cursor uses individual `.mdc` files in `rules/`.
## Next Steps
* **[MCP Installer](/get-started/mcp-installer)**: AI-assisted Velt installation through MCP (without the full plugin)
* **[Agent Skills](/get-started/skills)**: Standalone skill packages for any AI coding agent
* **[CLI](/get-started/cli)**: Terminal-based Velt setup without an AI agent
* **[Quickstart](/get-started/quickstart)**: Manual step-by-step Velt setup
* **[Key Concepts](/key-concepts/overview)**: Understand documents, locations, users, and access control