Teach Claude YugabyteDB Best Practices with YugabyteDB Agent Skills

AI coding assistants are useful, but they do not automatically know the best way to design schemas, indexes, transactions, or application patterns for a distributed SQL database.

That is where the new YugabyteDB Agent Skills repository comes in.

The repository gives AI agents structured YugabyteDB guidance so they can produce better answers for YSQL, YCQL, YugabyteDB Anywhere APIs, and Kubernetes-based deployments.

🧠 Key Insight
Instead of repeatedly telling your AI assistant, “Remember, YugabyteDB is distributed, indexes may require remote reads, use hash/range sharding carefully, and check Storage Read Requests,” you can install a YugabyteDB skill once and let the agent load that guidance when needed.

What Are YugabyteDB Agent Skills?

The YugabyteDB skills repo is a collection of reusable AI agent instructions.

Today it includes skills for:

Skill	What It Helps With
`ysql`	YSQL schema design, indexes, smart drivers, transactions, retries, sharding, migrations, and production readiness
`ycql`	YCQL table design, partition keys, clustering columns, indexes, prepared statements, TTL, and batching
`yb-k8s-operator`	Deploying and managing YugabyteDB universes on Kubernetes
`yba-api`	Using the YugabyteDB Anywhere REST API to create, observe, manage, and deploy universes

For this tip, we will focus on the ysql skill.

Option 1: Use Claude Free with a Custom Skill Upload

Claude Skills are available on Free, Pro, Max, Team, and Enterprise plans, but code execution and file creation must be enabled.

In Claude:

1. Go to Settings → Capabilities
2. Enable Code execution and file creation
3. Go to Customize → Skills
4. Click the + button
5. Choose Create skill
6. Choose Upload a skill
7. Upload a ZIP file containing the YugabyteDB ysql skill folder

To create the ZIP locally:

				
					git clone https://github.com/yugabyte/yugabytedb-skills.git
cd yugabytedb-skills/skills

zip -r ysql.zip ysql

Upload ysql.zip into Claude.

Option 2: Install with the Skills CLI

For local AI agent workflows, you can install all available YugabyteDB skills with:

				
					npx skills add yugabyte/yugabytedb-skills

Or install only the YSQL skill:

				
					npx skills add yugabyte/yugabytedb-skills -s ysql

Other targeted installs include:

				
					# Cassandra-compatible YCQL API
npx skills add yugabyte/yugabytedb-skills -s ycql

# YugabyteDB Anywhere REST API
npx skills add yugabyte/yugabytedb-skills -s yba-api

Demo 1: Ask Claude to Review a PostgreSQL Schema for YugabyteDB

Now for the fun part.

After enabling the ysql skill, ask Claude something like this:

				
					Use the YugabyteDB YSQL skill.

Review this PostgreSQL table design for YugabyteDB.
Point out any distributed SQL concerns and suggest a better schema.

CREATE TABLE events (
    id BIGSERIAL PRIMARY KEY,
    tenant_id UUID NOT NULL,
    event_ts TIMESTAMPTZ NOT NULL DEFAULT now(),
    event_type TEXT NOT NULL,
    payload JSONB
);

CREATE INDEX idx_events_event_ts ON events (event_ts DESC);
CREATE INDEX idx_events_tenant_ts ON events (tenant_id, event_ts DESC);

A good YugabyteDB-aware answer should flag several things:

And provide a recommended schema specific to YugabyteDB:

				
					-- Level 1: Fix the hotspot with a hash+range primary key
-- Use a UUID surrogate key (random distribution) instead of BIGSERIAL,
-- OR keep a sequential ID but force HASH sharding.

CREATE TABLE events (
    id          UUID        NOT NULL DEFAULT gen_random_uuid(),
    tenant_id   UUID        NOT NULL,
    event_ts    TIMESTAMPTZ NOT NULL DEFAULT now(),
    event_type  TEXT        NOT NULL,
    payload     JSONB,
    PRIMARY KEY ((tenant_id) HASH, event_ts DESC, id ASC)
    --           ^^^^^^^^^^^^       ^^^^^^^^^^^^^^  ^^^^^^
    --           Hash by tenant:    Range within    Tie-breaker
    --           distributes        tenant for      for uniqueness
    --           writes evenly      efficient scans
);

