query-readability

What it does and when to use it

Write SQL other people can review, modify, and trust, with clear structure, meaningful aliases, and stated assumptions. Use when a query will be read again by anyone, including you.

How it works

1. Method
2. Boundaries

---
name: query-readability
description: Write SQL other people can review, modify, and trust, with clear structure, meaningful aliases, and stated assumptions. Use when a query will be read again by anyone, including you.
---

# Query readability

SQL is read far more than written, and unreadable SQL is where wrong
results hide. Readability is not decoration here: the reason a bug
survives review is usually that nobody could hold the query in their
head long enough to see it.

## Method

1. **State the grain in a comment at the top.** One line saying what one
   row of the result represents orients every later reader and catches
   errors during review.
2. **Alias tables meaningfully.** Short is fine, cryptic is not:
   customers c reads well, t1 does not, and single letters collapse once
   a query joins six tables.
3. **Format for scanning.** One clause per line, joins with their ON
   conditions together, and consistent capitalisation. The point is that
   a reviewer can see the shape without parsing it.
4. **Name intermediate steps with CTEs.** A staged query reads
   top-down and each stage can be run alone, which is what makes review
   and debugging possible (see common-table-expressions).
5. **Comment the non-obvious filter, not the syntax.** Explain why a
   status is excluded or a date is shifted, since that is the knowledge
   that leaves with whoever wrote it.
6. **Prefer explicit over clever.** An extra join that reads plainly
   beats a nested correlated subquery that saves three lines, because
   the next change is made by someone in a hurry.

## Boundaries

- Readability serves review and maintenance; it does not substitute for
  verifying results against the source (see sql-joins).
- Formatting preferences differ, and consistency inside a codebase
  matters more than which style won.
- The clearest form is occasionally not the fastest, and a deliberate
  performance rewrite deserves a comment explaining why (see
  sql-optimization).

Versions

The database has no other skills named query-readability.

Database snapshot: 13.11.2026 · package version 26131a95b09b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

• 100sql-query-optimizer
  Optimize sql query optimizer operations. Auto-activating skill for Data Analytics. Triggers on: sql query optimizer, sql query optimizer Part of the Data Analytics skill category. Use when working with sql query optimizer functionality. Trigger with phrases like "sql query…
• 100sql-translator
  Translates a plain-English question into a single, safe, read-only SQL query against a known schema, with assumptions made explicit. Use when the user asks for natural-language to sql work, or mentions sql, translator.
• 100sql
  Write, run, and explain SQL queries, and do quick local analysis of CSV/SQLite data with the sqlite3 CLI. Use when users want a SQL query written or fixed, want to query a .db/.sqlite file, or want to analyze a CSV with SQL (joins, group by, window functions). Triggers on…
• 100ggsql
  Write ggsql queries — a grammar of graphics for SQL. Use when the user wants to create, modify, or understand a ggsql visualization query.
• 90sql-helper
  Write, fix, explain or speed up SQL queries and schema changes against the project's real database schema. Use when the user asks for "a query that...", "a report from the database", "why is this query slow", "add an index", "update/delete these rows", or pastes SQL that returns wrong numbers.
• 100optimizing-sql-queries
  Execute use when you need to work with query optimization. This skill provides query performance analysis with comprehensive guidance and automation. Trigger with phrases like "optimize queries", "analyze performance", or "improve query speed".