CLI tool
planetscale/database-skills avatar
planetscale/database-skills

PlanetScale database-skills: four folders, three of them for one vendor's products

Skills for AI agents working with databases

740 stars68 forksHTMLMIT

At a glance

What is it?
This repository is a set of agent skills for database work, distributed as repository content rather than as a package: four skill folders, each holding an instruction file with triggers and a workflow plus an optional folder of reference documents the agent loads only when it needs them. Read the catalogue closely and three of the four are written for one vendor's own products, which tells you what this is before you install it.
Who is it for?
Use these skills if your agent is doing operational work on a PlanetScale database and you would rather it read the vendor's own guidance than improvise, because the trigger lists are written for exactly the situations an on-call engineer recognises, and the reference folders mean the detail arrives only when the task needs it.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 39 days ago.
What is it written in?
Mainly HTML, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 13, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • planetscale/database-skills740 β˜… Β· +69
Star history
Repository2026-09-132026-11-13
planetscale/database-skills671740

69 Stars in the last 61 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Three of the four skills are written for one vendor's own products

The catalogue is four directories and reading the one-line descriptions in order tells you what this repository is. The MySQL skill covers schema, indexing, query tuning, transactions and operations with no vendor attached. The Postgres skill is explicitly written for PlanetScale Postgres, and its triggers name that vendor's own features alongside the general ones. The Vitess skill is likewise scoped to PlanetScale Vitess. The fourth, Neki, is described as PlanetScale's sharded Postgres product. So three of the four are vendor documentation for that vendor's products, republished in a form an agent can load, under a permissive licence. That is not a criticism so much as a fact you should know before installing, and it cuts both ways. If you run on that vendor's platform, these skills are the vendor's own guidance in the one format your agent can actually read, which is worth more than a documentation site it cannot fetch. If you are on a different platform or on open source Postgres, you are getting a vendor's opinions dressed as best practice, and the parts of the trigger lists that name vendor-specific features will simply never match anything you care about.

Triggers are the load mechanism, and a weak one is a skill that never fires

Each skill directory holds one required file and one optional folder. The required file carries instructions, triggers and a workflow. The optional folder holds supporting documents that are loaded into context as needed. That structure is the whole design, and it is worth being precise about how it works, because the format is easy to misuse. The agent does not read the catalogue and does not read everything in a skill. It matches the trigger description against the task in front of it, loads the instruction file when something matches, and reaches for a reference document only when the task has progressed to the point that needs it. Two things follow. The cost is proportional to the task rather than to the size of the corpus, which is what makes this pattern usable with reference documents that would otherwise never fit. And the entire mechanism rests on the quality of the trigger text, because a skill nobody matches is a skill that does not exist. That is why the descriptions here are written as concrete situations rather than as topics. A trigger that says the skill covers Postgres best practices has to be matched semantically against every database question in a conversation. A trigger that lists schema design, indexing, vacuum, write-ahead log tuning, replication, monitoring and connection pooling gives the matcher something concrete to hit. If you write your own skills, that is the field to spend your effort on.

Two install routes, and neither one installs a package

There are two documented ways in and both of them are about content rather than code. The first goes through a skills registry and is a single command run through the Node package runner.

bash
npx skills add planetscale/database-skills

The second is specific to one editor: in that editor's chat you add the repository as a plugin with a slash command.

bash
/add-plugin database-skills

The repository carries the manifest that makes that work, in a directory at the root. Notice what is absent from both. There is no package to add to your dependencies, no version constraint, and no lockfile step, because the unit being installed is a folder of text files and the transport is the version control system itself. That has an obvious upside, which is that you can read every word of what you are about to install, and a less obvious downside, which is that there is no channel for pushing a correction to something you installed last month. You get updates when you update, by whatever mechanism you use for the rest of your dependencies, and the registry's job here is discovery rather than distribution of binaries. For an agent's instruction set that trade is reasonable. For anything that patches behaviour at runtime it would not be, and it is worth checking which category you are in before you assume the same rules apply to both.

The only build step in the repository builds the website

The package manifest at the root is marked private and carries exactly one development dependency, which is the command line tool for deploying a static site to an edge network. Alongside it sit a configuration file for that tool, a website directory, and a screenshot image. The repository's primary language is reported as HTML, which fits: there is more site here than code. The point worth drawing out is what is not present. There is no runtime for these skills, no bundler step, no transpilation, and nothing to compile, because a skill is a markdown file and a directory of documents. The JavaScript exists solely to put a catalogue page online at the project's own domain. That is a tiny surface to audit, and it is also why the package is private: it is not published, so the package manager is being used as a build tool rather than as a distribution channel. If you are reviewing this repository for a supply-chain checklist, the useful observation is that there is almost nothing to review. A malicious change here would be a change to words in a text file, and no automated check in this repository would catch it, which is the real risk surface for a project whose product is instructions.

The triggers are written for the person on call, not the person writing a query

