Agent Skills

AI coding agents perform best when they have the right context for the job. Each Agent Skill is a self-contained package of instructions, reference material, and resources that an agent can pick up and apply whenever the task calls for it.

SurrealDB publishes a set of official skills that give your agent deep knowledge of SurrealQL, vector search, the Python SDK, and more. Built on the Agent Skills open standard, they work across all major coding agents including Claude Code, GitHub Copilot, Cursor, Cline, and many others.

Installation

Using the Skills CLI

The quickest way to get started is to install every SurrealDB skill in one go:

npx skills add surrealdb/agent-skills

If you only need a subset, pick the ones relevant to your project:

npx skills add surrealdb/agent-skills --skill surrealql

Manual setup

Alternatively, clone the repository and copy the skills into your agent's context directory:

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

After cloning, move the skills/ folder to wherever your coding agent looks for context files. Check your agent's documentation for the exact path.

Available skills

SurrealQL

A comprehensive reference for the SurrealQL query language, including syntax, schema design, graph traversals, and idiomatic patterns.

npx skills add surrealdb/agent-skills --skill surrealql

!NOTE: Useful for
Authoring SurrealQL queries
Defining and maintaining schemas
Navigating graph relationships and working with record IDs
Transitioning from traditional SQL to SurrealQL
Configuring live queries for real-time data

SurrealDB Vector

Covers vector search in SurrealDB, including creating HNSW indexes, running KNN queries, and applying similarity scoring.

npx skills add surrealdb/agent-skills --skill surrealdb-vector

!NOTE: Useful for
Setting up HNSW vector indexes on tables
Running KNN queries with distance operators
Implementing semantic search, RAG pipelines, or recommendation engines
Fine-tuning HNSW parameters (EFC, M, M0, distance function, type)

SurrealDB Python

Guidance for using the SurrealDB Python SDK in both client/server mode (WebSocket) and embedded mode (in-memory or file-based).

npx skills add surrealdb/agent-skills --skill surrealdb-python

!NOTE: Useful for
Connecting to SurrealDB from Python applications
Working with the surrealdb package (synchronous and asynchronous)
Running SurrealDB embedded in Python without a separate server
Performing CRUD operations from Python code

Discovering community skills

The skills.sh directory catalogues skills published by the wider community. You can also search directly from the command line:

npx skills find QUERY