Content
55%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 executable reference of SQL optimization commands, undermined by verbosity and the absence of a stated workflow. Most of the inline content re-teaches knowledge Claude already has, while the genuinely valuable material (pg_stat monitoring queries, PG index syntax variants) is diluted among padded sections, and no find→diagnose→fix→verify sequence with validation checkpoints is ever given.
Suggestions
Add an explicit optimization workflow with a validation loop, e.g.: 1. Find slow queries via pg_stat_statements, 2. Run EXPLAIN ANALYZE on each, 3. Apply the matching pattern or index, 4. Re-run EXPLAIN ANALYZE to verify improvement before moving on.
Cut sections that restate knowledge Claude already has (the EXPLAIN metrics glossary, index-type primer, "Avoid SELECT *", and the implicit-vs-explicit JOIN example) and keep the body focused on non-obvious content like the pg_stat catalog queries and partial/expression/covering index syntax.
Fix or remove the misleading JOIN example — the planner treats the implicit "FROM users u, orders o WHERE u.id = o.user_id" join identically to an explicit JOIN, so labeling it "Cartesian product then filter" is incorrect; likewise flag that the subquery-pre-filter "Better" form is usually unnecessary on modern planners.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Several sections restate standard SQL knowledge Claude already has — a glossary explaining "Seq Scan: Full table scan (usually slow for large tables)" and "Index Only Scan: Using index without touching table (best)", filler like "Indexes are the most powerful optimization tool", and a basic "Avoid SELECT *" example. Only the pg_stat catalog queries and PG-specific index syntax variants (partial, expression, covering) add non-obvious value, so the padding spans multiple sections rather than being occasional. | 2 / 5 |
Actionability | The guidance is fully executable copy-paste SQL covering the common cases: "EXPLAIN (ANALYZE, BUFFERS, VERBOSE) SELECT ...", "CREATE INDEX idx_active_users ON users(email) WHERE status = 'active'", and monitoring queries like "SELECT query, calls, total_time, mean_time FROM pg_stat_statements ORDER BY mean_time DESC LIMIT 10". Examples are complete and runnable with no gaps. | 5 / 5 |
Workflow Clarity | The skill hints at a process ("Understanding EXPLAIN output is fundamental to optimization") and ends with discovery queries, but never sequences an actual workflow (find slow query → EXPLAIN ANALYZE → apply pattern → re-verify) and includes no validation checkpoints such as re-running EXPLAIN ANALYZE after adding an index. Database operations without feedback loops cap this at 3 per the rubric, but the actual level is lower: a rough topical sequence exists while steps are poorly defined and validation is absent. | 2 / 5 |
Progressive Disclosure | The body clearly signals a real, one-level-deep reference — "Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient" — and details.md exists with substantial content and no nested references. Minor gaps keep it from a 5: the ~215-line body inlines a heavy catalog (seven index variants, three monitoring queries, best-practices and pitfalls lists) that could be split further, and the single pointer doesn't break the reference into navigable topics. | 4 / 5 |
Total | 13 / 20 Passed |