Neon Postgres skill: what it does and how to install it

Source: neondatabase/agent-skills · Maintainer: Neon · License: Apache-2.0 · Checked: 24 October 2026

What is the Neon Postgres skill?

The Neon Postgres skill is Neon's official guide for coding agents working on a Neon database: how to connect, when to use the pooled or direct connection string, how to test migrations on a branch, and which built-in diagnostics to run before rewriting a query. It is for developers who already use Neon, or are choosing it, and want the agent to follow Neon's own advice instead of generic Postgres habits.

The skill lives in neondatabase/agent-skills. Its description begins: "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." Lakebase Postgres is the name the skill uses for the database at the core of Neon.

As of 24 October 2026, its skills.sh page listed 275.0K installs (snapshot, 24 October 2026).

What does it do?

The skill is model-invoked. Its description tells the agent to load it when the work involves an existing DATABASE_URL, SQL, schema changes, database inspection or search, and when you mention terms like @neondatabase/serverless, neon inspect db, "vector search", "BM25" or "hybrid search". It hands other work to sibling skills: new backends, Auth, files, Functions and LLM calls go to the parent neon skill, and live queries go to neon-realtime.

What's in the folder:

• SKILL.md: setup flow, branching, migrations, diagnostics, platform features and gotchas.
• references/vector-search.md: semantic search with the lakebase_vector extension.
• references/full-text-search.md: full-text search with BM25 ranking.
• references/hybrid-search.md: combining semantic and lexical results with fusion or reranking.
• references/lakebase-search-drizzle.md: managing Lakebase Search through Drizzle ORM.

The main guidance in the SKILL.md:

Reuse what exists. If a DATABASE_URL or a .neon file is already present, the agent uses it and does not create a second project. It also keeps your existing ORM and driver. For new TypeScript schema work with no prior choice, it names Drizzle as a suggestion.

Pick the right connection. A table maps use cases to connection types:

Driver notes by platform. On Vercel, node-postgres with Fluid compute and attachDatabasePool; on Cloudflare, node-postgres with Hyperdrive; for other serverless and edge runtimes, the @neondatabase/serverless driver.

Test migrations on a branch. The skill says to run a migration against a branch of production before production itself, over the direct connection, and to manage schemas as code rather than ad hoc.

Diagnose with built-in checks. It maps symptoms to neon inspect db checks (also available as the MCP inspect_database tool): table-sizes, unused-indexes, seq-scans, long-running-queries, locks, outliers, calls, lfc-hit-rate, bloat and others. It warns the agent to treat unused-indexes as a candidate list, not permission to drop, and to ask before running CREATE EXTENSION. It also shows Neon's extra EXPLAIN options, FILECACHE and PREFETCH, for cache behavior per query.

Shorter sections cover autoscaling, scale to zero (idle computes suspend after 5 minutes of inactivity, which Neon's scale to zero docs confirm), instant restore, read replicas, PgBouncer pooling, IP allow lists and logical replication, each with a link to Neon's docs.

How do you install it?

The skills.sh page gives this command for just this skill:

npx skills add https://github.com/neondatabase/agent-skills --skill neon-postgres

The README installs every Neon skill with npx skills add neondatabase/agent-skills. Since neon-postgres defers to the parent neon skill for getting started, installing both makes sense. The SKILL.md also gives the Neon CLI route for the parent skill:

neon skills -s neon -y

The folders land in .claude/skills/neon-postgres/ in your project, or ~/.claude/skills/neon-postgres/ for all projects, the standard Claude Code skill locations.

Claude Code plugin with the MCP server. From the README:

/plugin marketplace add neondatabase/agent-skills
/plugin install neon-postgres@neon

The plugin bundles the Neon skills and the Neon MCP Server; the README says you'll be prompted to authenticate with Neon through OAuth the first time you use MCP tools. For Cursor, the README's command is /add-plugin neon-postgres.

claude.ai. You can zip the neon-postgres folder and upload it under Customize > Skills, following Anthropic's help article on skills. The Apache-2.0 License permits this.

Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

How do you use it?

Ask about the database you have. Some of these come close to the README's own examples; all are suggestions:

• Recommend a connection method for this Next.js app on Vercel and update .env.
• Add a full_name column to users. Test the migration on a Neon branch first, then give me the command for production.
• The dashboard query got slow this week. Run the relevant neon inspect db checks and tell me what you find.
• Add semantic search over the docs table with Lakebase Search and Drizzle.
• Prisma Migrate fails with "prepared statement s0 already exists". What's wrong?

Requirements: a Neon account and project, plus either the Neon CLI (the skill's default) or the Neon MCP Server for anything that touches the project. The skill's vector search reference notes that Lakebase Search requires Postgres 16 or later.

Tips and limits

• Use the direct URL for migrations. This is the skill's main gotcha. neon env pull writes DATABASE_URL (pooled) and DATABASE_URL_UNPOOLED (direct). The skill lists failures that never mention pooling, such as relation "mytable" does not exist after a SET search_path, and suggests pointing Prisma's directUrl at the direct string rather than swapping DATABASE_URL. That setting applies to Prisma 6 and earlier: Prisma's config reference says directUrl was removed in Prisma ORM v7, where the CLI uses the url in prisma.config.ts, so point that url at the direct string instead.
• It splits work across skills. Query rewriting, indexing and locking go to a postgres-best-practices skill that Neon maintains in neondatabase/postgres-skills. Branch workflows go to neon-postgres-branches. Install those too if you want the full set.
• Some diagnostics need extensions. outliers and calls require pg_stat_statements; lfc-hit-rate and working-set require the neon extension. Statistics reset when compute restarts, including after scale to zero.
• Careful with EXPLAIN ANALYZE. It executes the statement, so the skill says not to run it on its own for mutating SQL.
• Security audits. On 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub, Socket and Snyk.

The skill runs no scripts of its own; database actions go through the CLI or MCP tools you authorize. The Apache-2.0 License lets you copy and modify it if you keep the license and notices and mark changed files.

Save it in your Kipt library

Kipt keeps your prompts and skills as Markdown in a private GitHub repo you own. Open Skills and paste the folder link, https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres, into the import box; the import brings the references/ files along. Paste the repo link instead and it lists every Neon skill so you can pick neon and neon-postgres-branches too. Install your whole library into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Neon or Databricks.

Similar skills

• Postgres best practices skill: Supabase's 31 rules for indexes, RLS, pooling and locking on any Postgres.
• Prisma skill: Prisma's Client API reference skill, for the query side of an app that uses Neon.
• Better Auth skill: configuration guidance for Better Auth, which supports @neondatabase/serverless as a direct connection.
• Deprecation and migration skill: expand/contract schema changes to test on a Neon branch.