{
  "markdown": "# PlanetScale Skills\n\nA skill pack that turns your coding agent into a PlanetScale database\nreviewer and operator. Point it at an organization and it audits\nconfiguration, query behavior, open recommendations, and safety posture —\nthen, with your approval, does the work: reviewable schema changes,\ninstrumentation PRs, webhooks, and scheduled automation.\n\nWorks with any agent that reads `SKILL.md` files — Cursor, Claude Code,\nand anything following the open agent-skills convention. The skills are\nplain markdown instructions; all output is markdown and text. Nothing is\nagent-specific: no plugins, no custom tools, no proprietary rendering.\n\n## What it does\n\n- **Assess** — a read-only, evidence-backed review of one database or a\n  whole organization: branch and safety workflow, backups and restore\n  posture, credentials, Query Insights, anomalies, SQL comment / query tag\n  coverage, open schema recommendations, webhooks, and Traffic Control.\n- **Report** — a single markdown report where every claim carries the\n  command that produced it and every recommendation carries a measured\n  finding, a gate, and a rollback path.\n- **Execute** — on your approval, changes ship through PlanetScale's own\n  safety mechanisms: development branches, pull requests, deploy requests\n  with revert windows, warn-before-enforce Traffic Control budgets.\n- **Automate** — scheduled agent loops that sweep recommendations into\n  ready-to-ship PRs, watch for query regressions, and detect posture\n  drift.\n\n## Setup\n\n### Prerequisites\n\n1. **PlanetScale CLI**, authenticated for automation:\n\n   ```sh\n   brew install planetscale/tap/pscale   # or see planetscale.com/cli\n   pscale agent-guide --format json      # CLI conventions (or load skill planetscale-pscale-cli-automation)\n   pscale auth check --format json       # verify auth; follow next_steps if action_required\n   pscale org list --format json         # verify access\n   ```\n\n   Agents should always pass `--format json` on `pscale` commands. Use `pscale sql`\n   for non-interactive queries, not `pscale shell`. See skill `planetscale-pscale-cli-automation`\n   or the CLI repo `AGENTS.md` for full conventions.\n\n2. **Optional: PlanetScale MCP server.** The skills prefer the\n   insights-only MCP server for telemetry analysis when it is available,\n   and fall back to `pscale` / `pscale api` otherwise. Nothing requires\n   MCP.\n\n3. **Recommended: run from your application repository.** The skills\n   work anywhere, but they are significantly better when the agent runs\n   inside the repo that contains the code talking to the database. See\n   [Run it from the repo that uses the database](#run-it-from-the-repo-that-uses-the-database).\n\n### Install the skills\n\nThe skills work with any agent that reads `SKILL.md` files. Pick the\nroute that fits:\n\n**Setup script (recommended).** Detects installed agents and installs to\neach of them:\n\n```sh\ngit clone https://github.com/planetscale/skills.git\ncd skills && script/setup\n```\n\nThe script installs to every agent it finds (`~/.cursor/skills/`,\n`~/.claude/skills/`, `~/.agents/skills/`). For any other agent, pass its\nskills directory explicitly:\n\n```sh\nscript/setup ~/.codex/skills          # or wherever your agent reads skills\n```\n\n**Skills CLI.** If you use the `npx skills` package manager:\n\n```sh\nnpx skills add planetscale/skills -g -y\n```\n\n**Manual.** Copy the `planetscale-*` directories into your agent's skills\nlocation:\n\n| Agent | User-level | Project-level |\n|---|---|---|\n| Cursor | `~/.cursor/skills/` | `<repo>/.cursor/skills/` |\n| Claude Code | `~/.claude/skills/` | `<repo>/.claude/skills/` |\n| Open agent-skills convention | `~/.agents/skills/` | `<repo>/.agents/skills/` |\n| Anything else | the directory your agent documents for `SKILL.md` files | |\n\nOne constraint in all cases: the directories must stay siblings — skills\nreference each other by relative path\n(`../planetscale-change-gates-and-approval-contract/SKILL.md`). Each folder is\nnamed after its frontmatter `name`, as the agent-skills specification\nrequires, so installers that rename folders by frontmatter name (including\nthe Skills CLI) leave those paths intact.\n\n## Usage\n\n### Run it from the repo that uses the database\n\nYou can run these skills from anywhere, but they are at their best when\nthe agent runs inside the repository that contains the code talking to\nthe database. With the codebase in view, the agent can:\n\n- map expensive query patterns in Insights back to the routes, jobs, and\n  ORM calls that produce them\n- add SQLCommenter query tags to your framework so future load is\n  attributed automatically\n- fix the code behind findings (N+1s, missing pagination, unindexed\n  lookups) instead of only reporting them\n- turn schema recommendations into migrations in your framework's own\n  migration system, ready for review as a normal PR\n\nWithout the repository, the assessment still covers everything on the\ndatabase side; it just stops at recommendations where the fix lives in\ncode. If your agent supports project-level skills, installing the pack\ninto the application repo (for example `<repo>/.cursor/skills/`) gets\nyou this by default.\n\n### Run an assessment\n\nAsk in plain language. The orchestrator skill picks up the request and\nruns every phase. For the full treatment, start with a prompt that puts\neverything in scope:\n\n> Run the full PlanetScale best-practices assessment on my-org/my-db.\n> Review the whole setup against best practices: branch topology and\n> schema-change workflow, safe migrations and deploy requests, backups\n> and restore posture, roles and credentials, connection pooling and\n> network configuration, Query Insights behavior, anomalies, SQL comment\n> / query tag coverage, open schema recommendations, webhooks, and\n> Traffic Control. My application repository is in this workspace:\n> include query attribution and instrumentation recommendations for it,\n> and map findings to the code that produces them.\n> Produce the complete evidence-backed report with IDs for every\n> recommendation. Read-only: propose everything, change nothing.\n\nEverything in that prompt beyond the first sentence is optional — the\norchestrator covers all phases by default. Scope it down whenever you\nwant less:\n\n> Check the larger databases in my-org.\n> Audit our query tag coverage and open recommendations.\n\nThe first pass is always read-only. You get the report; nothing changes.\n\n### Approve changes\n\nEvery recommendation in the report has an ID. Approve the ones you want:\n\n> Approve VIT-1 and WEB-1.\n\nThe agent shows the exact commands, expected effect, and rollback plan\nfor each approved ID, executes them one at a time, verifies each by\nreading state back, and reports.\n\nWork that lives inside a review workflow — development branches, pull\nrequests, deploy requests — does not need approval to *prepare*. The\nagent's default deliverable for a schema recommendation is the complete\nreviewable unit: a branch with the DDL applied, a PR with the evidence,\nand an open deploy request. Your action is the merge/deploy decision.\n\n### Full autonomy (opt-in)\n\nIf you want the agent to execute the whole plan without per-change\napproval, say so explicitly. Three elements are required — an\nunambiguous risk acknowledgment, a named scope, and whether production\nis included:\n\n> I accept the risk — apply all report recommendations to my-db,\n> production included.\n\nThe agent then plans in dependency order, executes one atomic change at\na time, verifies each step, streams status the entire way, and halts on\nfailure with staged rollbacks. \"Go ahead\" and \"fix everything\" do not\nactivate this mode; the acknowledgment must be explicit, and it covers\none run and one scope only.\n\n### Scheduled automation\n\nFor unattended runs (cron, CI, agent schedulers), interactive\nacknowledgment is replaced by a **standing authorization**: a committed\nfile naming the owner, scope, allowed operations, numeric bounds, expiry\ndate, and a status delivery channel. Details and templates are in\n`planetscale-autonomous-execution-mode/SKILL.md`. Recommended loops (see\n`planetscale-mcp-agent-operating-model/SKILL.md`):\n\n- **Recommendation-to-PR** (daily) — open schema recommendations become\n  ready-to-ship branch + PR + deploy request units. No authorization\n  needed; it only produces proposals.\n- **Recommendation deployer** (daily) — deploys approved deploy requests\n  within authorized bounds. Requires a standing authorization.\n- **Regression watch** (hourly or per-deploy) — diffs query patterns\n  against a baseline and reports regressions with the responsible deploy.\n- **Posture drift check** (daily) — reports changes to safety flags,\n  webhooks, roles, and backup posture since the last assessment.\n\n## Safety model\n\nEvery operation the agent might take is classified before it happens\n(`planetscale-change-gates-and-approval-contract/SKILL.md`):\n\n| Class | Scope | Default |\n|---|---|---|\n| A | Read-only: list, inspect, report | Runs freely |\n| B | Proposals: dev branches, PRs, deploy requests, restore tests | Runs freely — the review workflow is the gate |\n| C | Behavior-changing: safety flags, webhooks, roles, budgets | Approval or authorization required |\n| D | Production data/availability: deploys, DDL, deletions, credentials | Approval + named target + rollback plan |\n| E | Destructive without recourse: drop production data, disable all safety, expose secrets | Never executed autonomously, under any phrasing |\n\nTwo properties hold in every mode, including full autonomy: a change is\nverified by reading state back (not by command exit codes), and every\nrun produces an audit log. Reports end with the same contract line:\n\n> No changes have been applied. Approve specific change IDs before any\n> mutation.\n\n## The skills\n\n| Skill | Role |\n|---|---|\n| planetscale-safe-orchestrator | Runs the full assessment end to end; the usual entry point |\n| planetscale-readonly-inventory | Evidence collection: org, branches, backups, webhooks, roles |\n| planetscale-vitess-safety-review | Vitess: safe migrations, deploy requests, revert, sharding |\n| planetscale-postgres-safety-review | Postgres: roles, pg_strict, Traffic Control, PITR, pooling |\n| planetscale-query-insights-and-tags | Query behavior, anomaly review, tag coverage and cardinality |\n| planetscale-traffic-control-recommendations | Warn-first budget plans for Postgres traffic slices |\n| planetscale-webhook-automation-recommendations | Event routing, receiver requirements, automation flows |\n| planetscale-schema-recommendations-agent-loop | Recommendation triage into reviewable units |\n| planetscale-codebase-sqlcommenter-instrumentation | Repository review and query-tagging PR plans |\n| planetscale-mcp-agent-operating-model | Agent/MCP configuration and scheduled loop catalog |\n| planetscale-customer-report-template | Report format, tone, and evidence requirements |\n| planetscale-change-gates-and-approval-contract | The Class A–E permission model |\n| planetscale-best-practices-matrix | Per-engine coverage checklist so assessments miss nothing |\n| planetscale-autonomous-execution-mode | Risk-acknowledged autonomy: contract, status protocol, halt rules |\n| planetscale-pscale-cli-automation | Driving `pscale` headless: `--format json`, auth check, `pscale sql` |\n\nEach skill is a standalone `SKILL.md` — readable as documentation,\nexecutable by the agent. Start with `planetscale-safe-orchestrator/SKILL.md` to\nsee how a full run fits together.\n\n## Disclaimer\n\nThese skills direct AI agents that read from and — with your approval —\nmake changes to databases and infrastructure. Agent behavior is not\ndeterministic, and no safety model eliminates risk. You are responsible\nfor reviewing changes before they are applied, for maintaining backups,\nand for the consequences of enabling autonomous execution or scheduled\nautomation.\n\nThis software is provided \"as is\", without warranty of any kind.\nPlanetScale, Inc. accepts no liability for any damages, data loss,\ndowntime, or costs arising from its use, as set out in the\n[LICENSE](LICENSE). These skills are not part of the PlanetScale\nservice and are not covered by any service agreement or SLA.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 12183,
  "sha": "ca010d2934165a8a9d8f744c5b74ecb1427745e0dca63646d5074b6a9088f84b",
  "repo_slug": "planetscale/skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_planetscale_skills_planetscale_mcp_agent_dd05517b/readme"
}