Content
71%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured overview skill with excellent progressive disclosure, executable validation/formatting commands, and a built-in validate-and-recover loop appropriate for database operations. Its main weaknesses are marketing-fluff padding, a redundant intro, and hardcoded version numbers that will become stale over time.
Suggestions
Remove the marketing sentence ('SurrealQL is... modern, flexible, and powerful... easy to learn and use') and the redundant restatement of the description in the intro; Claude gains nothing from them.
Replace hardcoded version numbers ('v3.1.4', '3.x', 'since SurrealDB v3.1.0') with the version-detection commands themselves, or move version-specific notes into a dedicated version/compatibility section so they age gracefully.
Add one or two inline SurrealQL examples for the most common cases (e.g. a basic SELECT with WHERE and a CREATE) so users get immediate syntax grounding without opening a reference file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient (compact statement tables, lean command examples), but includes unnecessary padding: the marketing sentence 'a modern, flexible, and powerful query language that is designed to be easy to learn and use', a redundant restatement of the description, and time-sensitive version numbers ('v3.1.4', '3.x', 'since SurrealDB v3.1.0') that will age and are not in a deprecated/old-patterns section. | 3 / 5 |
Actionability | Provides fully executable, copy-paste-ready commands (`surreal validate query.surql`, `curl -s https://download.surrealdb.com`, `npx @surrealdb/surql-fmt --stdin`) with a worked example; the minor gap is that no actual SurrealQL query examples appear inline, being delegated entirely to the reference files. | 4 / 5 |
Workflow Clarity | The generate→validate→format flow is well supported: 'always validate them using the SurrealDB CLI' with an error-recovery feedback loop ('Validation may fail to due version differences, at which point you can retrieve your SurrealDB CLI version with `surreal version`'), and explicit always-format situations. It falls short of a 5 because the workflow is implied across sections rather than presented as an explicit sequenced process. | 4 / 5 |
Progressive Disclosure | Clear overview with a well-signaled References section ('For detailed querying patterns (filtering, graph traversal, aggregation, subqueries), see references/querying.md') pointing to three real, one-level-deep files (querying.md, schema.md, values.md — verified to exist with no nested references); statement tables serve as a navigable index, and content is appropriately split. | 5 / 5 |
Total | 16 / 20 Passed |