Content
86%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 index-style skill: executable commands and complete code examples for the common setup and connection cases, a numbered setup flow with resume support, and clean one-level-deep disclosure to the official docs plus a verified local reference file. The main improvement opportunities are tightening a few verbose spots and adding an explicit connection-verification step to the setup workflow.
Suggestions
Trim the repeated choose-connection.md URL (appears three times: in Setup Flow step 3, the Connection Methods section, and the Neon Auth section) to a single canonical mention, and condense the marketing-style opening paragraph — both would lift the conciseness dimension from 4 to 5.
Add an explicit verification checkpoint at the end of the Setup Flow (e.g., run a trivial test query against DATABASE_URL or confirm the connection string resolves) so the workflow closes the loop the way the Resume Support section opens it.
Consider compressing the ~50-line neon.ts section by removing line-by-line code comments and keeping only the config skeleton, or moving the full annotated example into a reference file in the same style as references/neon-sdk.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is largely lean — a disciplined repeating pattern of "Use this for ... / Key points / Link:" with complete code blocks and no tutorials on concepts Claude already knows. Minor trims are possible: the marketing-style intro ("Neon is a serverless Postgres platform that separates compute and storage..."), the ~50-line neon.ts section with heavily commented config, and the choose-connection.md URL repeated three times. That places it at anchor 4 ('efficient; minor instances of over-explanation that could be trimmed') — above anchor 3's noticeable padding, below anchor 5 where every token earns its place. | 4 / 5 |
Actionability | Guidance is fully executable: concrete commands ("npx -y neon@latest init --agent <agent-name>", "npx skills add neondatabase/agent-skills --skill neon-postgres-branches", "neon config plan/apply"), copy-paste-ready TypeScript for both runtime patterns (module-scope pg Pool with attachDatabasePool for Vercel Fluid, neon-http serverless driver for Netlify), doc-fetching techniques (append .md / Accept: text/markdown), and a docs index for URL discovery. Placeholders like <agent-name> are justified with an explicit list of supported values. This matches anchor 5 ('fully executable; copy-paste ready; specific examples cover the common cases'). | 5 / 5 |
Workflow Clarity | The Getting Started section has a clear numbered 6-step Setup Flow with a pre-flight "Check Status Quo" inspection, resume logic ("check what's already configured ... and continue from the next incomplete step"), and a safety checkpoint ("Read the file first before modifying to avoid overwriting existing values" for .env). No destructive/batch cap applies. It falls just short of anchor 5 because there is no explicit post-setup verification (e.g., testing the connection with a query) — a minor checkpoint gap that lands it at anchor 4 rather than 5. | 4 / 5 |
Progressive Disclosure | The body is exactly an overview-plus-navigation document: every topic section is a short "Use this for ..." pointer with a one-level-deep link to the authoritative Neon doc page, plus a docs index (llms.txt) for undiscovered pages and "Don't guess URLs" guidance. The single bundle file references/neon-sdk.md exists on disk and matches its in-body citation, and the sibling neon-postgres-branches skill is signaled with both a fetch URL and an install command. This matches anchor 5 ('clear overview with well-signaled one-level-deep references; easy navigation'); there is no inlined bulk content that belongs in a separate file and no nested references. | 5 / 5 |
Total | 18 / 20 Passed |