neon-postgres Skill for Claude: Neon Postgres Connections, Branches and Search

neon-postgres gives your agent Neon's Postgres guidance: connections, migrations, branching, autoscaling, diagnostics and search.

Installs: 298.5K; on skills.sh
Stars: 108; on GitHub
Files: 4; besides SKILL.md
Updated: Oct 2026; last repo commit

neon-postgres triggers on work with an existing DATABASE_URL, SQL, schemas, neon inspect, or semantic, vector, full-text and hybrid search. It tells the agent when to use the pooled or direct connection string, to test migrations on a branch of production, and to run Neon's read-only inspect checks before writing catalog queries by hand.

It begins by using the parent neon skill, so install both. New backends, Auth, files and Functions go to the parent skill, and live queries go to neon-realtime. It uses the Neon CLI by default, or the Neon MCP server, and needs a Neon project.

Good for

Developers using a Neon database through a DATABASE_URL, SQL or a schema
Teams testing migrations on a branch before production
Anyone adding vector, full-text or hybrid search to a Neon Postgres project

Install neon-postgres

Claude Code

Copy this prompt.

Install the neon-postgres skill in Claude Code. Run this command:

npx skills add neondatabase/agent-skills --skill neon --skill neon-postgres

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

neon-postgres starts by using the parent neon skill, so install both. Optional companions from the same repo include neon-postgres-branches for branch workflows and neon-realtime for live queries.

From the vendor's docs. Source.

What's in the skill

When it loads

Guides and best practices for working with Lakebase Postgres on Neon: connections, pooled vs direct, schema migrations, branching, autoscaling, scale-to-zero, instant restore, read replicas, IP allow lists, logical replication, and Lakebase Search. Use when the work is an existing DATABASE_URL, SQL, schema, inspect, or search. New backends, Auth, files, Functions, and LLM calls go to the parent `neon` skill. Live queries, reactive UIs, and realtime data go to `neon-realtime`. Also use for "@neondatabase/serverless", "@neon/neon-js", "neon inspect db", "semantic search", "vector search", "full-text search", "BM25", or "hybrid search".

Sections in SKILL.md

Setup Flow
1. Select the organization and project
2. Get the connection string
3. Pick the connection method and driver
4. Set up the schema
Branching
Migrations
Troubleshooting and Neon-Specific Performance
Choose CLI or MCP
Pick the Diagnostic
Interpret Results Safely
Inspect Neon Cache Behavior Per Query
Performance Workflow
Autoscaling
Scale to Zero
Keep hot reads off Postgres

Key facts

Author: Neon (neondatabase/agent-skills)
License: Apache-2.0
Installs on skills.sh: 298,543 as of 2026-11-02
GitHub stars: 108 for the whole neondatabase/agent-skills repo
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass
What is inside: 4 files besides SKILL.md (4 in references/)
Needs: The parent neon skill; the Neon CLI (default) or Neon MCP server; a Neon project and DATABASE_URL
Part of plugin: neon
Last commit to the repo: 2026-10-30

What it includes

Starts with the neon skill for the overview
If it is missing, SKILL.md says to fetch it from neon.com or install it with `neon skills -s neon -y`.
Read · Parent neon skill first
Uses your DATABASE_URL, or the CLI to find one
If DATABASE_URL is supplied it uses that. Otherwise it lists organizations and projects, runs `neon env pull`, and stores the string in .env after reading the file.
Try: “Set up my Neon connection and use the direct URL for the Drizzle migration.”
Files · Project and connection string
Pooled for apps, direct for migrations and dumps
Direct for schema migrations, pg_dump, logical replication, LISTEN/NOTIFY and session state. Pooled strings carry the -pooler suffix.
Read · Pooled or direct
Tests a migration on a production branch first
Uses the Neon CLI or MCP to create and compare branches. Detailed branch workflows live in the neon-postgres-branches skill.
Runs code · Branching and migrations
Predefined read-only diagnostics
Checks such as table-sizes, unused-indexes, locks, outliers, bloat and replication-slots. The MCP inspect_database tool runs the same checks.
Runs code · neon inspect db checks
Vector, full-text and hybrid search guides
Four reference files cover semantic search, BM25 full-text search, hybrid search and managing search with Drizzle.
Read · Lakebase Search
Autoscaling, scale to zero, restore, replicas, IP allow lists
Short notes with links to the Neon docs for each feature.
Read · Platform topics

From the official docs

Permissions

Medium risk

The agent can run SQL and migrations on your Neon database and write the connection string to .env. Try changes on a branch or dev database first.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can run SQL and migrations on your database
Use a branch of production to test schema changes, as SKILL.md advises, and use a direct connection string for migrations.
It stores your connection string in .env
SKILL.md says to read .env first so it does not overwrite values. Keep .env out of git.
It asks before installing database extensions
SKILL.md says to ask before CREATE EXTENSION because it changes the database.

Technical details

Talks to	Neon API through the CLI or MCP server. Your Neon database
Scopes	Runs the Neon CLI or Neon MCP tools as your account Can read or write DATABASE_URL in .env Can run SQL, migrations and branch commands

Questions

What does the neon-postgres skill do?

It gives your agent Neon-specific Postgres guidance for connections, branching, migrations, diagnostics, scaling and search. It is a documentation index plus working rules, not a database tool by itself.

How do I install it?

Use the install box at the top of this page, which has tabs for Claude Code, the Claude app and Codex. The install box adds the parent neon skill as well, which this skill starts from.

Do I need the parent neon skill?

Yes, SKILL.md starts by telling the agent to use it for the Neon overview and getting started. It also gives a command to install it if missing.

Does it need an API key?

No key is named in SKILL.md. It uses the Neon CLI or MCP server, which must be authenticated, and a DATABASE_URL for your database.

Pooled or direct connection string?

Use pooled for web apps and serverless functions. Use direct for schema migrations, pg_dump, logical replication and anything that relies on session state.

Can it change my database?

Yes, through SQL, migrations and branches via the CLI or MCP. SKILL.md has it test migrations on a branch and ask before CREATE EXTENSION.

Is it safe?

It can write your connection string to .env and run SQL, so point it at a branch or dev database first. See the audit results under key facts.

Information

updated Nov 2, 2026

Repository: neondatabase/agent-skills
Folder: skills/neon-postgres

neondatabase/agent-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

neondatabase/agent-skills README · github.com
skills CLI commands · github.com
neon-postgres SKILL.md · github.com
skills.sh listing and audits · skills.sh