Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/planetscale-skills/badge.svg)](/listings/planetscale-skills)

HTML

<a href="/listings/planetscale-skills"><img src="/api/listings/planetscale-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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)

  1. # PlanetScale Skills
  2. A skill pack that turns your coding agent into a PlanetScale database
  3. reviewer and operator. Point it at an organization and it audits
  4. configuration, query behavior, open recommendations, and safety posture —
  5. then, with your approval, does the work: reviewable schema changes,
  6. instrumentation PRs, webhooks, and scheduled automation.
  7. Works with any agent that reads `SKILL.md` files — Cursor, Claude Code,
  8. and anything following the open agent-skills convention. The skills are
  9. plain markdown instructions; all output is markdown and text. Nothing is
  10. agent-specific: no plugins, no custom tools, no proprietary rendering.
  11. ## What it does
  12. - **Assess** — a read-only, evidence-backed review of one database or a
  13. whole organization: branch and safety workflow, backups and restore
  14. posture, credentials, Query Insights, anomalies, SQL comment / query tag
  15. coverage, open schema recommendations, webhooks, and Traffic Control.
  16. - **Report** — a single markdown report where every claim carries the
  17. command that produced it and every recommendation carries a measured
  18. finding, a gate, and a rollback path.
  19. - **Execute** — on your approval, changes ship through PlanetScale's own
  20. safety mechanisms: development branches, pull requests, deploy requests
  21. with revert windows, warn-before-enforce Traffic Control budgets.
  22. - **Automate** — scheduled agent loops that sweep recommendations into
  23. ready-to-ship PRs, watch for query regressions, and detect posture
  24. drift.
  25. ## Setup
  26. ### Prerequisites
  27. 1. **PlanetScale CLI**, authenticated for automation:
  28. ```sh
  29. brew install planetscale/tap/pscale # or see planetscale.com/cli
  30. pscale agent-guide --format json # CLI conventions (or load skill planetscale-pscale-cli-automation)
  31. pscale auth check --format json # verify auth; follow next_steps if action_required
  32. pscale org list --format json # verify access
  33. ```
  34. Agents should always pass `--format json` on `pscale` commands. Use `pscale sql`
  35. for non-interactive queries, not `pscale shell`. See skill `planetscale-pscale-cli-automation`
  36. or the CLI repo `AGENTS.md` for full conventions.
  37. 2. **Optional: PlanetScale MCP server.** The skills prefer the
  38. insights-only MCP server for telemetry analysis when it is available,
  39. and fall back to `pscale` / `pscale api` otherwise. Nothing requires
  40. MCP.
  41. 3. **Recommended: run from your application repository.** The skills
  42. work anywhere, but they are significantly better when the agent runs
  43. inside the repo that contains the code talking to the database. See
  44. [Run it from the repo that uses the database](#run-it-from-the-repo-that-uses-the-database).
  45. ### Install the skills
  46. The skills work with any agent that reads `SKILL.md` files. Pick the
  47. route that fits:
  48. **Setup script (recommended).** Detects installed agents and installs to
  49. each of them:
  50. ```sh
  51. git clone https://github.com/planetscale/skills.git
  52. cd skills && script/setup
  53. ```
  54. The script installs to every agent it finds (`~/.cursor/skills/`,
  55. `~/.claude/skills/`, `~/.agents/skills/`). For any other agent, pass its
  56. skills directory explicitly:
  57. ```sh
  58. script/setup ~/.codex/skills # or wherever your agent reads skills
  59. ```
  60. **Skills CLI.** If you use the `npx skills` package manager:
  61. ```sh
  62. npx skills add planetscale/skills -g -y
  63. ```
  64. **Manual.** Copy the `planetscale-*` directories into your agent's skills
  65. location:
  66. | Agent | User-level | Project-level |
  67. |---|---|---|
  68. | Cursor | `~/.cursor/skills/` | `<repo>/.cursor/skills/` |
  69. | Claude Code | `~/.claude/skills/` | `<repo>/.claude/skills/` |
  70. | Open agent-skills convention | `~/.agents/skills/` | `<repo>/.agents/skills/` |
  71. | Anything else | the directory your agent documents for `SKILL.md` files | |
  72. One constraint in all cases: the directories must stay siblings — skills
  73. reference each other by relative path
  74. (`../planetscale-change-gates-and-approval-contract/SKILL.md`). Each folder is
  75. named after its frontmatter `name`, as the agent-skills specification
  76. requires, so installers that rename folders by frontmatter name (including
  77. the Skills CLI) leave those paths intact.
  78. ## Usage
  79. ### Run it from the repo that uses the database
  80. You can run these skills from anywhere, but they are at their best when
  81. the agent runs inside the repository that contains the code talking to
  82. the database. With the codebase in view, the agent can:
  83. - map expensive query patterns in Insights back to the routes, jobs, and
  84. ORM calls that produce them
  85. - add SQLCommenter query tags to your framework so future load is
  86. attributed automatically
  87. - fix the code behind findings (N+1s, missing pagination, unindexed
  88. lookups) instead of only reporting them
  89. - turn schema recommendations into migrations in your framework's own
  90. migration system, ready for review as a normal PR
  91. Without the repository, the assessment still covers everything on the
  92. database side; it just stops at recommendations where the fix lives in
  93. code. If your agent supports project-level skills, installing the pack
  94. into the application repo (for example `<repo>/.cursor/skills/`) gets
  95. you this by default.
  96. ### Run an assessment
  97. Ask in plain language. The orchestrator skill picks up the request and
  98. runs every phase. For the full treatment, start with a prompt that puts
  99. everything in scope:
  100. > Run the full PlanetScale best-practices assessment on my-org/my-db.
  101. > Review the whole setup against best practices: branch topology and
  102. > schema-change workflow, safe migrations and deploy requests, backups
  103. > and restore posture, roles and credentials, connection pooling and
  104. > network configuration, Query Insights behavior, anomalies, SQL comment
  105. > / query tag coverage, open schema recommendations, webhooks, and
  106. > Traffic Control. My application repository is in this workspace:
  107. > include query attribution and instrumentation recommendations for it,
  108. > and map findings to the code that produces them.
  109. > Produce the complete evidence-backed report with IDs for every
  110. > recommendation. Read-only: propose everything, change nothing.
  111. Everything in that prompt beyond the first sentence is optional — the
  112. orchestrator covers all phases by default. Scope it down whenever you
  113. want less:
  114. > Check the larger databases in my-org.
  115. > Audit our query tag coverage and open recommendations.
  116. The first pass is always read-only. You get the report; nothing changes.
  117. ### Approve changes
  118. Every recommendation in the report has an ID. Approve the ones you want:
  119. > Approve VIT-1 and WEB-1.
  120. The agent shows the exact commands, expected effect, and rollback plan
  121. for each approved ID, executes them one at a time, verifies each by
  122. reading state back, and reports.
  123. Work that lives inside a review workflow — development branches, pull
  124. requests, deploy requests — does not need approval to *prepare*. The
  125. agent's default deliverable for a schema recommendation is the complete
  126. reviewable unit: a branch with the DDL applied, a PR with the evidence,
  127. and an open deploy request. Your action is the merge/deploy decision.
  128. ### Full autonomy (opt-in)
  129. If you want the agent to execute the whole plan without per-change
  130. approval, say so explicitly. Three elements are required — an
  131. unambiguous risk acknowledgment, a named scope, and whether production
  132. is included:
  133. > I accept the risk — apply all report recommendations to my-db,
  134. > production included.
  135. The agent then plans in dependency order, executes one atomic change at
  136. a time, verifies each step, streams status the entire way, and halts on
  137. failure with staged rollbacks. "Go ahead" and "fix everything" do not
  138. activate this mode; the acknowledgment must be explicit, and it covers
  139. one run and one scope only.
  140. ### Scheduled automation
  141. For unattended runs (cron, CI, agent schedulers), interactive
  142. acknowledgment is replaced by a **standing authorization**: a committed
  143. file naming the owner, scope, allowed operations, numeric bounds, expiry
  144. date, and a status delivery channel. Details and templates are in
  145. `planetscale-autonomous-execution-mode/SKILL.md`. Recommended loops (see
  146. `planetscale-mcp-agent-operating-model/SKILL.md`):
  147. - **Recommendation-to-PR** (daily) — open schema recommendations become
  148. ready-to-ship branch + PR + deploy request units. No authorization
  149. needed; it only produces proposals.
  150. - **Recommendation deployer** (daily) — deploys approved deploy requests
  151. within authorized bounds. Requires a standing authorization.
  152. - **Regression watch** (hourly or per-deploy) — diffs query patterns
  153. against a baseline and reports regressions with the responsible deploy.
  154. - **Posture drift check** (daily) — reports changes to safety flags,
  155. webhooks, roles, and backup posture since the last assessment.
  156. ## Safety model
  157. Every operation the agent might take is classified before it happens
  158. (`planetscale-change-gates-and-approval-contract/SKILL.md`):
  159. | Class | Scope | Default |
  160. |---|---|---|
  161. | A | Read-only: list, inspect, report | Runs freely |
  162. | B | Proposals: dev branches, PRs, deploy requests, restore tests | Runs freely — the review workflow is the gate |
  163. | C | Behavior-changing: safety flags, webhooks, roles, budgets | Approval or authorization required |
  164. | D | Production data/availability: deploys, DDL, deletions, credentials | Approval + named target + rollback plan |
  165. | E | Destructive without recourse: drop production data, disable all safety, expose secrets | Never executed autonomously, under any phrasing |
  166. Two properties hold in every mode, including full autonomy: a change is
  167. verified by reading state back (not by command exit codes), and every
  168. run produces an audit log. Reports end with the same contract line:
  169. > No changes have been applied. Approve specific change IDs before any
  170. > mutation.
  171. ## The skills
  172. | Skill | Role |
  173. |---|---|
  174. | planetscale-safe-orchestrator | Runs the full assessment end to end; the usual entry point |
  175. | planetscale-readonly-inventory | Evidence collection: org, branches, backups, webhooks, roles |
  176. | planetscale-vitess-safety-review | Vitess: safe migrations, deploy requests, revert, sharding |
  177. | planetscale-postgres-safety-review | Postgres: roles, pg_strict, Traffic Control, PITR, pooling |
  178. | planetscale-query-insights-and-tags | Query behavior, anomaly review, tag coverage and cardinality |
  179. | planetscale-traffic-control-recommendations | Warn-first budget plans for Postgres traffic slices |
  180. | planetscale-webhook-automation-recommendations | Event routing, receiver requirements, automation flows |
  181. | planetscale-schema-recommendations-agent-loop | Recommendation triage into reviewable units |
  182. | planetscale-codebase-sqlcommenter-instrumentation | Repository review and query-tagging PR plans |
  183. | planetscale-mcp-agent-operating-model | Agent/MCP configuration and scheduled loop catalog |
  184. | planetscale-customer-report-template | Report format, tone, and evidence requirements |
  185. | planetscale-change-gates-and-approval-contract | The Class A–E permission model |
  186. | planetscale-best-practices-matrix | Per-engine coverage checklist so assessments miss nothing |
  187. | planetscale-autonomous-execution-mode | Risk-acknowledged autonomy: contract, status protocol, halt rules |
  188. | planetscale-pscale-cli-automation | Driving `pscale` headless: `--format json`, auth check, `pscale sql` |
  189. Each skill is a standalone `SKILL.md` — readable as documentation,
  190. executable by the agent. Start with `planetscale-safe-orchestrator/SKILL.md` to
  191. see how a full run fits together.
  192. ## Disclaimer
  193. These skills direct AI agents that read from and — with your approval —
  194. make changes to databases and infrastructure. Agent behavior is not
  195. deterministic, and no safety model eliminates risk. You are responsible
  196. for reviewing changes before they are applied, for maintaining backups,
  197. and for the consequences of enabling autonomous execution or scheduled
  198. automation.
  199. This software is provided "as is", without warranty of any kind.
  200. PlanetScale, Inc. accepts no liability for any damages, data loss,
  201. downtime, or costs arising from its use, as set out in the
  202. [LICENSE](LICENSE). These skills are not part of the PlanetScale
  203. service and are not covered by any service agreement or SLA.
  204. ## License
  205. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.