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.
A highly actionable, well-researched body: nearly every command and code sample is copy-paste ready, workflows include real validation checkpoints (config plan dry-run, fails-fast env pull, destructive-write warning), and the beta-region caveat is handled up front. The costs are length-appropriateness: an overview skill carrying ~120 lines of config-layer reference material inline, plus repeated statements of the env-pull-by-default behavior. Splitting the deep neon.ts/parseEnv material into a reference file would fix both the disclosure and conciseness issues at once.
Suggestions
Move the deep neon.ts / @neon/env material (parseEnv examples, branch-config function, type-error walkthrough) into a references file (e.g. references/neon-config.md) and keep a short summary with a one-level-deep pointer in SKILL.md.
State the "link and checkout pull env by default" behavior once (in the Branch-First Dev Flow intro) instead of three times across the checkout, code-comment, and config-apply sections.
Consolidate the two parseEnv code examples into one example showing key selection ("parseEnv(config, [\"DATABASE_URL\", \"NEON_AUTH_BASE_URL\"])") with a comment noting the narrowed return shape.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Almost every line carries product-specific, non-inferable detail (CLI flags, neon.ts semantics, gotchas) — no explaining of concepts Claude already knows — but the env-pull-by-default behavior is stated three separate times, the varlock example is a niche digression, and the parseEnv section uses two full code examples where one annotated example would do. Mostly efficient but noticeably loose in these spots, matching anchor 3 rather than 4. | 3 / 5 |
Actionability | Fully executable throughout: exact commands ("npx -y neon@latest init", "neon link --agent", "neon set-context --project-id <id> --org-id <id> --branch-id <id>", "neon config status/plan/apply", "neon neon-auth domain add <domain>"), complete copy-paste-ready TypeScript samples, the --agent JSON state machine with exact status values, and precise doc-fetch URLs. Common cases are covered end to end. | 5 / 5 |
Workflow Clarity | The getting-started flow is clearly sequenced (check status quo → init/link → per-service skills) with checkpoints: a resume-support step, "neon config plan" as a read-only dry-run, an env pull that "fails fast if the branch is missing a declared service, pointing you at neon deploy", and the set-context destructive write explicitly flagged. It falls short of 5 because there is no explicit post-apply verification step and no systematic validate→fix→retry loop or checklist for the setup flow. | 4 / 5 |
Progressive Disclosure | Headers are well organized and sibling skills plus the docs index are clearly signposted, but the skill has no reference files at all, and roughly 120 lines of neon.ts/parseEnv material (two parseEnv code examples, the branch-config function, the type-error walkthrough) are inlined in a file positioned as an overview/router. That is inline content which clearly belongs in a separate reference file — anchor 3, not the minor gaps of anchor 4. | 3 / 5 |
Total | 15 / 20 Passed |