TL;DR: We built three VeloDB agent skills to give AI assistants the production database expertise: an architecture advisor skill for infrastructure sizing, a best-practice skill for schema design and query troubleshooting, and a cloud-operations skill that adds safety checks to administrative commands. All three skills are open source and encode patterns from 500+ enterprise deployments, tested and hardened against real production failure modes.
The most flexible databases are also the most complex. They offer many configuration options for diverse workloads that power users depend on, while new users struggle to navigate. VeloDB is no exception: a skilled operator can tune queries, design tables, and pick partitions in ways that transform what the system delivers, but those same levers can defeat someone who has not seen them used in production before.
Data agents have made real progress here, but a general-purpose agent will not understand the intricacies of every database or the shape of every workload. So we built agent skills for the three areas where the gap hurts most: architecture and sizing, schema design and performance tuning, and cloud operations. Before we get to how the skills work, it is worth being precise about why these three areas are hard.
What these three areas of database management entail
Architecture and sizing
Sizing is hard because you commit to it before production exists to validate it, and data volume alone will not tell you what to choose. A small database answering complex, high-cardinality queries can be harder to plan for than a large append-only stream.
Most applications also run several competing workloads at once. A single IoT use case may require high-throughput ingestion, mutable state tracking, aggregated analytics, and fast point lookups, each with a different data model. Underestimate the hardware and the system collapses under load; overestimate it, and you pay for capacity you never use.
Schema design and performance tuning
Once the architecture is set, the decisions move to the individual table. A schema in an analytics database is a performance plan disguised as a table definition: partitioning determines which data the engine can skip, the bucket key determines how work spreads across nodes, indexes determine which lookups are cheap, and materialized views determine what gets precomputed. Those choices pay off only when they match how the table is actually queried.
VeloDB hands you every one of these levers but assumes nothing about which you need. A schema can be entirely valid and still wrong: filtered queries scan whole tables, writes pile onto a few nodes, and joins shuffle data across the network. The mistakes are invisible at creation and costly in production.
When a live query slows down, the cause could be hiding almost anywhere. The evidence sits in a query profile that can run to megabytes, and the right fix depends on which step did the wasted work. Adding an index will not help if the real problem is skew, and a bigger cluster usually just hides the issue.
Cloud operations
Managed cloud abstracts the physical servers, but human decisions still govern the platform, and routine commands carry consequences that are not obvious. Resizing a cluster changes its cache. Switching a warehouse drops active sessions. A security tweak can isolate the monitoring tools you rely on.
The platform is exposed to human error and blind scripting. A basic automation script will happily run a command that breaks production. Operational tools must understand how each action affects the system and show the likely impact before any change is applied.
None of these problems is a bug. Each is the cost of a general-purpose engine, and we packaged the judgment they require into three skills.
VeloDB Skills
Each skill maps to one of the task areas above:
velodb-architecture-advisor handles sizing and capacity planning. It analyzes workload metrics (ingestion rates, query patterns, concurrency goals) and delivers a concrete infrastructure design before you deploy your first node.
velodb-best-practices handles table design and live troubleshooting. It evaluates table definitions against 37 performance rules before creation, then analyzes query profiles to find the actual bottleneck when a live query slows down.
velocli-cloud replaces blind automation with intelligent safety checks. It turns routine administrative tasks into repeatable commands while simulating the impact on active sessions, caches, and billing before any change is executed.
The skills did not come from rewriting documentation as prompts. They came from patterns across 11 industry whitepapers and the support cases behind 500 enterprise customers and 5,000 open-source adopters: the design teams keep choosing, the schema mistakes that keep causing slow queries, and the operations that keep needing guardrails. The advisor and best-practice skills trigger together, because sizing and table design should come from the same workload.
How we validated the Skills
We evaluated the skills the way we would evaluate software behavior: define what success means, run the agent against representative tasks, and grade the result against explicit checks. The question was never whether the answer "looked good." It was whether the right skill triggered, whether the agent used the right evidence, and whether the recommendation matched VeloDB best practice.
For each skill we wrote down the behavior that had to be true. The advisor must decompose a workload before sizing it. Best practices must treat CREATE TABLE as a performance plan, not just valid syntax. Troubleshooting must inspect profile evidence before recommending a fix. Cloud operations must build the right command, target the right environment, and gate destructive actions.
The harness checks those behaviors across four layers: activation, where prompts with explicit, implicit, and noisy cues test whether the right skill triggers; deterministic checks, where static DDL rules and mock cloud-command tests catch repeatable failures; evidence use, where troubleshooting must pull structured velocli output (profiles, scan statistics, tablet distribution) before recommending a fix; and rubric-based expert review for the judgments a script cannot make.
Two patterns emerged from the loop. First, the bottleneck is not raw model capability but domain expertise. A capable model still needs procedural knowledge that tells it which bucket-key cardinality causes skew or which sort-key order enables prefix pruning. Second, templates beat rules. Agents copy a validated pattern more reliably than they follow an abstract constraint, and a hard "do not recommend a fix before reading the profile" works better than a gentle "collect evidence first." Every failure becomes a change to the skill itself, so the suite grows into a memory of the production behaviors that the skills must continue to handle.
How to get started with VeloDB Skills yourself
The skills are open source under Apache-2.0. You can install them in one step:
npx skills add velodb/agent-skills
Or clone the repository and run the installer, which auto-detects your agent and offers to install velocli for structured diagnostics:
git clone https://github.com/velodb/agent-skills.git
cd agent-skills && ./install.sh
npm install -g @velodb/velocli
You will need a VeloDB Cloud account or a self-hosted Apache Doris cluster. The repository is at github.com/velodb/agent-skills. If you already run VeloDB or Doris with an AI assistant, hand the skills the workload you are designing, the table you are about to create, or the slow query you are staring at, and see whether the gap closes.
