Content
80%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, highly actionable reference skill with excellent progressive disclosure (verified one-level-deep references with explicit 'When to Read' routing) and executable examples throughout. Its weaknesses are moderate: version-specific details live inline rather than in a compatibility section, and validation guidance is a single closing bullet instead of checkpoints in the destructive/batch SQL workflows.
Suggestions
Add inline validation checkpoints to the mutating patterns (e.g. after the upsert procedure and before the scheduled materialized view), such as 'query the row count or a sample before and after MERGE, and roll back / skip refresh if counts look wrong', turning the final test note into a per-pattern loop.
Move the DBR version matrix ('Since' column) into a dedicated compatibility section (or into the version table in references/sql-scripting.md) so time-sensitive version numbers don't sit inline in the main file.
Merge the Quick Reference and Reference Files tables (add a 'When to Read' column to the single feature table) to remove the duplicated reference routing.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean: 16 compact, comment-light code examples, a quick-reference table, and terse directive bullets with no explanation of concepts Claude already knows. Minor trimmable material keeps it below 5: the 'Since' column embeds time-sensitive version numbers ('DBR 16.3+', 'GA') outside any deprecated/old-patterns section, and the 'Reference Files' table duplicates the reference column of the Quick Reference table. It is noticeably above the anchor-3 midpoint (no unnecessary explanations, just minor redundancy), so 4. | 4 / 5 |
Actionability | Every pattern is a complete, copy-paste-ready SQL block covering the common case: a full procedure with EXIT HANDLER and CALL invocation, a scheduled materialized view, pipe-syntax rewrite, ai_query with returnType, an H3 join with ST_Distance filter, a CREATE CONNECTION plus http_request, read_files with schemaHints, and a concrete CLI test command ('databricks experimental aitools tools query') with an env-var fallback. This matches anchor 5; anchor 4 would imply minor gaps in the examples themselves, which are absent. | 5 / 5 |
Workflow Clarity | The body is a pattern catalog rather than a sequenced procedure, and the multi-step flows it does contain (e.g. create connection then call http_request, or MERGE-based upserts that mutate data) have no inline validation checkpoints — the only verification guidance is one final bullet ('Test SQL via CLI ... before deploying'), with no fix-and-retry loop. Per the rubric's cap for database operations without feedback loops, workflow clarity cannot exceed 3; a score of 4 would require checkpoints embedded at each risky step. | 3 / 5 |
Progressive Disclosure | The body is a clear overview: a feature-to-reference routing table, one worked example per feature kept inline, and a 'Reference Files' table with an explicit 'When to Read' column. All five referenced files exist and contain only internal anchor links, so references are exactly one level deep with no nesting — matching anchor 5's clear overview with well-signaled one-level-deep references. | 5 / 5 |
Total | 17 / 20 Passed |