Neon Postgres skill (Using Neon) for Claude: review, verdict, safety and alternatives
The Neon Postgres skill (neon-postgres) is Neon's official Agent Skill for connections, migrations and read-only diagnostics on Neon. Our verdict is Recommended, 76/100, with safety grade C.
- Verdict
- Recommended
- Score
- 76/100
- Confidence
- Moderate
- Safety grade
- C
- Best for
- Teams on Neon who want agents to pick the right connection string, driver and migration path
- Poor fit
- Projects not hosted on Neon; token-constrained agents
- Reviewed version
- plugin 2.0.1, no skill tag (commit b8250e6)
- Review date
- 2026-09-30
- Works in verified
- Claude Code
- Works in claimed
- Cursor · Kimi Code · Pi · skills-CLI agents
- Since review
- plugin 2.3.0; SKILL.md and search references changed 2026-10-12 to 2026-10-15
Get the skill: neon-postgres folder on GitHub · SKILL.md at the reviewed commit · skills.sh listing
What is the Neon Postgres skill?
The Neon Postgres skill, listed as Using Neon, is Neon's official neon-postgres Agent Skill. It guides agents through pooled versus direct connections, drivers, migrations, branching and read-only diagnostics. It ships no code.
Neon is a serverless Postgres service, branded Lakebase Postgres in the skill. The skill is a SKILL.md package that agents load on demand. Our guide explains what an Agent Skill is.
| Fact | Value |
|---|---|
| Publisher | Neon (neondatabase) |
| Path | skills/neon-postgres in neondatabase/agent-skills |
| Licence | Apache-2.0 |
| Files | 5: SKILL.md (16.6 KB, ~4.1K tokens) and 4 search references (~5.3K tokens) |
| Version | Plugin 2.0.1, no skill tag |
| Reviewed commit | b8250e6 (2026-09-30) |
| Contributors | 15 |
| Installs | 204.7K on skills.sh, all three audits Pass |
| Stars and forks | 97 and 20 at review; 101 and 23 on 2026-10-21 |
The skill describes five Neon features (publisher claims, untested):
- Branching
- Autoscaling
- Scale-to-zero
- Read replicas
- Instant restore
Is the Neon Postgres skill worth installing?
Yes, the Neon Postgres skill is worth installing when your database runs on Neon: 76/100, Recommended, Moderate confidence. Its connection and diagnostic guidance is accurate and current. Routing overlap with the parent neon skill and token load hold it back.
Its strength is concrete gotchas from support cases, such as Prisma's prepared-statement error on pooled migrations. A symptom-to-check table keeps agents on read-only commands. Its weakness is routing: the parent neon skill still claims database triggers.
Our page on how we score skills gives the weights.
| Parameter | Score |
|---|---|
| Effectiveness | 78 |
| Reliability | 70 |
| Safety | 78 |
| Efficiency | 64 |
| Compatibility | 76 |
| Maintainability | 88 |
| Setup friction | 70 |
| Connection-type correctness | 85 |
| Diagnostic safety | 84 |
| Routing precision | 60 |
| Reference currency | 86 |
| Instruction weight vs value | 66 |
| Cost of adoption | 70 |
Only a 19-row routing pilot exists, with no task benchmark. Two parameters track the worst failure: migrations on the pooled endpoint, or destructive diagnostics. Compare it with other agent skills ranked by verdict.
How many tokens does the Neon Postgres skill use?
The Neon Postgres skill loads about 4,149 instruction tokens. It asks the agent to load the parent neon skill first, roughly 8,000 more by our estimate. A typical migration task is estimated at 14,000 input and 3,000 output tokens.
| What | Tokens |
|---|---|
| SKILL.md, loaded each time the skill runs (16.6 KB) | 4,149, measured |
| Search references | ~5.3K, our estimate |
| Whole folder | 9,477, measured |
Parent neon skill, loaded first (32.8 KB) |
~8K, our estimate |
| Typical task (wire an app, run a Drizzle migration) | 14,000 in / 3,000 out, our estimate |
| Typical call | 19,149 in / 3,000 out, our cost estimate |
Our estimate assumes 5 uses a week. Loading the parent skill roughly triples instruction tokens (estimate). Diagnostics wake suspended computes and use Neon compute time.
What changed since our review?
The GitHub API showed these changes on 2026-10-21. The verdict stays unchanged.
- 2026-10-12: neon-realtime wiring in SKILL.md (7410538).
- 2026-10-14: AI Gateway embeddings in SKILL.md (c843abc); all four search references rewritten.
- 2026-10-15: neon-realtime merge (f333dd0); SKILL.md is now 16,798 bytes.
- Plugin version: 2.0.1 to 2.3.0.
- New sibling skills: neon-realtime, neon-ai-gateway and neon-auth.
- Still open: issue #76 and PR #73.
Our corrections log shows how we track changes after review.
Is the Neon Postgres skill safe to install?
Yes, the Neon Postgres skill is safe to install with care, at safety grade C. It ships five Markdown files and no code. Its workflows need Neon credentials, write DATABASE_URL into .env and fetch an unpinned parent skill.
Our review of the folder at commit b8250e6 found these facts:
- No scripts, hooks, MCP configs or manifests sit in the folder.
- The neon CLI or Neon MCP server runs the work, and both need Neon authentication.
- The skill writes DATABASE_URL into .env after reading the file first.
- It fetches the parent neon skill from neon.com, and that file is unpinned.
- It asks before CREATE EXTENSION and forbids autonomous EXPLAIN ANALYZE on mutating SQL.
- It treats unused-index output as candidates, not permission to drop.
- It gives no guidance on treating query results as untrusted input.
- Gen Agent Trust Hub, Socket and Snyk audits all pass on skills.sh.
The safety score is 78, yet the grade is C: credentials and a remote file set it, not code. A Snyk fix for a sibling skill (PR #73) remains unmerged. Our guide to checking a skill's credentials and fetches explains the grades.
What does the community report about the Neon Postgres skill?
The community reports about the Neon Postgres skill come mainly from its GitHub repository. Merged PRs #83, #92 and #118 added support-driven guidance. Open issue #76 shows the parent neon skill absorbing a neon-postgres prompt.
| Source | Date | Finding | Sentiment |
|---|---|---|---|
| PR #118 | 2026-09 | Triggers scoped to database work | Positive |
| PR #83 | 2026-08 | Direct-connection gotcha from support cases | Positive |
| PR #92 | 2026-08 | Diagnostics checked against CLI and MCP schemas | Positive |
| Issue #76 | 2026-08 | Parent router absorbed a neon-postgres prompt | Negative |
| Issue #21 | 2026-04 | Ignored --branch-id flag, fixed in two days |
Negative |
| Issue #28 | 2026-05 | Plugin install loaded zero skills | Negative |
| PR #62 | 2026-07 | Plugin vendors real skill copies | Positive |
| PR #73 | 2026-08 | Sibling credential fix unmerged | Negative |
| PR #58 | 2026-07 | 13 unreachable references removed | Positive |
| PR #25 | 2026-05 | Branching skill linked | Positive |
| skills.sh | 2026-09 | 204.7K installs, three audits pass | Positive |
| SKILL.md at b8250e6 | 2026-09 | Depends on an unpinned parent file | Negative |
| Neon connection guide | 2026-09 | Linked neon.com docs all resolve | Positive |
| @vercel/functions 3.9.9 | 2026-09 | attachDatabasePool still exported | Positive |
The 14 items split 9 positive and 5 negative, with 6 rated strong. Evidence confidence is Moderate.
What are the Neon Postgres skill's known failures?
The Neon Postgres skill has two known failures at commit b8250e6. The parent neon skill can intercept database prompts (issue #76, still open). The skill depends on an unpinned parent file fetched from neon.com.
- Routing overlap. In issue #76's 19-row Haiku pilot, the parent neon skill took a neon-postgres prompt, then used WebFetch. PR #118 narrowed this skill's triggers, but neon still claims postgres and database.
- Unpinned dependency. The pinned SKILL.md loads the parent skill from neon.com at runtime.
Fixed before review: issue #21's ignored --branch-id flag and issue #28's empty plugin install (PR #62). Our guide covers why the wrong skill loads.
Which Neon skill should you install?
Install neon-postgres when you need database work, and Neon's parent neon skill for the wider platform. Both live in neondatabase/agent-skills. Neon's separate postgres-skills repository holds a generic Postgres best-practices skill we have not evaluated.
| Skill or package | Source | Job | Our verdict |
|---|---|---|---|
| neon-postgres (Using Neon) | neondatabase/agent-skills | Connections, drivers, migrations, diagnostics | Recommended, 76 |
| neon (parent) | neondatabase/agent-skills | Platform router: Postgres, Auth, Functions, Object Storage and more | Not evaluated |
| neon-postgres-branches, neon-auth, neon-realtime, neon-ai-gateway, others | neondatabase/agent-skills | Sibling specialists, 9 skills in total | Not evaluated |
| Neon Claude Code plugin | neon@claude-plugins-official (docs) or neon-postgres@neon (README) |
Bundles skills and the Neon MCP server | Not a skill |
| postgres-best-practices | neondatabase/postgres-skills | Generic Postgres guidance | Not evaluated |
| neon-drizzle, neon-serverless, neon-toolkit, add-neon-knowledge | neondatabase/ai-rules (2025) | Older skill set | Not evaluated |
| neon-instagres | aitmpl (third-party template) | Instant database provisioning | Not evaluated |
GitHub code search counts 1,122 SKILL.md files named neon-postgres, forks included. Install from neondatabase only.
Which agents does the Neon Postgres skill work with?
The Neon Postgres skill is verified only in Claude Code. Neon packages it for Cursor, Kimi Code and Pi, and the skills CLI reaches other agents. No run outside Claude Code appears in our evidence.
| Agent | Status | Source |
|---|---|---|
| Claude Code | Verified | User reports #28 and #76 |
| Cursor | Claimed | Repo packaging |
| Kimi Code | Claimed | Repo packaging |
| Pi | Claimed | Repo packaging |
Antigravity (agy plugin install) |
Claimed, added after review | README |
| Other agents via the skills CLI | Claimed | Publisher |
Our list of top Claude Code skills has verified picks.
How do you install the Neon Postgres skill?
Install the Neon Postgres skill with npx skills add neondatabase/agent-skills -s neon -s neon-postgres. Neon's docs list the official Claude plugin, neon@claude-plugins-official. You need a Neon account and the neon CLI or Neon MCP server.
Two official sources give different routes, checked on 2026-10-21.
| Source | Route | Command |
|---|---|---|
| Neon docs | Claude plugin | claude plugin install neon@claude-plugins-official |
| Neon docs | skills CLI | npx skills add neondatabase/agent-skills -s neon -s neon-postgres |
| Neon docs | neon CLI | neon skills -s neon -s neon-postgres |
| Repo README | Neon marketplace | /plugin install neon-postgres@neon |
| Repo README | Cursor | /add-plugin neon-postgres |
- Create a Neon account.
- Install the neon CLI, or connect the Neon MCP server.
- Run the skills CLI in your project:
npx skills add neondatabase/agent-skills -s neon -s neon-postgresThe README route in Claude Code adds the marketplace with /plugin marketplace add neondatabase/agent-skills. It then runs /plugin install neon-postgres@neon. At b8250e6 this installed the whole bundle: 8 skills and the Neon MCP config.
Setup friction scores 70. Our guide to adding skills to Claude Code covers scopes. Read when an MCP server beats a skill before you add both.
How do you use the Neon Postgres skill?
Use the Neon Postgres skill by asking to connect an app, run a migration or diagnose a slow query. It picks pooled or direct connection strings and tests migrations on a branch. Diagnostics stay read-only.
DATABASE_URL_UNPOOLED is the direct connection string that bypasses Neon's pooler. Three tasks fit the skill:
- Choose pooled or direct strings and a driver for Vercel, Cloudflare or edge runtimes.
- Run migrations on a branch over the direct connection, with Prisma, Drizzle or Alembic.
- Diagnose slow queries with
neon inspect dbor the MCPinspect_databasetool.
Lakebase Search (vector, BM25, hybrid) and autoscaling explanations are claimed only.
Test it yourself:
- Install neon-postgres alongside neon.
- Ask 10 database prompts on your model.
- Check which skill loads.
- Check that migrations use DATABASE_URL_UNPOOLED.
What are the alternatives to the Neon Postgres skill?
The closest evaluated alternative to the Neon Postgres skill is Supabase Postgres Best Practices: Conditional, 66/100, safety grade A. It teaches portable Postgres patterns. Neither it nor the Postgres read-only skill by sanjay3290 covers Neon pooling or branching.
| Skill | Publisher | Verdict | Note |
|---|---|---|---|
| Supabase Postgres Best Practices | Supabase | Conditional, 66, Moderate, safety A | Portable Postgres rules; one RLS helper example is known broken |
| Postgres (read-only SQL) | sanjay3290 | Conditional, 66, Low, safety C | Runs single read-only SQL statements |
| postgres-best-practices | Neon (postgres-skills) | Not evaluated | Generic Postgres |
Read our Supabase Postgres Best Practices verdict for the full comparison.
Common questions
For general questions, start with Claude skills explained. Our guide to giving Claude a new skill covers the Claude app. To build your own, read Anthropic's skill-creator verdict.
Does the Neon Postgres skill work without a Neon database?
No. It targets Neon, and generic Postgres skills fit other hosts better.
Do you need the Neon MCP server?
No. The neon CLI works instead, and both need Neon authentication.
Is the Neon Postgres skill free?
Yes, it is Apache-2.0. Neon bills compute time separately.
Why did Claude load the neon skill instead?
The parent skill claims the same database triggers (issue #76). Run the test above on your model.
What is Neon, and how does it differ from plain PostgreSQL?
Neon is a serverless Postgres service with branching and scale-to-zero. Neon states it is fully Postgres-compatible (vendor-reported).
Where is the Neon Postgres skill on GitHub?
It sits in skills/neon-postgres in neondatabase/agent-skills. Our guide explains the SKILL.md format.