SurrealDB Agent Skills

Official SurrealDB agent skills for use in agentic workflows. Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. Compatible with most AI agents including Claude Code, GitHub Copilot, Cursor, Cline, and many others.

The skills in this repo follow the Agent Skills format.

Installation

Install all skills

npx skills add surrealdb/agent-skills

Install a specific skill

npx skills add surrealdb/agent-skills --skill surrealql
npx skills add surrealdb/agent-skills --skill surrealql-performance
npx skills add surrealdb/agent-skills --skill surrealql-functions
npx skills add surrealdb/agent-skills --skill surrealkit
npx skills add surrealdb/agent-skills --skill surrealdb-vector
npx skills add surrealdb/agent-skills --skill surrealdb-python
npx skills add surrealdb/agent-skills --skill surrealdb-js
npx skills add surrealdb/agent-skills --skill surrealdb-cli

Local install from repository

1. Clone the repository:

   git clone https://github.com/surrealdb/agent-skills.git

2. Copy the skills/ directory to the location where your coding agent reads its skills or context files. Refer to your agent's documentation for the correct path.

Available Skills

surrealql

Core SurrealQL query language reference covering syntax, best practices, schema definitions, graph relationships, and common patterns.

Use when:

• Writing SurrealQL queries (SELECT, CREATE, UPDATE, DELETE, RELATE)
• Designing schemas with DEFINE TABLE, DEFINE FIELD, and DEFINE INDEX
• Working with graph relationships and record IDs
• Migrating from traditional SQL to SurrealQL
• Setting up live queries for real-time updates

surrealql-performance

Performance optimization for SurrealDB: record ID and key design for locality and range scans, indexing strategy, and computed/derived fields.

Use when:

• Designing record IDs and keys for efficient lookups and range scans
• Choosing between standard, unique, full-text, or vector indexes
• Verifying index usage with EXPLAIN and avoiding over-indexing
• Precomputing values with computed fields, views, or events
• Diagnosing and fixing slow queries

surrealql-functions

Discover and use SurrealDB's built-in SurrealQL functions with version-current signatures via the SurrealQL language server and tree-sitter grammar, plus a namespace catalog linking every function group to its docs.

Use when:

• Looking up which built-in function to use or its exact signature
• Getting editor completions, hover, and signature help for .surql files
• Confirming a function exists in the installed SurrealDB version
• Setting up the surrealql-language-server (LSP)

surrealkit

SurrealKit CLI for SurrealDB schema management: project scaffolding from templates, development sync, phased production rollouts, type generation, and a declarative testing framework.

Use when:

• Scaffolding a new SurrealDB project with surrealkit init and templates
• Applying schema changes in development with surrealkit sync
• Planning, executing, or rolling back production migrations with surrealkit rollout
• Generating JSON or TypeScript types from a live schema with surrealkit typegen
• Writing declarative TOML tests for schemas, permissions, and API endpoints with surrealkit test

surrealdb-vector

Vector search with SurrealDB using HNSW indexes, KNN queries, and similarity scoring.

Use when:

• Creating HNSW vector indexes on tables
• Querying vectors with KNN distance operators
• Building semantic search, RAG pipelines, or recommendation systems
• Tuning HNSW parameters (EFC, M, M0, distance function, type)

surrealdb-python

Using SurrealDB with the Python SDK, covering both client/server mode (WebSocket) and embedded mode (in-memory or file-based persistence).

Use when:

• Connecting to SurrealDB from Python applications
• Using the surrealdb Python package (sync or async)
• Running SurrealDB embedded in Python without a server
• Performing CRUD operations from Python code

surrealdb-js

Using SurrealDB from JavaScript and TypeScript with the official surrealdb SDK, covering remote (WebSocket/HTTP) and embedded engines, authentication, CRUD, parameterized queries, and live queries.

Use when:

• Connecting to SurrealDB from Node.js, Deno, Bun, or the browser
• Using the surrealdb npm package
• Running SurrealDB embedded with @surrealdb/node or @surrealdb/wasm
• Performing CRUD, queries, and real-time live queries from JS/TS code

surrealdb-cli

The surreal command-line binary for running and operating SurrealDB: starting a server, querying it interactively or via pipes, importing/exporting data, and maintenance tasks.

Use when:

• Starting a SurrealDB server with surreal start (memory, RocksDB, SurrealKV, or TiKV)
• Opening the SQL shell or piping queries with surreal sql
• Backing up or restoring data with surreal export and surreal import
• Gating scripts or CI on server readiness with surreal is-ready
• Upgrading the binary, repairing storage, or managing ML models (surreal upgrade, surreal fix, surreal ml)

Usage

Skills are automatically available once installed. The agent will use them when relevant tasks are detected.

Examples:

Write a SurrealQL query to find all users who follow each other

Create an HNSW vector index for semantic search on my documents table

Connect to SurrealDB from my Python application

Skill Structure

Each skill follows the Agent Skills Open Standard:

• SKILL.md — Required skill manifest with frontmatter (name, description, metadata)
• references/ — (Optional) Reference files for detailed documentation

Resources

• SurrealDB Documentation
• SurrealDB Agent Rules
• Agent Skills Specification