Read the trigger lists as a taxonomy of operations and the shape of this catalogue becomes clear. The MySQL skill fires for slow or locking behaviour, for planning migrations, and for troubleshooting replication and connection problems, not only for creating tables. The Postgres skill adds multi-version concurrency and vacuum, write-ahead log tuning, replication, monitoring, and connection pooling. The Vitess skill adds sharding, keyspace management, virtual schema configuration, online schema changes, and change-data-capture replication. Those are not the vocabulary of a developer writing a first query. Locking behaviour, vacuum, write-ahead log tuning and keyspace management are the vocabulary of someone responsible for a database at three in the morning. So the intended user is an operations engineer with an agent in the room, and the value proposition is that the agent has the runbook rather than improvising from a general model. That also explains the reference folders: runbooks are long, and the format that loads them on demand is what makes a runbook-shaped document set usable at all. If your use case is a developer asking how to write a query, this repository will feel like the wrong tool, because there is no skill here about learning SQL and there is one about what to do when a replica falls behind.

One skill per technology, so cross-cutting questions have no home

The split is by technology, and that axis has a known weakness. The MySQL-compatible sharding layer and MySQL itself overlap in territory: query tuning, indexing and connection problems are plausible matches for both, and nothing in the structure arbitrates which one wins. An agent matching on trigger text will pick whichever description reads closer, and since the sharding layer's description mentions query optimisation and connection troubleshooting in the same breath as MySQL's, that choice is not something you control. The same problem appears at the seams between the two Postgres skills, where a question about how a schema behaves once a table is sharded belongs to both a general Postgres answer and a sharding answer, and the skill format has no way to say that one should be read and then the other. The reference folders are where a cross-cutting document would naturally live, but each folder is described as holding that skill's own supporting documents, and nothing in the documented layout suggests a skill pointing at another skill's files. For a repository this small that is a fair thing to fix in a pull request, and it is the kind of contribution the four-step contributing path is well suited to. What it will not fix is the general shape, since a directory per technology is the natural unit and cross-cutting knowledge is the natural exception.

Contributing is a directory and a file, with nothing to validate them

The contribution path is four steps and worth quoting in full because the absence of a fifth is the interesting part. Fork the repository. Create a new skill directory under the skills folder. Add the required instruction file and, if you need them, a reference folder. Open a pull request. There is no build step to run, no schema to satisfy, no linter in the contributing notes and no test to add, because there is nothing to execute.

code
database-skills/
β”œβ”€β”€ .cursor-plugin/
β”‚   └── plugin.json
β”œβ”€β”€ README.md
└── skills/
    β”œβ”€β”€ mysql/
    β”‚   β”œβ”€β”€ SKILL.md
    β”‚   └── references/
    β”œβ”€β”€ neki/
    β”‚   β”œβ”€β”€ SKILL.md
    β”‚   └── references/
    β”œβ”€β”€ postgres/
    β”‚   β”œβ”€β”€ SKILL.md
    β”‚   └── references/
    └── vitess/
        β”œβ”€β”€ SKILL.md
        └── references/

And there is no continuous integration directory in the repository listing, which means nothing mechanically verifies a submitted skill: not that its trigger description is well formed, not that its references resolve, not that it does not contradict another skill. For a project whose entire product is text that an agent will follow, that is the risk surface, and it is a risk that lives in review rather than in tooling. Two other packaging facts round out the picture. There are no tagged releases, so installation tracks a branch rather than a version. And there is a small mismatch worth naming: the catalogue is a set of vendor-scoped skills published by the vendor under a permissive licence, which means you can fork it and drop the vendor framing, and for anyone who wants that, the contributing path is the cheapest possible route. The last commit on record is 1 October 2026, so the directory is current.

Editorial conclusion

Use these skills if your agent is doing operational work on a PlanetScale database and you would rather it read the vendor's own guidance than improvise, because the trigger lists are written for exactly the situations an on-call engineer recognises, and the reference folders mean the detail arrives only when the task needs it. Do not expect neutrality: three of the four skills are written for one vendor's products, and the two database families overlap enough that a tuning question could reasonably match either. Two things to check before you wire it into a workflow. Decide which skill wins when MySQL and the MySQL-compatible sharding layer both match, because nothing in the structure arbitrates that, and expect to add your own skill for anything outside the four technologies, since the contributing path is a directory and a file and nothing more. Also note that no automation validates a submitted skill, so read what you install the way you would read any other instructions you are about to hand an agent.

Frequently asked questions

What is in the PlanetScale database-skills repository?

Four skill directories, each containing a required instruction file with instructions, triggers and a workflow, plus an optional folder of reference documents. The four cover MySQL, PostgreSQL, Vitess and Neki, the last of which is described as PlanetScale's sharded Postgres product.

How do I install the PlanetScale database skills?

Two documented routes: a single command through a skills registry, or a slash command in Cursor chat that adds the repository as a plugin, which works because the repository carries a plugin manifest. Neither route installs a package; the skills arrive as repository content.

What is the references folder in a database skill for?

It holds optional supporting documents that are loaded into the agent's context as needed rather than up front, which is what keeps a long runbook-shaped document set usable. The instruction file carries the triggers and the workflow; the detail arrives only when a task reaches it.

Do I need Node or a build step to use these skills?

No. The package manifest is marked private and its single development dependency is the tool that deploys the catalogue website, so the JavaScript in the repository exists only to build a site. The skills themselves are markdown files and directories of documents.

How do I add a skill to the database-skills repository?

Fork it, create a directory under the skills folder, add the required instruction file and optionally a reference folder, and open a pull request. There is no automated validation in the repository, so what a submitted skill contains is checked by review rather than by tooling.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/planetscale-database-skills.svg)](https://hysenlabs.com/projects/planetscale-database-skills)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/planetscale-database-skills.svg)](https://hysenlabs.com/projects/planetscale-database-skills)

Was this useful?