DATABASES / Cockroach Labs
CockroachDB SQL
Cockroach Labs skill that turns a natural-language request into CockroachDB SQL, applies the relevant rule files with 00-fundamental-principles.md first, and tells the agent to run EXPLAIN on every generated query when a cluster connection is available.
“Converts natural language questions into CockroachDB-compliant SQL queries, following CockroachDB best practices. Use it for schema design, writing queries and optimizing query.”
01 / THE REASONING
Why this made the selection.
- SKILL.md marks plan validation as mandatory: when connected, it tells the agent to run EXPLAIN on every generated query, fix and re-run it after a parsing or syntax error, and include the EXPLAIN output in the response.
- It applies the relevant rule files under references/cockroachdb-rules/ for each operation, 00-fundamental-principles.md first; that file requires a PRIMARY KEY in every table, prefers UUID primary keys and says to avoid sequential IDs that cause hotspots.
- Cockroach Labs maintains the repository, per the README footer, and LICENSE carries the line Copyright 2026 Cockroach Labs Inc.
02 / THE REVIEW RECORD
What we actually inspected.
Source review has boundaries.
A clear record is more useful than a “safe” badge.
Material inspected
- skills/cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
- README.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
- docs/installation.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
- skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
- skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd: section headings and the statements quoted in limitations
- skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md, 03-query-patterns.md and 04-optimization.md at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd: the statements quoted in limitations
- LICENSE at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd
- Repository tree at e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd: 34 SKILL.md files
Our findings
- Connection detection checks a postgresql:// string in the prompt, then the COCKROACH_URL environment variable, then a cockroach-cloud MCP server; if none is available or the cluster is unclear, the agent is told to ask the user before running anything.
- Queries run through `cockroach sql --url … -e "SQL"`, and SKILL.md says not to use psql.
- Nothing in SKILL.md limits execution to read-only statements: its frontmatter asks for SELECT, INSERT, UPDATE, DELETE or admin privilege when connected, and the optimizing step says to execute each step and report the outcome.
- docs/installation.md shows --skill only with reviewing-cluster-health and with '*'; no printed line names cockroachdb-sql.
Not established by this review
- Not executed: it was not installed or run.
- No SQL was generated, no EXPLAIN plan was produced and no cluster was connected.
- references/EXAMPLES.md was not read, and rule files 01 to 04 were read only at the statements quoted in limitations.
The review applies to the material and revision named here. A newer upstream release can change its behavior.
03 / PUT IT TO WORK
Add a skill to your workflow.
- README.md prints `npx skills add cockroachlabs/cockroachdb-skills` as its one-line installation. At this revision that line offers all 34 SKILL.md skills in the repository, not this skill alone.
- docs/installation.md says the interactive installer lets you select which skills to install; its non-interactive examples use `--skill '*'` and `--skill reviewing-cluster-health`. No printed line selects cockroachdb-sql.
- The manual options in docs/installation.md clone the repository and symlink or copy the whole skills/ directory into .claude/skills.
Before you start
- Node.js 18+ for the npx installer, as docs/installation.md states
- A connection for EXPLAIN validation: the cockroach CLI with a connection URL in the prompt or COCKROACH_URL, or a cockroach-cloud MCP server
04 / FOLLOW THE EVIDENCE
The source trail.
Our notes are separate from the original resource.
Check upstream before adopting a new version.
https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/SKILL.md
Supports: upstreamDescription, whySelected, bestFor, limitations, access, install.prerequisites, review.findings
https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/README.md
Supports: install, compatibility, homepage, whySelected, limitations
https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/docs/installation.md
Supports: install, compatibility, limitations, review.findings
https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/00-fundamental-principles.md
Supports: whySelected
https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/05-operational.md
Supports: limitations
https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/LICENSE
Supports: license, limitations, whySelected
https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/01-schema-design.md
Supports: limitations
https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/03-query-patterns.md
Supports: limitations
https://github.com/cockroachlabs/cockroachdb-skills/blob/e14e86d23ce8ee2e7e40a34ce2944c2502b6eadd/skills/cockroachdb-query-and-schema-design/cockroachdb-sql/references/cockroachdb-rules/04-optimization.md
Supports: limitations