planetscale/database-skills: Markdown Skill Packs for Database Work in AI Coding Assistants

The gap this fills: assistants that write SQL without database context

A general-purpose coding assistant asked to add an index or rewrite a query produces something syntactically valid and frequently wrong for the engine in front of it. It does not know that the table is sharded, that a keyspace has a VSchema, or that the connection path runs through a pooler. The repository's premise is that this context should be shipped as files the assistant reads, rather than as a service it calls. Each skill is scoped to one technology: mysql covers InnoDB schema, indexing, query tuning, transactions and operations; postgres covers PostgreSQL best practices, MVCC and VACUUM, WAL tuning, replication and PlanetScale-specific features such as connection pooling and CLI insights; vitess covers sharding, VSchema configuration, keyspace management, online DDL and VReplication; neki covers PlanetScale's sharded Postgres product. The audience is narrow by design. If you never touch a PlanetScale database and never touch Vitess, two of the four skills are dead weight, and the mysql and postgres skills are competing with whatever your assistant already absorbed during training.

What is actually in the box: SKILL.md plus a references directory

The repository layout is the whole architecture. Under skills/ there are four sub-directories, each holding a SKILL.md and a references/ folder. The README states that SKILL.md is required and contains the instructions, triggers and workflow for the skill, while references/ is optional and holds supporting documents loaded into context as needed. That two-tier split is the only real mechanism here, and it is a deliberate one: the trigger text stays small so the assistant can decide whether the skill applies, and the bulk of the material sits in references/ until something pulls it in. There is no index format documented beyond that, no manifest listing which reference files exist, and no stated size budget for either tier. The root also carries a .cursor-plugin/plugin.json, which is what makes the Cursor install path work. Nothing in the README describes a runtime, a daemon, a query engine or a connection to your database. Everything the assistant gets is text.

Installing through skills.sh or as a Cursor plugin

Two installation routes are documented. The first is skills.sh, invoked with npx skills add planetscale/database-skills. The README points to skills.sh for further detail rather than explaining what the command writes to disk or where. The second is the Cursor plugin route: run /add-plugin database-skills inside Cursor chat, which reads the .cursor-plugin/plugin.json at the repository root. Both are one-liners, and both depend on a host application that understands the convention. If your assistant has no notion of skills or plugins, neither command helps you; you would be copying Markdown by hand. There is also no configuration surface described in the README. No environment variables, no config keys, no per-skill enable or disable flags. The only tuning knob the material exposes is editing the files themselves, which is legitimate but means every local change is a fork you now maintain.

The maintenance problem: no releases, no changelog, no version pin

The repository has no releases retrieved, which means there is no tag to pin against and no changelog to scan before an upgrade. The last push recorded is 2026-08-28, so the project is active, but activity without versioning gives you a moving target: npx skills add planetscale/database-skills resolves to the default branch, and the default branch is main. When the maintainers revise a SKILL.md trigger or rewrite a reference document, your next install picks up the change with nothing to diff against. For a library this is annoying. For instruction files fed to an AI agent it is a different category of problem, because the content steers generated SQL. A tightened trigger phrase can change which queries the assistant proposes. Practically, the only stable approach is to vendor the four skill directories into your own repository at a commit you chose, and treat upstream as a source to re-read rather than a dependency to update. The README does not suggest this, and the install commands point the other way. That mismatch is the sharpest thing about the project.

Where the skills approach stops working

Instruction files cannot see your database. A skill can tell the assistant to consider index selectivity or to think about VACUUM behaviour, but it cannot report that a particular query is doing a sequential scan on a table with forty million rows, because nothing in this repository connects to a server. That is a boundary, not a defect, and it matters when you compare the repository to tooling that does connect. A query analyzer or an EXPLAIN-driven advisor reads real statistics and returns real plans; database-skills reads nothing and returns guidance. The second limitation is coverage. Four skills exist, and two of them, vitess and neki, are tied to PlanetScale products specifically. A team running self-managed PostgreSQL on RDS gets the postgres skill, which the README describes as covering PlanetScale Postgres and PlanetScale-specific features, so parts of it will simply not apply. The third is that skill loading is host-dependent: the README does not state which assistants honour SKILL.md, and nothing in the material confirms whether an assistant loads references/ automatically or only when it decides to. If your host ignores the convention, the install succeeds and nothing changes about your assistant's output.

Compared with pgvector-style retrieval or a plain style guide

The closest thing most teams already have is a wiki page of database conventions, pasted into a prompt when someone remembers. That approach has no trigger mechanism and no lazy loading, so either the whole document goes into context on every request or none of it does. The skills layout improves on this by splitting triggers from references, which is the same instinct behind retrieval-augmented setups that chunk documentation and fetch only relevant passages. The difference is where the decision is made. A retrieval system scores chunks against the current question using embeddings and a vector store; database-skills hands the decision to the assistant reading SKILL.md, with no scoring, no index and no infrastructure. That is cheaper to run and easier to audit, since every file is readable Markdown in a git repository. It is also less predictable, because the routing quality depends on how well the trigger prose was written. If you need deterministic retrieval over a large corpus of internal database documentation, this repository is not that, and no amount of editing SKILL.md will make it that.

Licence and the cost of contributing a fifth skill

The repository is MIT-licensed, which permits use, modification and redistribution provided the copyright notice and permission notice are retained. That matters more than usual here, because the natural way to use these files is to edit them, and MIT gives you clear room to do so and to keep your edits private or publish them. It does not give you rights to the PlanetScale trademarks or product names that appear throughout, and it says nothing about the accuracy of the technical guidance itself, which is the thing you are actually relying on. The contribution path is documented and flat: fork the repo, create a new directory under skills/, add a SKILL.md and optional references/, submit a PR. There is no test harness, no schema for SKILL.md, and no validation step mentioned, so a contributed skill is reviewed on prose quality alone. If you add a skill for, say, SQLite or CockroachDB, you are maintaining it yourself against a default branch that can move under you. Weigh that before treating the four existing skills as a platform to build on rather than a set of documents to read.

Editorial conclusion

Adopt it if you already run an assistant that supports the skills convention and you work on MySQL, PlanetScale Postgres, Vitess or Neki, because the payload is plain Markdown you can read and edit before trusting it. Do not adopt it if you expect a runtime component: there is no server, no CLI, and no versioned release to pin. Before wiring it into a workflow, open skills/mysql/SKILL.md and skills/postgres/SKILL.md and check that the triggers and workflow match your engine version and your actual schema, since the repository publishes no releases and no changelog to tell you when that content shifts.

Official sources

1. Issues
2. License: MIT
3. planetscale/database-skills on GitHub
4. Project website
5. README