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

```bash
npx skills add surrealdb/agent-skills
```

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

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

### Manual setup

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

```bash
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.

```bash
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.

```bash
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).

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

```bash
npx skills find QUERY
```

## Further reading

- [SurrealDB Agent Skills](https://github.com/surrealdb/agent-skills)
- [Agent Skills documentation](https://agentskills.io/home)