sql-insight

Translate natural language to SQL, optimize query performance, and interpret EXPLAIN plans for SQLite and PostgreSQL. Triggered when users ask to convert questions into SQL, improve slow queries, tune indexes, analyze execution plans, or mention keywords like NL2SQL, query tuning, or full table scan.

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./skills/sql-insight/SKILL.md

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A highly actionable, well-structured skill body with executable commands and concrete examples throughout. The main gap is that the lengthy optimization-rules and EXPLAIN-interpretation tables could be moved to a reference file, and validation feedback loops are implicit rather than explicit.

Suggestions

Make the workflow's validation explicit: after `optimize`, add a 'fix flagged issues, then re-run optimize' loop before proceeding to `explain`.

Move the 13-row Optimization Rules and EXPLAIN Interpretation Items tables into a separate reference file (e.g. references/optimization_rules.md) and link to it from SKILL.md to reduce token load.

Trim the Detailed Usage global-parameter table, since the same information is already implied by the Quick Start command examples.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with well-organized tables and copy-paste commands; minor instances that could be trimmed (e.g., the 'Detailed Usage' global-parameter table repeats info already implied by the Quick Start examples).	4 / 5
Actionability	Fully executable copy-paste commands covering schema/optimize/explain across SQLite and PostgreSQL, plus concrete output examples; common cases are specifically covered.	5 / 5
Workflow Clarity	The NL→SQL workflow is a clear 4-step sequence with the optimize/explain commands acting as implicit validation checkpoints; however, validation feedback loops (e.g., iterate on optimize issues before running explain) are not explicitly framed as validate→fix→retry.	4 / 5
Progressive Disclosure	Well-structured overview with clearly organized sections (Capabilities, Workflow, Quick Start, Detailed Usage, Rules, Output Examples); the single bundle script (scripts/sql_query_helper.py) is referenced consistently and exists, but no separate reference files are used to offload the lengthy rules/output tables, leaving minor organization gaps.	4 / 5
	Total	17 / 20 Passed

Description

78%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that names concrete capabilities and provides explicit trigger guidance with natural keywords. Minor room to tighten the 'when' clause into a cleaner 'Use when...' form and add a few synonyms.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('Translate natural language to SQL, optimize query performance, and interpret EXPLAIN plans'), naming both the domain and specific tasks with only minor coverage gaps (no explicit mention of schema extraction/index tuning outcomes).	4 / 5
Completeness	Clearly answers 'what' (translate/optimize/interpret) and 'when' via an explicit 'Triggered when users ask...' clause with concrete triggers; the 'when' clause is explicit but slightly list-like rather than a clean 'Use when...' formulation.	4 / 5
Trigger Term Quality	Includes natural trigger phrases users would say ('convert questions into SQL', 'improve slow queries', 'tune indexes', 'analyze execution plans') plus keywords (NL2SQL, query tuning, full table scan); a few natural synonyms like 'SQL generator' are missing.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (NL→SQL + EXPLAIN interpretation for SQLite/PostgreSQL) with distinct triggers (NL2SQL, EXPLAIN plans, full table scan), making conflict with unrelated skills minimal.	5 / 5
	Total	17 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: zebbern/claude-code-guide
Path: skills/sql-insight/SKILL.md
Commit: 9d252b3

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.