surreal-skills

Expert SurrealDB 3 skill for AI coding agents. Complete coverage of SurrealQL, multi-model data modeling, graph traversal, vector search, security, deployment, performance tuning, SDK integration, WASM extensions, and the full SurrealDB ecosystem, including SurrealKit workflows.

Features

• SurrealQL mastery -- Complete language reference with statements, functions, operators, and idioms
• Multi-model data modeling -- Document, graph, vector, relational, time-series, and geospatial patterns in a single schema
• Graph queries -- First-class edge creation and traversal without JOINs
• Vector search -- HNSW indexes, similarity functions, and RAG pipeline patterns
• Security -- Row-level permissions, JWT auth, namespace/database/record-level access control
• Deployment -- Storage engine selection, Docker, Kubernetes, production hardening
• Performance -- Index strategies, EXPLAIN analysis, batch operations, connection pooling
• 9+ SDK integrations -- JavaScript/TypeScript, Python, Go, Rust, Java, .NET, C, PHP, Dart
• Surrealism WASM extensions -- Custom functions and analyzers compiled from Rust (new in v3)
• Full ecosystem -- Surrealist IDE, Surreal-Sync CDC, SurrealFS agent filesystem, SurrealKit schema tooling, SurrealML
• Health checks and introspection -- Doctor script and schema introspection for any SurrealDB instance
• Universal agent support -- Works with 30+ AI coding agents via skills.sh

Installation

Claude Code (recommended)

Option 1 -- Install as a Claude Code skill (global)

npx skills add 24601/surreal-skills -a claude-code -g -y

This installs the skill globally so it is available in every Claude Code session. The -g flag installs globally, -y auto-confirms prompts.

Option 2 -- Install per-project via CLAUDE.md

Clone the repo and reference it from your project's CLAUDE.md:

git clone https://github.com/24601/surreal-skills.git ~/.claude/skills/surrealdb

Then add to your project's CLAUDE.md (or ~/.claude/CLAUDE.md for global):

# SurrealDB Skill

@import ~/.claude/skills/surrealdb/AGENTS.md

Or inline the reference:

# SurrealDB Skill

For SurrealDB work, read the rules at ~/.claude/skills/surrealdb/rules/ and
use the scripts at ~/.claude/skills/surrealdb/scripts/ for health checks
and schema introspection.

Option 3 -- Add as a Claude Code custom slash command

Create ~/.claude/commands/surrealdb.md:

Load the SurrealDB 3 skill from ~/.claude/skills/surrealdb/AGENTS.md
and use its rules for all SurrealDB architecture, development, and operations tasks.
Available rules: surrealql, data-modeling, graph-queries, vector-search, security,
deployment, performance, sdks, surrealism, surrealist, surreal-sync, surrealfs.

Then invoke with /surrealdb in any Claude Code session.

Option 4 -- Project-scoped slash commands

Add SurrealDB-specific commands to your project:

mkdir -p .claude/commands

Create .claude/commands/surreal-doctor.md:

Run the SurrealDB health check: uv run ~/.claude/skills/surrealdb/scripts/doctor.py
Report any issues found and suggest fixes based on the deployment rules.

Create .claude/commands/surreal-schema.md:

Introspect the current SurrealDB schema: uv run ~/.claude/skills/surrealdb/scripts/schema.py introspect
Analyze the output using the data-modeling rules and suggest improvements.

Other AI Agents

# skills.sh (universal -- works with all supported agents)
npx skills add 24601/surreal-skills

# Amp
npx skills add 24601/surreal-skills -a amp -g -y

# Codex
npx skills add 24601/surreal-skills -a codex -g -y

# Gemini CLI
npx skills add 24601/surreal-skills -a gemini-cli -g -y

# OpenCode
npx skills add 24601/surreal-skills -a opencode -g -y

# Pi (badlogic/pi-mono)
npx skills add 24601/surreal-skills -a pi -g -y

# OpenClaw / Clawdbot
npx skills add 24601/surreal-skills -a openclaw -g -y

GitHub Copilot (native agent skills)

Copilot supports the Agent Skills standard natively in VS Code,
Copilot CLI, and the Copilot coding agent. This skill ships a Copilot-native
.github/skills/surrealdb/SKILL.md that Copilot auto-loads when your prompt
is SurrealDB-related.

