Introducing ScyllaDB Agent Skills

A new set of best practices and usage patterns for AI agents working with ScyllaDB Cloud clusters

Today we’re releasing a curated set of best practices and usage patterns for AI agents working with ScyllaDB Cloud clusters.

If you just want to grab the skills and go build, here you go:

npx skills add scylladb/agent-skills

If you want to understand why these skills are useful and what problems they solve, read on.

**

You may have noticed a short warning at the bottom of many AI applications:

“AI can make mistakes. Double-check the output.”

Or something along those lines.

This is also true when it comes to working with databases. We’ve seen agents reach for the wrong driver, fail to connect to ScyllaDB Cloud, generate schemas that fit a relational database but not NoSQL, and produce queries that technically execute but perform poorly at scale.

For more on agents getting things wrong, see this video…

These problems can all be minimized by using agent skills.

What are Agent Skills?

Agent Skills are markdown files that give your AI agent best practices and domain-specific knowledge. They follow the standard format and help your agent reduce hallucinations. They are also essential to give the agent up-to-date information. Since LLM training data doesn’t include real-time updates by default, these skills help bridge that gap. A specialized skill helps make the agent’s behavior more consistent and predictable.

Available ScyllaDB Skills

The ScyllaDB Agent Skills cover three distinct areas:

scylladb-cloud-setup: Guides agents through the full connection flow: retrieving cluster credentials from the Cloud Console, selecting the correct shard-aware driver for the user’s language, configuring DC-aware load balancing with the right datacenter name, and verifying the connection.

scylladb-data-modeling: Encodes query-first design methodology, partition key and clustering column patterns, anti-patterns (ALLOW FILTERING, hot partitions, unbounded partition growth), time-series bucketing, and guidance on when to use secondary indexes versus denormalized tables. The goal is to create schemas and queries that hold up under production load (just returning correct results in development is not sufficient).

scylladb-vector-search: Covers vector index creation, ANN queries, filtering strategies (global vs. local indexes and when each applies), quantization, and driver configuration.

You can install all three at once, or pick only what your project needs. Each skill loads on demand when a relevant task comes up, they don’t interfere with each other.

Let’s look at the main areas where AI systems get ScyllaDB wrong.

Shard-aware drivers

ScyllaDB has its own family of shard-aware drivers for Python, Java, Go, Rust, C++, and more. Agents sometimes decide to download the wrong driver. While it may appear to work, unofficial drivers bypass ScyllaDB’s shard-aware routing and degrade performance. In other cases, agents may hallucinate non-existent drivers. Besides making it impossible to connect to the ScyllaDB cluster, this also introduces a security risk: you may install a fake package designed to trick the AI (this is called slopsquatting).

Connecting to ScyllaDB Cloud

Connecting to ScyllaDB Cloud requires DC-aware load balancing configured with the exact datacenter name (e.g. AWS_US_EAST_1) from your cluster. If your agent gets that wrong, the driver will fail to connect.

Data modeling

ScyllaDB’s data model requires you to have a query-first approach. You design tables around your access patterns, not your entities. Agents tend to be trained more heavily on SQL and relational databases than on NoSQL systems such as ScyllaDB. That means they are more likely to generate an entity-first schema, then use ALLOW FILTERING to force queries. This can result in suboptimal performance when using ScyllaDB.

Vector Search

Vector search on ScyllaDB is powerful but specific. There are global and local vector indexes with different filtering semantics and performance considerations. There’s an ANN OF operator, and quantization options that matter at scale. Choosing the wrong index type for a filtered query can hurt performance.

Getting started

Install all skills using the Vercel Skills CLI (requires Node.js):

npx skills add scylladb/agent-skills

Or install a specific skill:

npx skills add scylladb/agent-skills --skill scylladb-data-modeling

You can also install manually by cloning the GitHub repository and copying the skill folders into your agent’s skills directory:

The skills follow the Agent Skills open standard and work with any agent that supports it, including Claude Code, Cursor, Codex, and GitHub Copilot. Native Claude Code and Cursor plugins are coming soon.

We recommend installing all three skills in any project that uses ScyllaDB. You get full coverage of the areas where agents most commonly go wrong, with no overhead when those skills aren’t relevant to the current task.

As of now, the skills cover the CQL interface; Alternator (DynamoDB API) is not yet included.

Feedback is welcome. Create an issue on GitHub!