DATABASES / SurrealDB
SurrealQL
SurrealDB skill for writing, adapting and troubleshooting SurrealQL statements, with statement tables linked to the docs and instructions to validate and format queries with the SurrealDB CLI and surql-fmt.
“Generate and modify SurrealQL queries to interact with SurrealDB databases. This includes creating and retrieving records, designing and managing schemas, establishing and querying graph relationships, performing live (real-time) queries, and leveraging all unique SurrealQL features for advanced database workflows. Use this skill whenever users need to write, adapt, or troubleshoot SurrealQL statements.”
01 / THE REASONING
Why this made the selection.
- Tables map SurrealQL query, schema and control-flow statements, from SELECT and LIVE SELECT to DEFINE TABLE, DEFINE INDEX and BEGIN / COMMIT, to their surrealdb.com docs pages, with references for querying, schema and values.
- It targets current SurrealDB 3.x syntax unless the user explicitly asks for an older version, and tells the agent to check the active version with `surreal version`, or otherwise to read the latest released version, published as a plain string at https://download.surrealdb.com.
- README.md prints a single-skill install line for it, `npx skills add surrealdb/agent-skills --skill surrealql`.
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/surrealql/SKILL.md at b139bf713490830384cb59f3ef1696e98e32223f
- README.md at b139bf713490830384cb59f3ef1696e98e32223f
- LICENSE at b139bf713490830384cb59f3ef1696e98e32223f
- skills/surrealql/references/querying.md, schema.md and values.md at b139bf713490830384cb59f3ef1696e98e32223f: scanned for commands and URLs; they hold SurrealQL examples and docs links
- Repository tree at b139bf713490830384cb59f3ef1696e98e32223f: 10 SKILL.md files
Our findings
- SKILL.md addresses commands to the agent: run `surreal version` if the CLI is installed (line 32), otherwise `curl -s https://download.surrealdb.com` (line 37).
- It says the agent should always validate generated or modified queries with the SurrealDB CLI if available (line 124), using `surreal validate` on a file, a glob or stdin.
- If a NodeJS-like runtime is available, it says the agent should always format queries presented to users, migration files and .surql files with `npx @surrealdb/surql-fmt`, which names no package version (lines 141-160).
- SKILL.md names no database connection, credentials or environment variables; the skill has no scripts.
Not established by this review
- Not executed: it was not installed or run.
- No query was generated, validated or formatted, and no SurrealDB instance or npm package was contacted.
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.
DOCUMENTED COMMAND
npx skills add surrealdb/agent-skills --skill surrealql Run in your terminal to choose your AI tools, project or global scope, and installation method. This short command follows the current upstream version; the review covers the revision shown above.
- Run the README line `npx skills add surrealdb/agent-skills --skill surrealql` to add this skill; `npx skills add surrealdb/agent-skills` without --skill adds all 10 skills in the repository.
- For a local install, README.md says to clone the repository and copy the skills/ directory to where the coding agent reads its skills; that copies all 10 skills, not this one alone.
Before you start
- A NodeJS-like runtime for npx; SKILL.md formats with surql-fmt only if one is available
- The SurrealDB CLI (surreal) for version checks and validation, if available
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/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/skills/surrealql/SKILL.md
Supports: upstreamDescription, whySelected, bestFor, limitations, access, install.prerequisites, review.findings
https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/README.md
Supports: install, compatibility, homepage, whySelected
- MIT LICENSE at b139bf71 ↗Checked
https://github.com/surrealdb/agent-skills/blob/b139bf713490830384cb59f3ef1696e98e32223f/LICENSE
Supports: license, limitations