Option 1 -- Project-level (recommended for teams)

Copy the entire skill into your project's .github/skills/ directory:

# From the surreal-skills repo
cp -r .github/skills/surrealdb <your-project>/.github/skills/surrealdb
cp -r rules/ <your-project>/.github/skills/surrealdb/rules/

Copilot discovers this automatically -- no config needed. Type /surrealdb in
chat or let Copilot auto-load it when it detects SurrealQL context.

Option 2 -- Personal (all projects)

Clone into ~/.copilot/skills/:

git clone https://github.com/24601/surreal-skills.git ~/.copilot/skills/surrealdb

Or add a custom search location in VS Code settings:

{
  "chat.agentSkillsLocations": [
    "~/.copilot/skills"
  ]
}

Option 3 -- Use /skills menu

Type /skills in Copilot chat to open the Configure Skills menu, then browse
to the cloned surrealdb directory.

Other IDE Integrations

# Cursor -- add skill to .cursor/skills/ (same Agent Skills standard)
cp -r .github/skills/surrealdb <your-project>/.cursor/skills/surrealdb

# Windsurf -- append AGENTS.md to .windsurfrules
cat AGENTS.md >> .windsurfrules

# Cline / Continue -- reference in your config
# Add the AGENTS.md path to your system prompt configuration

Manual installation

# Clone to any location
git clone https://github.com/24601/surreal-skills.git ~/.claude/skills/surrealdb

# Verify installation
uv run ~/.claude/skills/surrealdb/scripts/doctor.py --check

Quick Start

Credential warning: Examples below use root/root for local development
only. Never use default credentials against production or shared instances.

# Start SurrealDB in-memory for LOCAL DEVELOPMENT ONLY
surreal start memory --user root --pass root --bind 127.0.0.1:8000

# Connect via CLI REPL (local dev)
surreal sql --endpoint http://localhost:8000 --user root --pass root --ns test --db test

# Create records with SurrealQL
CREATE person:alice SET name = 'Alice', email = '[email protected]';
CREATE person:bob SET name = 'Bob', email = '[email protected]';

# Create graph edges
RELATE person:alice->follows->person:bob SET since = time::now();

# Traverse the graph
SELECT ->follows->person.name AS following FROM person:alice;

# Run the health check
uv run scripts/doctor.py

Architecture

surreal-skills/
  SKILL.md              # Skill manifest (frontmatter + body)
  AGENTS.md             # Structured agent briefing
  README.md             # This file
  LICENSE               # MIT license
  scripts/
    onboard.py          # Setup wizard / capabilities manifest
    doctor.py           # Health check (CLI, server, auth, storage)
    schema.py           # Schema introspection and export
  rules/
    surrealql.md        # SurrealQL language reference
    data-modeling.md    # Multi-model schema design patterns
    graph-queries.md    # Graph traversal and RELATE patterns
    vector-search.md    # Vector indexes, similarity search, RAG
    security.md         # Permissions, auth, access control
    deployment.md       # Storage engines, Docker, K8s, production
    performance.md      # Indexes, EXPLAIN, optimization
    sdks.md             # Official SDK integration (9+ languages)
    surrealism.md       # WASM extension system (new in v3)
    surrealist.md       # Surrealist IDE/GUI
    surreal-sync.md     # CDC migration tool
    surrealfs.md        # AI agent filesystem
    surrealkit.md       # Desired-state schema sync and rollouts

Rules

Scripts

All scripts follow the dual-output convention: stderr for Rich-formatted human output, stdout for machine-readable JSON.

Sub-Skills

Surrealism (WASM Extensions)

New in SurrealDB 3. Extend the database with custom functions and analyzers written in Rust, compiled to WebAssembly, and deployed to running instances. The rules/surrealism.md rule covers the full Surrealism SDK, module authoring, compilation, deployment, and testing workflow.

Surreal-Sync (CDC Migration)

Change Data Capture tool for migrating data from external databases (PostgreSQL, MySQL, MongoDB, and others) into SurrealDB. Supports incremental sync, schema translation, and conflict resolution. See rules/surreal-sync.md.

SurrealFS (AI Agent Filesystem)

A filesystem abstraction built on SurrealDB, designed for AI agent workflows. Store files with rich metadata queryable via SurrealQL, version files automatically, and integrate with agent frameworks. See rules/surrealfs.md.

