# Agent Skills

Official SurrealDB agent skills for use in agentic coding workflows.

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](https://agentskills.io/) 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
```

###### 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
```

###### 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
```

###### 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](https://skills.sh/) catalogues skills published by the wider community. You can also search directly from the command line:

```
npx skills find QUERY
```