-- Level 2: Covering index eliminates main-table fetch RPCs
-- for the most common query: "latest N events for a tenant"
CREATE INDEX idx_events_tenant_ts_cover
    ON events (tenant_id HASH, event_ts DESC)
    INCLUDE (event_type, payload);

-- Level 3 (high ingest only): Bucket the global timestamp index
-- to spread writes across shards.
-- Only add this if you have genuine cross-tenant time-range queries.
CREATE INDEX idx_events_ts_bucketed
    ON events ( (yb_hash_code(event_ts) % 8), event_ts DESC )
    INCLUDE (tenant_id, event_type);

…plus a few additional details that I’ll leave for you to discover when you run your own test!

⚠️ Note

Do not blindly accept AI-generated DDL. The skill helps the agent reason with YugabyteDB-specific context, but you should still validate every recommendation against the workload, query patterns, data distribution, and production requirements.

Claude correctly identified that monotonically increasing access paths can be risky in a distributed SQL database, especially when they are used as the leading column of a range-sharded primary key or index. However, the answer overstated the behavior of BIGSERIAL PRIMARY KEY.

In YugabyteDB, hash splitting is enabled by default, as shown by the setting yb_use_hash_splitting_by_default = on, which “enables hash splitting as the default method for primary key and index sorting in LSM indexes.” Because of that, a simple key like id BIGSERIAL PRIMARY KEY is hash-sharded by default.

That means inserts are distributed by the hash of the generated id value. They do not automatically all go to the “highest” range tablet. That hotspot concern would apply to an explicitly range-sharded key, such as PRIMARY KEY (id ASC).

The better takeaway is that AI-generated recommendations can be useful, but they still need expert review around YugabyteDB-specific details like hash sharding, range sharding, indexes, and workload access patterns.

Demo 2: Ask for a Covering Index Recommendation

Try a second prompt:

				
					Use the YugabyteDB YSQL skill.

This query runs frequently. Recommend an index for YugabyteDB and explain why.

SELECT tenant_id, event_ts, event_type
FROM events
WHERE tenant_id = $1
  AND event_ts >= now() - interval '1 day'
ORDER BY event_ts DESC
LIMIT 100;

A good answer should suggest an index shaped around the filter and sort pattern:

				
					CREATE INDEX idx_events_tenant_ts_cover
    ON events (tenant_id HASH, event_ts DESC)
    INCLUDE (event_type);

And…

Note that Claude provides even more detail than shown here. I’ll leave the rest for you to discover when you run the demo yourself!

Conclusion

YugabyteDB Agent Skills are a simple way to make AI assistants more useful for distributed SQL work. By giving tools like Claude YugabyteDB-specific guidance, you can get better first drafts for schema reviews, index recommendations, troubleshooting checklists, and migration planning.

But the demo also shows an important reminder: AI-generated answers still need human review. The skill can point the assistant in the right direction, but you should always validate the output against YugabyteDB behavior, your workload, your query patterns, and your production requirements.

Used correctly, YugabyteDB Agent Skills can be a great starting point, helping you move faster while still keeping expert review in the loop.

✅ Final Takeaway
YugabyteDB Agent Skills are a simple way to make AI assistants more YugabyteDB-aware. They will not replace testing, benchmarking, or human review, but they can dramatically improve the first draft of schema designs, index recommendations, migration reviews, and troubleshooting checklists.

Useful Links

Resource	Description
YugabyteDB Agent Skills	GitHub repository containing reusable YugabyteDB skills for AI agents
YugabyteDB Docs	Official YugabyteDB documentation
skills.sh	Open Agent Skills ecosystem

Have Fun!

Maple, our daughter’s pampered dog, enjoys a good scratch now and then… but honestly, who doesn’t?