AI Plugins - Velt

Add Velt collaboration knowledge directly into your AI coding editor. The Velt AI plugin gives your AI agent access to 8 slash-command skills, 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.

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
Skills only (for any AI agent): See Agent Skills
No AI agent: See the CLI

Prerequisites

Node.js 18+
Cursor or Claude Code with plugin support
A Velt API key

Quickstart

Cursor
Claude Code

Option 1: Local Plugin Directory

Clone the plugin repository:

git clone https://github.com/velt-js/velt-plugin.git

Open Cursor Settings → Plugins
Add the local plugin path:

<path-to-repo>/packages/cursor-velt

Restart Cursor.

Option 2: Marketplace CLI

From within Cursor, run:

/plugin marketplace add ./packages/cursor-velt

Option 1: Direct Plugin Directory

Point Claude Code at the built plugin:

git clone https://github.com/velt-js/velt-plugin.git
claude --plugin-dir packages/claude-velt

Option 2: Local Marketplace

# Inside Claude Code:
/plugin marketplace add ./packages/claude-marketplace
/plugin install velt@velt-plugins

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	8	Slash commands for common Velt tasks
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	`install_velt_interactive`
`/add-comments`	Add comments (freestyle, popover, text, stream, page, editor)	`install_velt_interactive`
`/add-crdt`	Add CRDT collaborative editing (Tiptap, BlockNote, CodeMirror, ReactFlow)	`install_velt_interactive`
`/add-notifications`	Add in-app notifications, email, webhooks	`install_velt_interactive`
`/add-presence`	Add real-time user presence indicators	`install_velt_interactive`
`/add-cursors`	Add live cursor tracking	`install_velt_interactive`
`/screenshot`	Capture app screenshot for visual reference	`take_project_screenshot`
`/velt-help`	Answer questions about the Velt SDK	`velt-docs` MCP

Embedded Rules

The plugin includes 6 rules distilled from 105 agent-skills rules. 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:

Embedded rules (always loaded) — distilled best practices that cover the most common mistakes
Reference agent-skills (vendored snapshot) — full detailed patterns with code examples from the agent-skills repository
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.

Claude Code Implementation

The Claude Code plugin lives at packages/claude-velt/ and follows the Claude Code plugin specification.

Plugin Structure

packages/claude-velt/
├── .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
│   ├── add-comments/SKILL.md
│   ├── add-crdt/SKILL.md
│   ├── add-notifications/SKILL.md
│   ├── add-presence/SKILL.md
│   ├── add-cursors/SKILL.md
│   ├── screenshot/SKILL.md
│   └── velt-help/SKILL.md
└── references/
    └── agent-skills/           # Vendored snapshot (~992 KB)

Plugin Manifest

The manifest at .claude-plugin/plugin.json registers the plugin with Claude Code:

{
  "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",
  "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:

{
  "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:

---
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:

Core setup — VeltProvider, API key, domain safelist
Authentication — user object, authProvider, JWT, provider mapping
Document identity — setDocuments, ID strategies, anti-patterns
Comments — all modes (freestyle, popover, text, stream, page, editor-integrated)
CRDT — store types, Tiptap integration, history disable
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):

---
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).

Marketplace Wrapper

For distribution through the Claude Code marketplace, a wrapper exists at packages/claude-marketplace/:

packages/claude-marketplace/
├── .claude-plugin/
│   └── marketplace.json        # Marketplace metadata
└── plugins/
    └── velt/                   # Copy of claude-velt (generated by build)

The marketplace.json registers the plugin collection:

{
  "name": "velt-plugins",
  "owner": { "name": "Velt", "email": "support@velt.dev" },
  "metadata": {
    "description": "Official Velt collaboration SDK plugins for Claude Code",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "velt",
      "source": "./plugins/velt",
      "description": "Add real-time collaboration (comments, presence, cursors, CRDT editing, notifications) to React and Next.js apps."
    }
  ]
}

Differences from Cursor Plugin

Aspect	Cursor (`cursor-velt`)	Claude Code (`claude-velt`)
Manifest	`.cursor-plugin/plugin.json` with `displayName`, `logo`, `category`, `tags`, `skills`, `rules`, `agents`, `mcpServers` fields	`.claude-plugin/plugin.json` with simpler schema (no `displayName`, `logo`, or path references)
Rules	6 individual `.mdc` files with `alwaysApply` / glob frontmatter	Single `guides/velt-rules.md` combining all 6 rules
MCP config	`mcp.json` (top-level file)	`.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/logo.svg` included	Not included
Marketplace	Direct plugin registration	Separate `claude-marketplace/` wrapper with `marketplace.json`

Contributing

If you are contributing to the plugin itself, the repository uses a shared-source architecture. All canonical content lives in packages/shared/ and is built into platform-specific outputs.

Build Workflow

# 1. Sync the agent-skills reference (from a sibling ../agent-skills directory)
npm run sync

# 2. Generate both Cursor and Claude Code plugins from shared source
npm run build

# 3. Validate both plugins are 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:

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 (Cursor) or a combined guides/velt-rules.md (Claude Code)
Copies the vendored agent-skills reference into both plugins
Generates the Claude Code marketplace wrapper

Validation Checks

npm run validate verifies:

All 8 skills present in both plugins
Both MCP servers configured
Agent persona present
JSON manifests valid and free of path traversal
Reference agent-skills 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 built output (packages/cursor-velt or packages/claude-velt), not the root repository or packages/shared.

Stale rules or skills

If you updated the shared source, re-run the build:

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:

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 packages/claude-velt, not packages/cursor-velt. 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: AI-assisted Velt installation through MCP (without the full plugin)
Agent Skills: Standalone skill packages for any AI coding agent
CLI: Terminal-based Velt setup without an AI agent
Quickstart: Manual step-by-step Velt setup
Key Concepts: Understand documents, locations, users, and access control

Get Started

Agentic Setup

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Backend SDKs

Model Context Protocol

Webhooks

Security

Miscellaneous

​When to Use AI Plugins

​Prerequisites

​Quickstart

​Option 1: Local Plugin Directory

​Option 2: Marketplace CLI

​Option 1: Direct Plugin Directory

​Option 2: Local Marketplace

​What’s Included

​Available Skills

​Embedded Rules

​How It Works

​Claude Code Implementation

​Plugin Structure

​Plugin Manifest

​MCP Server Configuration

​Agent Persona

​Combined Rules Guide

​Skill Format

​Marketplace Wrapper

​Differences from Cursor Plugin

​Contributing

​Build Workflow

​Sync Options

​What the Build Does

​Validation Checks

​Troubleshooting

​Plugin not loading after installation

​Skills not appearing

​Stale rules or skills

​MCP servers not connecting

​Claude Code: guides/velt-rules.md not found

​Next Steps