Content
40%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.
The body is rich with executable SQL examples but reads as a generic SQL-optimization textbook: long on knowledge Claude already has, short on a sequenced diagnostic workflow with verification steps, and its progressive-disclosure layer is broken — all seven referenced bundle files are missing. Biggest wins are trimming known material into the (to-be-created) reference files and adding a validated optimize-and-recheck loop.
Suggestions
Trim or move content Claude already knows (index type definitions, avoid SELECT *, batch INSERT basics) — conciseness
Add a numbered optimization workflow (find slow queries via pg_stat_statements → EXPLAIN ANALYZE → apply one fix → re-run EXPLAIN to verify improvement) with explicit validation checkpoints — workflow_clarity
Fix the broken bundle: create the seven referenced files (references/, assets/, scripts/ all absent) and move the database-specific detail there, or remove the Resources section — progressive_disclosure
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At 509 lines the body extensively covers concepts Claude already knows — index type definitions ('B-Tree: Default, good for equality and range queries'), 'Avoid SELECT *', batch INSERT VALUES syntax, and basic EXPLAIN semantics — with several padded bad/good/better triplets for the same idea. Not 1 because the material is organized and mostly relevant rather than introductory filler; not 3 because large sections are pure restatement of standard database knowledge. | 2 / 5 |
Actionability | Concrete, mostly copy-paste-ready SQL throughout — 'EXPLAIN (ANALYZE, BUFFERS, VERBOSE)', 'CREATE INDEX idx_users_cursor ON users(created_at DESC, id DESC)', the pg_stat_statements monitoring queries. Not 5 because of minor gaps: the Python batch example uses 'WHERE user_id IN (?)' with a list (not executable as written) and 'WHERE id IN (1, 2, 3, 4, 5, ...)' contains a literal ellipsis. | 4 / 5 |
Workflow Clarity | The body is a topic catalog (concepts → patterns → advanced → pitfalls), not a sequenced optimization process; there is no 'identify via pg_stat_statements → EXPLAIN ANALYZE → apply fix → re-verify' loop, and validation is absent despite this being a database-operation skill, which caps the score at 3 and the missing sequence pulls it to 2. Not 1 because the section ordering does loosely imply an approach (monitoring queries appear, EXPLAIN is introduced first). | 2 / 5 |
Progressive Disclosure | The Resources section lists seven bundle paths ('references/postgres-optimization-guide.md', 'assets/index-strategy-checklist.md', 'scripts/analyze-slow-queries.sql', etc.), but none of these files exist in the bundle — every reference is dead. Combined with ~500 lines of reference-grade detail inlined in SKILL.md (material the missing files were meant to hold), navigation fails. Not 3 because the references are clearly signaled yet point to nothing, which is worse than unclear signaling; not 1 because the section structure itself is well organized. | 2 / 5 |
Total | 10 / 20 Passed |