PlanetScale Skills
Fifteen skills to audit and safely change PlanetScale databases: evidence-backed report, branches, deploy requests, rollback
- 136 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- With an authenticated pscale the agent sees the organization, branches, roles and backup settings
- After your approval the agent deploys schema changes and alters safety settings of a production database
- In autonomous mode and scheduled runs changes go ahead without a per-step confirmation, with rollback on failure
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/planetscale-skillsDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- With an authenticated pscale the agent sees the organization, branches, roles and backup settings
- After your approval the agent deploys schema changes and alters safety settings of a production database
- In autonomous mode and scheduled runs changes go ahead without a per-step confirmation, with rollback on failure
This is third-party code. Review the repository files before installing.
What it does
A set of fifteen skills turns an agent into a reviewer and operator for PlanetScale databases on Vitess and Postgres. The entry point is planetscale-safe-orchestrator: it walks through the organization inventory, the safety review for the chosen engine, Query Insights, Traffic Control, webhooks, schema recommendations and query tags in the application code, then compiles one Markdown report. Every claim in the report carries the command that produced it, and every recommendation has a measured finding, a gate and a rollback path. The first pass only reads. Then you name recommendation IDs, for example VIT-1 and WEB-1, and the agent shows the exact commands, expected effect and rollback plan, runs the changes one at a time and verifies each by reading state back. For schema work it prepares a development branch, a pull request and an open deploy request, so the merge decision stays with you. All operations fall into classes A to E, and irreversible data deletion, class E, is never run by the agent under any phrasing. Separate skills drive recurring loops: turning recommendations into ready pull requests daily, watching for query regressions, and checking for drift in safety settings.
Who it is for. Developers and database administrators on PlanetScale who want a regular audit of settings, queries and migrations with a clear rollback plan.
Good fit when
- Before a release you want to review the whole PlanetScale organization: branches, backups, roles and open recommendations
- Queries in Insights are slow and you cannot tell where they come from in the code: the agent maps them to routes, jobs and ORM calls
- Schema recommendations pile up unattended and should become a branch with DDL, a PR and a deploy request
- On Postgres you need Traffic Control budgets, starting in warn mode
- After every deploy you want query patterns compared with a baseline to catch regressions
Not a fit when
- You need a one-off SQL query: `pscale sql` is enough, while the orchestrator runs the full assessment across all phases
- The database is not on PlanetScale: every skill depends on `pscale`, Query Insights and deploy requests
- You expect a ready MCP server: the skills only prefer one for telemetry when it is already connected and do not install it
Example request
Run the full PlanetScale assessment on my-org/my-db in read-only mode: propose changes with IDs but apply nothingLimitations
The skills are not part of the PlanetScale service and carry no service-level agreement: the authors remind you that agent behavior is non-deterministic. Automation needs the PlanetScale CLI with completed authentication, and queries go through `pscale sql`, not the interactive shell. The skills refer to each other by relative paths, so the planetscale-* folders must stay side by side. Scheduled runs without a person require a standing authorization: a file naming the owner, scope, allowed operations, numeric bounds and an expiry date.
How to disable. Delete the planetscale-* folders from the agent's skills directory, for example `~/.claude/skills/` or `~/.cursor/skills/`. If you enabled scheduled runs, remove the job from the scheduler and the standing authorization file, and end the CLI session with `pscale auth logout`.
FAQ
How do I start an assessment of a PlanetScale database?
Describe the task in plain words, the orchestrator picks up the request and runs every phase. To narrow the scope, name the database or the topic, for example query tag coverage. The first pass produces a report with recommendation IDs and changes nothing.
What is class E in the safety model?
Irreversible actions: dropping production data, disabling every safeguard and exposing secrets. The agent does not run them autonomously under any phrasing, even in full autonomy mode.
How do I enable full autonomy?
It takes an explicit phrase with three elements: an acknowledgment of risk, a named scope and whether production is included, for example "I accept the risk — apply all report recommendations to my-db, production included". Saying go ahead or fix everything does not enable it, and the permission covers one run and one scope.
Do I need the PlanetScale MCP server?
No. When an MCP server is connected the skills take Insights telemetry from it, and without it they work through `pscale` and `pscale api`.
How do I install the skills in Codex?
Run `script/setup ~/.codex/skills` in the cloned repository: the path to the Codex skills folder is passed to the script explicitly. For other agents substitute their directory the same way or copy the planetscale-* folders by hand.
Discussion
No questions or reviews yet.
Related
SkillsOfficial Elastic skills for Elasticsearch, Kibana, Observability, Security and Elastic Cloud: ES|QL, indices, dashboards, alert triage
ReskillSQL analyses failed agent SQL runs and ships query-writing skill versions only after checks on held-out examples.
Probabl skills for machine learning experiments: a scikit-learn and skrub pipeline, evaluation, audit and a link to Skore Hub
One Aerospike skill teaches an agent to run the database in Docker, write client code on the official SDKs and design the schema
A template for data scientists: AGENTS.md, CLAUDE.md and skills for Python, SQL, Polars and model diagnostics.
31 skills for Claude Code and Codex for the analyst workflow: data checks, cohorts, funnels, A/B tests, dashboards, summaries
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| PlanetScale Skills (this card) | yes | 136 | |
| PlanetScale Database Skills | yes | 739 | reference skills by database technology, while this audits and changes PlanetScale itself, with a report and rollback |
| PlanetScale CLI | no | 672 | the pscale CLI itself, while this set teaches an agent to audit and change safely through it |
README in short
The README presents the set as a tool for assessment, reporting, execution and automation. It goes on with requirements (the pscale CLI with an auth check and an optional MCP server), three install routes, sample prompts, a safety model with classes A to E and a table of fifteen skills. It ends with a disclaimer about the consequences of autonomous runs.
README badge
Original SKILL.md
--- name: planetscale-safe-orchestrator description: Master skill that runs the full PlanetScale safe best-practices assessment — inventory, engine review, Insights, Traffic Control, webhooks, schema recommendations, codebase instrumentation, and agent operating model — then produces a unified recommendations report. Never applies changes without explicit approval. Use when the user asks to run the full assessment, all skills, or PlanetScale best-practices review. --- # PlanetScale safe orchestrator (master skill) ## Purpose Run the complete PlanetScale safe best-practices skill pack end to end. Load and execute each sub-skill in order, accumulate evidence, and produce one unified recommendations report. The first pass is assessment-only. ## Non-negotiable safety contract Default to read-only. You may inspect configuration, branches, query telemetry, recommendations, webhooks, roles, backups, traffic budgets, and repository code. You must not mutate PlanetScale, the database, the repository, the network posture, credentials, schema, production traffic controls, or automation endpoints without explicit approval of a named change set. Class C/D/E mutations require approval per `../planetscale-change-gates-and-approval-contract/SKILL.md`. When in doubt, stop and add to the proposed change set instead of executing. One exception exists: if the operator explicitly acknowledges the risk and names a scope per `../planetscale-autonomous-execution-mode/SKILL.md`, execution proceeds autonomously under that skill's status and halt discipline instead of stopping for per-change approval. The assessment phases below are identical either way. Sub-skills are sibling folders next to this skill, referenced by relative path; if a referenced path does not exist, locate the sibling skill whose frontmatter `name` matches and use it instead. Ground all CLI and API usage in the official documentation rather than guessing: the docs index is at https://planetscale.com/docs/llms.txt (append `.md` to any docs URL for the markdown version) and the API reference is https://planetscale.com/docs/openapi.yaml. When a command or endpoint fails, check the docs for the correct form before recording an evidence gap. Tooling and access failures belong in the internal run log, never in the customer report. ## Before you start 1. Read this file completely. 2. Copy the progress checklist below into your working notes and update it as you go. 3. Collect inputs (ask or infer from `AGENTS.md`, MCP context, environment, repository): - Organization slug - Database name - Branch name - Engine: PlanetScale Vitess or PlanetScale Postgres - Production branch or branches - Connected application repository path, if available - Application language, framework, ORM, query builder, connection pooling - Operator tolerance: report-only, PR-generation, branch-only migrations, or supervised production apply If inputs are missing, continue with discovery. Do not block on completeness. ## Progress checklist Copy and track: ``` Master assessment progress: - [ ] Phase 0: Safety contract loaded - [ ] Phase 1: Read-only inventory - [ ] Phase 2: Engine safety review (Vitess OR Postgres) - [ ] Phase 3: Query Insights and tags - [ ] Phase 4: Traffic Control (Postgres only — skip for Vitess) - [ ] Phase 5: Webhook automation - [ ] Phase 6: Schema recommendations agent loop