Yugabytedb schema design

Skill srinivasa-vasu/agent-skills/yugabytedb-schema-design

Best practices for designing high-performance YugabyteDB schemas from scratch or optimizing existing ones. Covers hash vs range sharding decisions, avoiding write hotspots on sequential columns, partial indexes for nullable or skewed columns, low-cardinality index design, covering indexes, primary key selection, foreign key index requirements, and redundant index cleanup. Use this skill whenever the user asks how to design a YugabyteDB schema, choose a sharding strategy, avoid hotspots, optimize indexes, handle NULL-heavy columns, model a table for distributed SQL, or asks "how should I structure this in YugabyteDB". Trigger even when the user mentions "YugabyteDB indexes", "YSQL schema", "tablet hotspot", "sharding key", or asks why their YugabyteDB writes are slow or skewed.From its SKILL.md

Install

npx -y skills add srinivasa-vasu/agent-skills --skill yugabytedb-schema-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.7 KB, 698 tokens by cl100k_base, as published. Nobody here has run it

YugabyteDB Schema Design Best Practices

This skill covers how to design schemas well for YugabyteDB. The design patterns that make a schema performant in a distributed SQL environment.

Core Concepts (Read First)

YugabyteDB is an index-organized, distributed SQL database. Every design decision flows from three foundational facts:

The primary key IS the table. Rows are stored sorted by PK. No PK = system assigns ybrowid (hidden, hash-sharded).
Default sharding is HASH. Data is distributed by hashing the sharding key across tablets. Great for point lookups, bad for range queries.
Tablets split automatically, but hotspots happen. Sequential values (timestamps, auto-increment IDs) written to a range-sharded index concentrate all writes on one tablet until it splits.

Reference Files

Read only the section(s) relevant to the user's question:

references/sharding.md — Hash vs range, when to use each, choosing a sharding key
references/hotspots.md — Preventing write/read hotspots on timestamps and monotonic PKs
references/index-design.md — Index column ordering, covering indexes, redundant indexes
references/partial-indexes.md — Partial indexes for NULL-heavy and skewed-value columns
references/low-cardinality.md — Avoiding poor distribution from boolean/ENUM/low-distinct sharding keys
references/primary-keys.md — PK selection, explicit PKs, composite PKs for partitioned tables
references/foreign-keys.md — FK type alignment, mandatory FK indexes

Quick Decision Guide

User's question	Go to
"Should I use hash or range sharding?"	`sharding.md`
"My timestamp writes are all going to one tablet"	`hotspots.md`
"How do I index this column?"	`index-design.md`
"Half my rows have NULL in this column"	`partial-indexes.md`
"Indexing a status/boolean column"	`low-cardinality.md`
"What should my primary key be?"	`primary-keys.md`
"FK performance is slow"	`foreign-keys.md`
"Can you design schema for this?"	`Refer all the files for the optimal design`
"Can you optimize this schema?"	`Refer all the files for the optimal design`

Golden Rules at a Glance

✅ Always define an explicit PRIMARY KEY
✅ Use ASC/DESC on index columns that are range-queried
✅ Put high-cardinality columns first in multi-column indexes
✅ Index every foreign key column in child tables
✅ Use partial indexes for nullable or skewed columns
✅ Match FK column types exactly (INT vs BIGINT matters)
✅ Drop redundant indexes (prefix-covered by another index)
✅ Use text datatype whereever possible instead of VARCHAR(n)

❌ Never use a low-cardinality column as the sole sharding key
❌ Never range-shard on a monotonically increasing column without a synthetic shard key
❌ Never leave tables without a PK if UNIQUE NOT NULL columns exist
❌ Never create multi-column GIN indexes

What ships with it: 8 files

35.3 KB alongside SKILL.md

references/

README.md3.3 KB

Gives 0 of the 12 instructions most performance cost skills give in 698 tokens

Counted across 803 of the 1,058 authors here whose files we hold, read 2026-08-07

Keep skill files under 500 lines or tokensin 82 of 803, across 16 files
Use imperative form in instructionsin 80 of 803, across 9 files
Draft assertions while test runs are in progressin 75 of 803, across 9 files
Create two to three realistic test promptsin 74 of 803, across 9 files
Write skill descriptions to be pushyin 72 of 803, across 7 files
Save test cases to evals JSONin 72 of 803, across 6 files
Ask questions about edge cases and input formatsin 72 of 803, across 7 files
Save timing data immediately when runs completein 70 of 803, across 5 files
Include all trigger conditions in the skill descriptionin 69 of 803, across 3 files
Launch all test runs in a single turn or simultaneouslyin 69 of 803, across 3 files
Capture intent before writing a skillin 67 of 803, across 1 file
Import directly instead of barrel filesin 52 of 803, across 15 files

Said here and by no other author read

define an explicit primary key
use asc or desc on range-queried index columns
put high-cardinality columns first in multi-column indexes
use partial indexes for nullable or skewed columns
match foreign key column types exactly
drop redundant indexes covered by another index prefix

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.