SurrealKit (Schema Sync and Rollouts)

SurrealDB schema management for application teams. Use desired-state sync for disposable environments, rollout manifests for shared and production databases, seed for fixture data, and test for declarative schema, permission, and API checks. See rules/surrealkit.md.

Use Cases

API Backend

Use SurrealDB as the primary datastore for REST or GraphQL APIs. Define tables with schemafull validation, set up row-level permissions for multi-tenant security, connect via the JavaScript or Python SDK over WebSocket for real-time live queries.

Real-Time Application

Leverage LIVE SELECT for push-based data subscriptions. Clients receive changes as they happen without polling. Combine with WebSocket SDK connections for chat applications, collaborative editors, dashboards, and notification systems.

Graph Analytics

Model complex relationships (social networks, organizational hierarchies, dependency trees, knowledge graphs) using RELATE and typed edge tables. Traverse paths of arbitrary depth with -> operators. Filter and aggregate at each hop without writing JOINs.

Vector Search and RAG

Store document embeddings alongside content. Create HNSW vector indexes with configurable distance metrics. Query with vector::similarity::cosine for semantic search. Build retrieval-augmented generation pipelines that combine vector similarity with metadata filtering in a single SurrealQL query.

IoT and Time-Series

Ingest high-volume sensor data with schemaless tables. Use datetime fields and range queries for time-series analysis. Aggregate with built-in math and time functions. SurrealKV storage engine enables time-travel queries to access historical state at any point in time.

Geospatial Applications

Store geometry types (points, polygons, multipoints) as native SurrealDB values. Use built-in geo functions (geo::distance, geo::bearing, geo::area, geo::contains) for spatial queries. Combine with other data models -- a single query can traverse a graph, filter by location, and rank by vector similarity.

Data Migration

Migrate from PostgreSQL, MySQL, MongoDB, or other databases using Surreal-Sync CDC. Translate schemas automatically, sync incrementally, and validate with schema introspection. For SurrealDB v2-to-v3 upgrades, use surreal export/import with the migration notes in rules/surrealql.md.

WASM Extensions

Extend SurrealDB with custom business logic using Surrealism. Write functions and analyzers in Rust, compile to WASM, and deploy without restarting the server. Use cases include custom validation, domain-specific scoring, proprietary tokenizers, and specialized aggregation functions.

AI Agent Filesystem

Use SurrealFS as a persistent, queryable filesystem for AI agent workflows. Agents can store and retrieve files with rich metadata, query across files with SurrealQL, and leverage SurrealDB's permissions system for multi-agent access control.

Full-Text Search

Define custom analyzers (tokenizers, filters, stemmers) and create search indexes on text fields. Query with full-text search predicates that integrate with the rest of SurrealQL -- combine text search with graph traversal, vector similarity, and relational filters in a single statement.

Configuration

Set these environment variables to configure the skill scripts. All are optional with sensible defaults.

These variables are also recognized by the surreal CLI and official SurrealDB SDKs.

Source Provenance

This skill was refreshed on 2026-04-10 from these upstream sources. Use check_upstream.py
to detect what changed since this snapshot for incremental updates.

Documentation: surrealdb.com/docs snapshot 2026-04-10.

Machine-readable provenance: SOURCES.json.

Registries

This skill is published to multiple agent skill registries:

Contributing

See CONTRIBUTING.md for development setup, code style, and PR process.

Security

To report a vulnerability, use GitHub Security Advisories. See SECURITY.md for details.

This skill declares the following security properties in SKILL.md frontmatter:

Required Environment Variables

Declared in SKILL.md requires.env_vars:

Required Binaries

Declared in SKILL.md requires.binaries:

Script Safety

• All user-provided table names are validated against [a-zA-Z_][a-zA-Z0-9_]* before interpolation into SurrealQL queries (prevents SurrealQL injection)
• doctor.py and schema.py connect only to the SurrealDB endpoint specified by the user (via env var or CLI flag)
• check_upstream.py calls GitHub API via gh CLI to compare upstream repo SHAs (optional maintenance script, not needed for normal usage)
• No data is sent to third-party services
• Credential warning labels are present on all root/root examples

License

MIT

Credits

Built for the SurrealDB community. SurrealDB is created and maintained by SurrealDB Ltd.

Published on skills.sh, ClawHub, and GitHub.