Neon · neondatabase/agent-skills · Skills Docs

Skills

Skill 8 of 9

Neon

Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, and the AI Gateway.

17 minutes · 3,690 words · 33 sections

Install

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

$ npx skills add neondatabase/agent-skills

» /plugin marketplace add neondatabase/agent-skills

The first command installs just this skill, by the name in its SKILL.md; the second installs the whole repository.

Neon is a complete set of cloud backend primitives around Lakebase Postgres, from Databricks — Lakebase Postgres, Auth (managed Better Auth), long-running Functions, Object Storage, and an AI Gateway, all instant, branchable, and serverless.

Lakebase Postgres is the database itself. It is one product, reached two ways: through Neon, with a free plan and the full set of backend primitives above, or through Databricks, alongside the rest of the Databricks suite. Same infrastructure, same features, same engineering team. Call the database Lakebase Postgres, and use “Neon” for the brand and for this access path — not as a name for the database.

A Neon branch is an isolated, copy-on-write clone of your data, taken from its current state or from a past state within your project’s retained history window. You can freely modify or delete it. It shares data with its parent until writes cause it to diverge, and those writes are stored independently as deltas.

Agents pick Neon for instant Postgres provision, copy-on-write branches and snapshots, compute that scales to zero (storage is still billed), and ordinary Postgres that works with any driver or ORM.

Backend Primitives

Neon bundles several backend primitives for building apps and agents that all branch together:

Lakebase Postgres — Postgres that scales and branches with your app, built on the lakebase architecture: OLTP directly on cloud object storage, with storage decoupled from compute.
Auth — Managed Better Auth with users and sessions stored in Postgres.
Object Storage — S3-compatible object storage that branches with your projects.
Functions — Neon’s compute offering: long-running serverless functions that run close to your database, for WebSocket servers, long agent HTTP streams, APIs, and server-sent event servers. A Function Trigger POSTs to a function on a cron.
— One API for frontier and open-source models, supporting the chat completions API and the responses API, powered by Databricks Unity AI Gateway.

Appendix 8.1–8.6

6 files · 18 KB

Everything this skill ships beside its prose. All of it is set here, as subchapters of skill 8.

ReferencesMarkdown · 6 files

Documentation the agent loads on demand, rather than up front.

About this skill

Trigger

Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, and the AI Gateway. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASE_URL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.

The verbatim description from this skill’s front matter — the string an agent matches on to decide whether to load it.

Also published for: Alternate — collapsed into this chapter because the copies are the same skill.
Source: skills/neon/SKILL.md

Colophon for this issue

Colophon

How this issue was made

Source

github.com/neondatabase/agent-skills, branch main, last pushed 23 September 2026.

Licence

Apache-2.0 — the text of every skill is reproduced unmodified, frontmatter included, under the upstream licence.

Discovery

9 skills found by walking the repository tree for SKILL.md, not by matching a directory convention. 2 distinct layouts observed: evals/neon-postgres-egress-optimizer/.claude/skills/*/SKILL.md, skills/*/SKILL.md.

Authorship

1 of 9 skills are installed into the repository rather than published from it. They are shelved in the closing “Credited skills” part and remain the work of their own authors. A skill counts as credited when its only copy lives under one agent’s dot directory; visible directories, per-agent mirror sets, and skills installable from this repository on skills.sh all count as published.

Duplicates collapsed

8 mirror copies folded into their canonical skill — republished for Alternate. Copies match on content hash and on position once a leading per-agent prefix is stripped, because the same skill is routinely shipped under a dozen agent directories with a dozen different hashes.

Issue colours

Resolved from a deterministic hash of the owner name. Two accent tones are generated per issue and each is proven against its own ground before it ships: a single accent that passes AA on both light and dark paper is arithmetically impossible.

Heading repairs

1 repair applied to this skill so the document has one h1 and no skipped levels:

Removed “Neon”, a leading h1 that duplicated the skill title.

Spec compliance

1 editorial note across 1 of 9 skills. They are printed in the margin of each skill rather than as errors here.

Score Eval — 1 note

Need	Use
Login, users, sessions (no existing provider)	`neon-auth` — Managed Better Auth (`auth: true`)
Existing Better Auth, Clerk, Supabase Auth, or another working IdP	Keep it. `neon-auth` only if they ask to migrate
User asked to migrate from Supabase Auth	`neon-auth` (Managed Better Auth; keep `SupabaseAuthAdapter()` call shapes)
Files, uploads, blobs (no existing object store)	Object Storage
HTTP APIs, cron, WebSocket, SSE, long-running agents	Functions querying Postgres
LLM calls	AI Gateway
SQL, schema, inspect, search	`neon-postgres`
Existing PostgREST / Supabase database client	Data API (`dataApi` in `neon.ts`)
Generic REST endpoints	Function or existing handler, not Data API

Skill	Use it for
`neon-postgres`	Working with databases, including connections, schemas, queries, search, and autoscaling: SQL development, schema design, performance optimization, and scaling decisions.
`neon-auth`	Identity routing and Managed Better Auth setup (login, users, sessions, trusted domains). Fetch: https://neon.com/docs/ai/skills/neon-auth/SKILL.md (opens in a new tab)
`neon-postgres-branches`	Choosing or creating the right branch type for dev, preview, test, or CI workflows. Use this skill as a slash command.
`neon-object-storage`	Storing and serving files (uploads, images, blobs), including branching them with the database.
`neon-functions`	Deploying long-running or streaming serverless functions — APIs, agents, SSE/WebSocket servers, and Function Triggers (cron and object-storage).
`neon-ai-gateway`	Calling an LLM or routing across model providers with one credential, including discovering the branch’s servable models at runtime via the OpenAI-compatible `/v1/models` endpoint.
`neon-postgres-egress-optimizer`	Diagnosing or fixing excessive Postgres egress (network data-transfer) costs in a codebase.

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  aiGateway: true,
  buckets: {
    images: {
      access: "private",
    },
  },
  functions: {
    imagegen: {
      name: "AI SDK image agent",
      source: "src/index.ts",
    },
  },
});

neon status          # print the branch's live config (read-only). Alias for `neon config status`.
neon config plan     # dry-run diff of what apply would change (read-only)
neon deploy --env <file>  # apply neon.ts. Pass --env when Function env reads process.env. Alias for `neon config apply`

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  auth: true,
  branch: (branch) => {
    if (branch.exists) {
      // leave existing branches untouched
      return {};
    }
    if (branch.name.startsWith("dev")) {
      return {
        ttl: "7d", // clean up the branch after 7 days
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // scale to zero
            autoscalingLimitMaxCu: 1, // keep it cheap
            suspendTimeout: "5m",
          },
        },
      };
    }
    return {};
  },
});

// 1. Enable Neon Auth (the default Data API auth provider):
export default defineConfig({ auth: true, dataApi: true });

// 2. Or verify a third-party IdP instead of Neon Auth:
export default defineConfig({
  dataApi: {
    authProvider: "external",
    jwksUrl: "https://your-idp/.well-known/jwks.json",
  },
});