Content
71%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 highly actionable — exact commands, flags, env vars, and a strong verification culture around targeting the right database — with clear safety workflows. It loses points on conciseness and progressive disclosure: changelog-style incident narratives, repeated permission warnings, and env-loading internals are inlined in a long single file instead of being tightened or split into a reference.
Suggestions
Move the incident history and correction notes (the 2026-08-16 wrong-database story and the DDL correction changelog) into a references/ file or a clearly marked history section, keeping SKILL.md focused on current behavior.
State the --writable permission requirement once (in Safety Features) and cross-reference it from the --writable and dev sections instead of repeating the full warning three times.
Add a verification checkpoint to the tunnel-dependent workflows, e.g. confirming the local forwarded port is listening before running the first --dev or --notifications query.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient project-specific content, but padded in places: date-stamped incident narratives ("That cost an hour and produced a confidently wrong root cause on 2026-08-16", "verified 2026-08-17") are embedded in prose rather than a history/deprecated section, and the --writable permission warning ("you MUST ask the user for permission") is repeated across Safety Features, the --writable section, and the dev section. Not a 2 because nothing explains concepts Claude already knows — nearly every sentence is operational knowledge specific to this repo. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready commands covering the common cases: "node .claude/skills/postgres-query/query.mjs --prod --explain \"SELECT * FROM \"Model\" WHERE id = 1\"", plus --timeout, -f, --json, --notifications variants, the exact env var names (DEV_DATABASE_URL, NOTIFICATION_DB_REPLICA_URL) and where to set them. Matches the anchor-5 example of specific commands covering common cases. | 5 / 5 |
Workflow Clarity | Clear per-target sequencing with explicit verification — "Read that line before you trust a result", the numbered Safety Features checklist, and error-recovery guidance ("A checkout with no skill .env exits 1 and names the file it would have read") — so the destructive-operation cap at 3 does not apply. Not a 5: the tunnel-dependent --dev/--notifications workflows lack a checkpoint confirming the tunnel is live before the first query, and the performance-comparison workflow ends at running both queries without a step for interpreting the timing difference. | 4 / 5 |
Progressive Disclosure | A single ~230-line file with good headers, but deep detail is inlined that belongs in a reference file — the .env precedence mechanics ("loadEnv only fills in keys that are not already present (an empty value counts as present...)"), the wrong-database incident history, and the DDL correction changelog ("This section previously said the opposite..."). This matches anchor 3 ('content that should be separate is inline'); not a 2 because the document is well-sectioned and navigable rather than an unstructured dump. No references/ files exist in the bundle to verify; the only referenced path is the invoked query.mjs script. | 3 / 5 |
Total | 15 / 20 Passed |