Skip to main content
Get better results from AI coding agents when building with Velt. Agent Skills are structured knowledge packages that teach your AI agent the correct Velt patterns, so it writes working code on the first try instead of guessing from outdated training data.

GitHub Repository

velt-js/agent-skills
Agent Skills follow the open Agent Skills format and work with Claude Code, Cursor, GitHub Copilot, and other AI coding agents that support skill discovery.

​
What Are Agent Skills?

Agent Skills are folders of instructions, rules, and code examples that AI agents can discover and reference while helping you write code. Each skill covers a specific area of the Velt SDK and contains prioritized rules with correct and incorrect code patterns, verification checklists, and source pointers back to the official docs. Instead of relying on the agent’s general training data (which may be outdated or incomplete), skills give the agent access to verified, up-to-date Velt implementation patterns.

​
When to Use Skills

Install Agent Skills when you are:
  • Setting up Velt in a new project for the first time
  • Adding collaborative commenting to a React, Next.js, or web application
  • Integrating real-time collaborative editing with CRDT (Yjs) and editors like Tiptap, BlockNote, or CodeMirror
  • Implementing in-app notifications, email delivery, or webhook integrations
  • Adding audio, video, or screen recording with playback
  • Implementing Single Editor Mode (exclusive editing access with viewer/editor roles)
  • Self-hosting user-generated content (comments, attachments, reactions, user PII) on your own database
  • Adding real-time activity logs and audit trails
  • Adding real-time user presence avatars and online status indicators
  • Adding live cursor tracking across collaborators
  • Adding audio/video huddles and screen sharing
  • Calling Velt REST APIs or handling webhooks from your backend
  • Routing Velt SDK traffic through a reverse proxy (nginx) for enterprise network policies
  • Debugging issues with Velt features and looking for correct patterns

​
Installation

Install all available Velt skills with a single command: 
npx skills add velt-js/agent-skills
Skills are automatically available once installed. Your AI agent will use them when relevant tasks are detected.

​
Available Skills

The repository contains skills covering the core areas of the Velt SDK:

velt-setup-best-practices

24 rules across 8 categories covering installation, VeltProvider configuration, user authentication, JWT tokens, and document initialization.Use when setting up Velt in a new React, Next.js, Angular, Vue, or HTML project.

velt-comments-best-practices

71 rules across 12 categories covering comment modes (Freestyle, Popover, Stream, Text, Page, Inline), rich text editor integrations (Tiptap, SlateJS, Lexical), standalone components, and media/chart comments.Use when adding collaborative commenting to your application.

velt-crdt-best-practices

44 rules across 5 categories covering CRDT store setup, Tiptap, BlockNote, CodeMirror, and ReactFlow integrations.Use when implementing real-time collaborative editing.

velt-notifications-best-practices

17 rules across 8 categories covering notification panels, data access, delivery channels, and webhook integrations.Use when adding in-app notifications or email delivery.

velt-recorder-best-practices

21 rules covering audio, video, and screen recording setup, VeltRecorderTool configuration, floating control panels, pinned recording notes, RecordingPlayback with VeltRecorderPlayer, and UI wireframes.Use when adding recording features to your application.

velt-single-editor-mode-best-practices

14 rules across 7 categories covering exclusive editing access, editor/viewer role management, access request handoff, element-level sync control, timeout-based editor transfer, and multi-tab restrictions.Use when implementing one-user-at-a-time editing with live content sync.

velt-self-hosting-data-best-practices

13 rules across 8 categories covering data providers (comments, attachments, reactions, recordings, notifications, users), backend API routes, Python SDK (velt-py), type definitions, and response format contracts.Use when storing user-generated content on your own infrastructure instead of Velt servers.

velt-activity-best-practices

11 rules across 5 categories covering real-time activity feeds, VeltActivityLog component, custom activity logging, CRDT debounce configuration, type-safe action type filtering, and server-side REST API.Use when adding activity logs, audit trails, or real-time event feeds.

velt-presence-best-practices

13 rules covering user presence avatars, online/away/offline status indicators, inactivity timeout configuration, location-based presence filtering, and presence data subscriptions.Use when adding real-time user presence to your application.

velt-cursors-best-practices

11 rules covering live cursor tracking, avatar-mode cursors, element whitelisting, inactivity timeouts, and cursor position subscriptions.Use when adding real-time cursor sharing across collaborators.

