skills
Skills that help you configure and get the most out of PlanetScale
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/planetscale/skills with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/planetscale/skills'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/planetscale-skills)HTML
<a href="/listings/planetscale-skills"><img src="/api/listings/planetscale-skills/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
1. **PlanetScale CLI**, authenticated for automation:
brew install planetscale/tap/pscale # or see planetscale.com/cli pscale agent-guide --format json # CLI conventions (or load skill planetscale-pscale-cli-automation) pscale auth check --format json # verify auth; follow next_steps if action_required pscale org list --format json # verify access
Agents should always pass `--format json` on `pscale` commands. Use `pscale sql` for non-interactive queries, not `pscale shell`. See skill `planetscale-pscale-cli-automation` or the CLI repo `AGENTS.md` for full conventions.
2. **Optional: PlanetScale MCP server.** The skills prefer the insights-only MCP server for telemetry analysis when it is available, and fall back to `pscale` / `pscale api` otherwise. Nothing requires MCP.
3. **Recommended: run from your application repository.** The skills work anywhere, but they are significantly better when the agent runs inside the repo that contains the code talking to the database. See [Run it from the repo that uses the database](#run-it-from-the-repo-that-uses-the-database).
Install the skills
The skills work with any agent that reads `SKILL.md` files. Pick the route that fits:
**Setup script (recommended).** Detects installed agents and installs to each of them:
git clone https://github.com/planetscale/skills.git cd skills && script/setup
The script installs to every agent it finds (`~/.cursor/skills/`, `~/.claude/skills/`, `~/.agents/skills/`). For any other agent, pass its skills directory explicitly:
script/setup ~/.codex/skills # or wherever your agent reads skills
**Skills CLI.** If you use the `npx skills` package manager:
npx skills add planetscale/skills -g -y
**Manual.** Copy the `planetscale-*` directories into your agent's skills location:
| Agent | User-level | Project-level | |---|---|---| | Cursor | `~/.cursor/skills/` | `<repo>/.cursor/skills/` | | Claude Code | `~/.claude/skills/` | `<repo>/.claude/skills/` | | Open agent-skills convention | `~/.agents/skills/` | `<repo>/.agents/skills/` | | Anything else | the directory your agent documents for `SKILL.md` files | |
One constraint in all cases: the directories must stay siblings — skills reference each other by relative path (`../planetscale-change-gates-and-approval-contract/SKILL.md`). Each folder is named after its frontmatter `name`, as the agent-skills specification requires, so installers that rename folders by frontmatter name (including the Skills CLI) leave those paths intact.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 263 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # PlanetScale Skills
- A skill pack that turns your coding agent into a PlanetScale database
- reviewer and operator. Point it at an organization and it audits
- configuration, query behavior, open recommendations, and safety posture —
- then, with your approval, does the work: reviewable schema changes,
- instrumentation PRs, webhooks, and scheduled automation.
- Works with any agent that reads `SKILL.md` files — Cursor, Claude Code,
- and anything following the open agent-skills convention. The skills are
- plain markdown instructions; all output is markdown and text. Nothing is
- agent-specific: no plugins, no custom tools, no proprietary rendering.
- ## What it does
- - **Assess** — a read-only, evidence-backed review of one database or a
- whole organization: branch and safety workflow, backups and restore
- posture, credentials, Query Insights, anomalies, SQL comment / query tag
- coverage, open schema recommendations, webhooks, and Traffic Control.
- - **Report** — a single markdown report where every claim carries the
- command that produced it and every recommendation carries a measured
- finding, a gate, and a rollback path.
- - **Execute** — on your approval, changes ship through PlanetScale's own
- safety mechanisms: development branches, pull requests, deploy requests
- with revert windows, warn-before-enforce Traffic Control budgets.
- - **Automate** — scheduled agent loops that sweep recommendations into
- ready-to-ship PRs, watch for query regressions, and detect posture
- drift.
- ## Setup
- ### Prerequisites
- 1. **PlanetScale CLI**, authenticated for automation:
- ```sh
- brew install planetscale/tap/pscale # or see planetscale.com/cli
- pscale agent-guide --format json # CLI conventions (or load skill planetscale-pscale-cli-automation)
- pscale auth check --format json # verify auth; follow next_steps if action_required
- pscale org list --format json # verify access
- ```
- Agents should always pass `--format json` on `pscale` commands. Use `pscale sql`
- for non-interactive queries, not `pscale shell`. See skill `planetscale-pscale-cli-automation`
- or the CLI repo `AGENTS.md` for full conventions.
- 2. **Optional: PlanetScale MCP server.** The skills prefer the
- insights-only MCP server for telemetry analysis when it is available,
- and fall back to `pscale` / `pscale api` otherwise. Nothing requires
- MCP.
- 3. **Recommended: run from your application repository.** The skills
- work anywhere, but they are significantly better when the agent runs
- inside the repo that contains the code talking to the database. See
- [Run it from the repo that uses the database](#run-it-from-the-repo-that-uses-the-database).
- ### Install the skills
- The skills work with any agent that reads `SKILL.md` files. Pick the
- route that fits:
- **Setup script (recommended).** Detects installed agents and installs to
- each of them:
- ```sh
- git clone https://github.com/planetscale/skills.git
- cd skills && script/setup
- ```
- The script installs to every agent it finds (`~/.cursor/skills/`,
- `~/.claude/skills/`, `~/.agents/skills/`). For any other agent, pass its
- skills directory explicitly:
- ```sh
- script/setup ~/.codex/skills # or wherever your agent reads skills
- ```
- **Skills CLI.** If you use the `npx skills` package manager:
- ```sh
- npx skills add planetscale/skills -g -y
- ```
- **Manual.** Copy the `planetscale-*` directories into your agent's skills
- location:
- | Agent | User-level | Project-level |
- |---|---|---|
- | Cursor | `~/.cursor/skills/` | `<repo>/.cursor/skills/` |
- | Claude Code | `~/.claude/skills/` | `<repo>/.claude/skills/` |
- | Open agent-skills convention | `~/.agents/skills/` | `<repo>/.agents/skills/` |
- | Anything else | the directory your agent documents for `SKILL.md` files | |
- One constraint in all cases: the directories must stay siblings — skills
- reference each other by relative path
- (`../planetscale-change-gates-and-approval-contract/SKILL.md`). Each folder is
- named after its frontmatter `name`, as the agent-skills specification
- requires, so installers that rename folders by frontmatter name (including
- the Skills CLI) leave those paths intact.
- ## Usage
- ### Run it from the repo that uses the database
- You can run these skills from anywhere, but they are at their best when
- the agent runs inside the repository that contains the code talking to
- the database. With the codebase in view, the agent can:
- - map expensive query patterns in Insights back to the routes, jobs, and
- ORM calls that produce them
- - add SQLCommenter query tags to your framework so future load is
- attributed automatically
- - fix the code behind findings (N+1s, missing pagination, unindexed
- lookups) instead of only reporting them
- - turn schema recommendations into migrations in your framework's own
- migration system, ready for review as a normal PR
- Without the repository, the assessment still covers everything on the
- database side; it just stops at recommendations where the fix lives in
- code. If your agent supports project-level skills, installing the pack
- into the application repo (for example `<repo>/.cursor/skills/`) gets
- you this by default.
- ### Run an assessment
- Ask in plain language. The orchestrator skill picks up the request and
- runs every phase. For the full treatment, start with a prompt that puts
- everything in scope:
- > Run the full PlanetScale best-practices assessment on my-org/my-db.
- > Review the whole setup against best practices: branch topology and
- > schema-change workflow, safe migrations and deploy requests, backups
- > and restore posture, roles and credentials, connection pooling and
- > network configuration, Query Insights behavior, anomalies, SQL comment
- > / query tag coverage, open schema recommendations, webhooks, and
- > Traffic Control. My application repository is in this workspace:
- > include query attribution and instrumentation recommendations for it,
- > and map findings to the code that produces them.
- > Produce the complete evidence-backed report with IDs for every
- > recommendation. Read-only: propose everything, change nothing.
- Everything in that prompt beyond the first sentence is optional — the
- orchestrator covers all phases by default. Scope it down whenever you
- want less:
- > Check the larger databases in my-org.
- > Audit our query tag coverage and open recommendations.
- The first pass is always read-only. You get the report; nothing changes.
- ### Approve changes
- Every recommendation in the report has an ID. Approve the ones you want:
- > Approve VIT-1 and WEB-1.
- The agent shows the exact commands, expected effect, and rollback plan
- for each approved ID, executes them one at a time, verifies each by
- reading state back, and reports.
- Work that lives inside a review workflow — development branches, pull
- requests, deploy requests — does not need approval to *prepare*. The
- agent's default deliverable for a schema recommendation is the complete
- reviewable unit: a branch with the DDL applied, a PR with the evidence,
- and an open deploy request. Your action is the merge/deploy decision.
- ### Full autonomy (opt-in)
- If you want the agent to execute the whole plan without per-change
- approval, say so explicitly. Three elements are required — an
- unambiguous risk acknowledgment, a named scope, and whether production
- is included:
- > I accept the risk — apply all report recommendations to my-db,
- > production included.
- The agent then plans in dependency order, executes one atomic change at
- a time, verifies each step, streams status the entire way, and halts on
- failure with staged rollbacks. "Go ahead" and "fix everything" do not
- activate this mode; the acknowledgment must be explicit, and it covers
- one run and one scope only.
- ### Scheduled automation
- For unattended runs (cron, CI, agent schedulers), interactive
- acknowledgment is replaced by a **standing authorization**: a committed
- file naming the owner, scope, allowed operations, numeric bounds, expiry
- date, and a status delivery channel. Details and templates are in
- `planetscale-autonomous-execution-mode/SKILL.md`. Recommended loops (see
- `planetscale-mcp-agent-operating-model/SKILL.md`):
- - **Recommendation-to-PR** (daily) — open schema recommendations become
- ready-to-ship branch + PR + deploy request units. No authorization
- needed; it only produces proposals.
- - **Recommendation deployer** (daily) — deploys approved deploy requests
- within authorized bounds. Requires a standing authorization.
- - **Regression watch** (hourly or per-deploy) — diffs query patterns
- against a baseline and reports regressions with the responsible deploy.
- - **Posture drift check** (daily) — reports changes to safety flags,
- webhooks, roles, and backup posture since the last assessment.
- ## Safety model
- Every operation the agent might take is classified before it happens
- (`planetscale-change-gates-and-approval-contract/SKILL.md`):
- | Class | Scope | Default |
- |---|---|---|
- | A | Read-only: list, inspect, report | Runs freely |
- | B | Proposals: dev branches, PRs, deploy requests, restore tests | Runs freely — the review workflow is the gate |
- | C | Behavior-changing: safety flags, webhooks, roles, budgets | Approval or authorization required |
- | D | Production data/availability: deploys, DDL, deletions, credentials | Approval + named target + rollback plan |
- | E | Destructive without recourse: drop production data, disable all safety, expose secrets | Never executed autonomously, under any phrasing |
- Two properties hold in every mode, including full autonomy: a change is
- verified by reading state back (not by command exit codes), and every
- run produces an audit log. Reports end with the same contract line:
- > No changes have been applied. Approve specific change IDs before any
- > mutation.
- ## The skills
- | Skill | Role |
- |---|---|
- | planetscale-safe-orchestrator | Runs the full assessment end to end; the usual entry point |
- | planetscale-readonly-inventory | Evidence collection: org, branches, backups, webhooks, roles |
- | planetscale-vitess-safety-review | Vitess: safe migrations, deploy requests, revert, sharding |
- | planetscale-postgres-safety-review | Postgres: roles, pg_strict, Traffic Control, PITR, pooling |
- | planetscale-query-insights-and-tags | Query behavior, anomaly review, tag coverage and cardinality |
- | planetscale-traffic-control-recommendations | Warn-first budget plans for Postgres traffic slices |
- | planetscale-webhook-automation-recommendations | Event routing, receiver requirements, automation flows |
- | planetscale-schema-recommendations-agent-loop | Recommendation triage into reviewable units |
- | planetscale-codebase-sqlcommenter-instrumentation | Repository review and query-tagging PR plans |
- | planetscale-mcp-agent-operating-model | Agent/MCP configuration and scheduled loop catalog |
- | planetscale-customer-report-template | Report format, tone, and evidence requirements |
- | planetscale-change-gates-and-approval-contract | The Class A–E permission model |
- | planetscale-best-practices-matrix | Per-engine coverage checklist so assessments miss nothing |
- | planetscale-autonomous-execution-mode | Risk-acknowledged autonomy: contract, status protocol, halt rules |
- | planetscale-pscale-cli-automation | Driving `pscale` headless: `--format json`, auth check, `pscale sql` |
- Each skill is a standalone `SKILL.md` — readable as documentation,
- executable by the agent. Start with `planetscale-safe-orchestrator/SKILL.md` to
- see how a full run fits together.
- ## Disclaimer
- These skills direct AI agents that read from and — with your approval —
- make changes to databases and infrastructure. Agent behavior is not
- deterministic, and no safety model eliminates risk. You are responsible
- for reviewing changes before they are applied, for maintaining backups,
- and for the consequences of enabling autonomous execution or scheduled
- automation.
- This software is provided "as is", without warranty of any kind.
- PlanetScale, Inc. accepts no liability for any damages, data loss,
- downtime, or costs arising from its use, as set out in the
- [LICENSE](LICENSE). These skills are not part of the PlanetScale
- service and are not covered by any service agreement or SLA.
- ## License
- MIT — see [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.