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 — nearly every section ends in runnable code, exact commands, or precise configuration values, and verification/debugging guidance is unusually good. Its weaknesses are token efficiency (duplicated region lists, triple-repeated env-var caveats, marketing prose) and structure: it is a single monolithic file carrying reference-grade detail that belongs in separate one-level-deep reference files.
Suggestions
Deduplicate repeated material: state the region list and the 'Neon injects only NEON_AI_GATEWAY_* (not OPENAI_*)' caveat once, and let Setup/List Models sections link back instead of restating credential provisioning.
Move reference-grade detail — the /v1/models JSON response shape, the plan/catalog gating matrix, and the per-SDK dialect routing notes — into a references/ file (e.g. references/models-api.md, references/plan-gating.md), keeping SKILL.md as a lean overview with one-level-deep pointers.
Trim promotional prose ('trillions of tokens a month', 'batteries-included', 'No extra infrastructure...') in favor of the factual deltas that distinguish the gateway from direct provider SDKs.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient and factual, but with recurring waste: the region list appears twice (lines 30 and 58), the caveat that Neon injects only NEON_AI_GATEWAY_* and not OPENAI_* is stated three times (the env-var table, the AI SDK note, and the plain-SDKs section), credential-provisioning instructions are repeated in Setup and again under List Available Models, and promotional prose ("runs on the same Databricks infrastructure that serves trillions of tokens a month", "batteries-included") adds no actionable value. This fits the anchor for mostly efficient content that includes unnecessary explanation and could be tightened, more than the 'minor instances' of the level-4 anchor. | 3 / 5 |
Actionability | Fully executable, copy-paste-ready guidance throughout: the neon.ts config with `neon deploy`, the `neon config status/plan/apply` commands, complete TypeScript examples for @neon/ai-sdk-provider, Mastra, and plain OpenAI SDK, an exact env-var table, the curl for GET /v1/models, and precise dialect paths (${NEON_AI_GATEWAY_BASE_URL}/v1, /openai/v1, /anthropic, /gemini). Common cases (chat completion, streaming, agent with tools, model listing) are all covered with runnable code. | 5 / 5 |
Workflow Clarity | The setup-to-request sequence is clear and mostly checkpointed: check region and plan preconditions, enable aiGateway in neon.ts, run `neon deploy` (with `neon config plan` as a dry-run), confirm env vars, then build the client — plus explicit verification/debug guidance (read /v1/models rather than assuming the catalog, distinguish Free-plan blocking from a reduced catalog, `neon config status`). It falls short of a 5 because the sequence is implied by section order rather than presented as an explicit ordered workflow with feedback loops, and there is no end-to-end 'verify the request works' step. | 4 / 5 |
Progressive Disclosure | The file is a ~290-line monolith with no bundle files: reference-grade detail — the 30-line /v1/models JSON response shape, the plan-gating matrix, per-SDK dialect routing, and full Mastra/agent examples — is inlined in SKILL.md where the rubric expects it split into one-level-deep reference files. Section headers are clear and external pointers (Further Reading, the parent neon skill, models.dev) are well signaled, so it sits at the 'some structure but content that should be separate is inline' anchor rather than the unstructured level-2 anchor. | 3 / 5 |
Total | 15 / 20 Passed |