velt-huddle-best-practices

10 rules covering audio/video/screen sharing huddles, ephemeral chat, flock mode (follow-me), cursor-mode huddle bubbles, and webhook integration.Use when adding in-app audio/video calls or screen sharing.

velt-rest-apis-best-practices

9 rules covering Velt REST API v2 endpoints, JWT token generation, webhook handling (comment events, huddle events, CRDT updates), and server-side user/document/organization management.Use when calling Velt APIs from your backend or handling Velt webhooks.

velt-proxy-server-best-practices

14 rules covering reverse proxy (nginx) setup for all 6 Velt service hosts (CDN, API, persistence DB, ephemeral DB, storage, auth), proxyConfig SDK configuration, CSP whitelisting, Subresource Integrity (SRI), and forceLongPolling.Use when routing Velt SDK traffic through your own reverse proxy.

​
How Skills Are Organized

Each skill follows a consistent structure: 
skills/{skill-name}/
  SKILL.md              # Agent-facing manifest (when to apply, category index)
  AGENTS.md             # Generated compressed index of all rules
  AGENTS.full.md        # Generated verbose guide with all rules expanded
  README.md             # Contributor guide
  metadata.json         # Version, organization, and metadata
  rules/
    _sections.md        # Section definitions and ordering
    _template.md        # Template for new rules
    shared/             # Framework-agnostic rules
    react/              # React / Next.js specific rules
    non-react/          # Non-React specific rules
Rules are organized into category folders (e.g., core/, panel/, data/) within framework groups (shared/, react/, non-react/). Each rule file is named {prefix}-{descriptive-name}.md where the prefix matches its category.

​
How to Pick the Right Skill

You want to…Use this skill
Set up Velt for the first timevelt-setup-best-practices
Add comments (any mode or editor)velt-comments-best-practices
Add real-time collaborative editing (CRDT/Yjs)velt-crdt-best-practices
Add notifications or email deliveryvelt-notifications-best-practices
Add audio/video/screen recordingvelt-recorder-best-practices
Add exclusive editing (one editor at a time)velt-single-editor-mode-best-practices
Store data on your own databasevelt-self-hosting-data-best-practices
Add activity logs or audit trailsvelt-activity-best-practices
Add user presence avatarsvelt-presence-best-practices
Add live cursor trackingvelt-cursors-best-practices
Add audio/video huddlesvelt-huddle-best-practices
Call Velt REST APIs or handle webhooksvelt-rest-apis-best-practices
Route Velt traffic through a reverse proxyvelt-proxy-server-best-practices

​
Example Prompts

Once skills are installed, you can give your AI agent prompts like these. The agent will automatically reference the relevant skill rules. Setting up Velt in a new project: 
Set up Velt collaboration in my Next.js app. I need comments and presence.
My API key is in .env.local as NEXT_PUBLIC_VELT_API_KEY.
Adding CRDT collaborative editing: 
Set up Velt CRDT for my Tiptap editor. The document ID comes from
the route parameter. Ask me for any identifiers you need.
Debugging an integration issue: 
Help me debug why my collaborative cursors aren't showing.
Check the Velt skills for correct setup patterns before suggesting fixes.

​
Rule Priority Levels

Each rule in a skill is assigned an impact level so the agent knows what matters most:
LevelImprovementExamples
CRITICALPrevents failure or 10-100x improvementProvider setup, authentication, core initialization
HIGHMajor quality gain (5-20x)Comment modes, CRDT editor integration
MEDIUM-HIGHSignificant benefit (2-5x)Standalone components, design patterns
MEDIUMNoticeable gain (1.5-3x)UI customization, data handling
LOW-MEDIUMMinor benefit (1.2-2x)Configuration, debugging patterns
LOWIncremental or edge casesAdvanced techniques, polish

​
Staying Up to Date

Skills are updated as the Velt SDK evolves with new features, API changes, and improved patterns. To pull the latest rules into your project, re-run the install command: 
npx skills add velt-js/agent-skills
This will fetch the latest version of all skills, including any new rules or updated code examples. You can also watch the agent-skills GitHub repository to get notified when new skills or rules are published. For broader SDK updates and announcements, follow us on X and LinkedIn.

​
Next Steps