Content
75%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 dense, highly actionable overview with strong sequencing, real validation checkpoints, and a genuine reference bundle used appropriately. Its main cost is length driven by repetition — the Data API, env-pull, and region guidance each appear multiple times — plus an inline neon.ts deep dive that should live in a reference file.
Suggestions
Consolidate the Data API guidance (currently stated at least four times across Backend Primitives, Architecture, the needs table, Choosing the Right Skill, neon init, Claimable, and the IaC sections) into one canonical placement, likely the Backend Primitives bullet plus one pointer.
Move the neon.ts / type-safe-config deep dive (defineConfig examples, branch() policy, Data API type errors) into a reference file (e.g. references/neon-ts.md), keeping only the plan/apply/delay reconciliation loop and a pointer inline; also make body reference links point at the local bundle files rather than neon.com URLs so the skill works offline.
Deduplicate the repeated env-pull-by-default note (stated in Useful CLI Commands, Branch-First Dev Flow, and the checkout composition paragraph) and the verbatim-duplicated supported-region list (Region availability and Observability) into one canonical mention with a pointer.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is product-specific (no padding about concepts Claude already knows), but guidance is noticeably repeated: the Data API caution appears at least four times ("Use it only when the app already uses PostgREST...", "Do not recommend this for new apps", "There is no neon-data-api skill", "Use data-api only for PostgREST / Supabase database-client compatibility"), the "link and checkout run this for you by default" env-pull note repeats three times, and the supported-region list is duplicated verbatim. Mostly efficient but could be tightened — anchor 3, not 2 since nothing explains generic known concepts. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready guidance throughout: exact CLI commands with flags ("neon init --agent cursor --org-id <org-id> --project-id <project-id> -y", "neon mcp --oauth --project --agent <agent> -y"), complete defineConfig TypeScript examples, install commands, and concrete flag semantics ("-y skips prompts but does not supply project selection or credentials"). Specific examples cover the common setup, deploy, branch, and logging cases. | 5 / 5 |
Workflow Clarity | Setup and convert-app flows are clearly sequenced with most checkpoints present: "Verify the app flow (sign-in, upload, API call), not only that env vars landed", the "neon config plan" dry-run before apply, env-pull failing fast and pointing at "neon deploy --env <file>", and auth failures routed to "stop and ask the user to sign in". Not 5 because the combined-init and manual-steps paths interleave without a single top-level sequence, and a few checkpoints are implicit (no explicit post-deploy verification step). | 4 / 5 |
Progressive Disclosure | Six real one-level-deep reference files exist in the bundle and are clearly signaled in the body ("[references/logs-loki.md]", "[references/claimable-neon.md]"), with deep material (Claimable flow, trigger parsers, LogQL, SDK, parseEnv) correctly pushed out of the overview. Not 5 because the ~130-line neon.ts / type-safe-config section is detailed inline material that belongs in a reference (it points only to a docs URL, no bundle file), and body reference links point to web URLs rather than the local bundle files. | 4 / 5 |
Total | 16 / 20 Passed |