Kipt

Neon skill: the official overview skill for building on Neon

The official neon skill gives your coding agent Neon's setup path, neon.ts config, branch-first workflow and backend primitives. Install and use it.

By the Kipt team · Updated 24 October 2026

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

What is the neon skill?

The neon skill is Neon's official overview skill: it teaches your coding agent what Neon offers, how to set it up with the CLI or MCP server, and how to work branch-first, then hands detailed tasks to child skills. Install it with npx skills add https://github.com/neondatabase/agent-skills --skill neon.

Its description opens: "Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime." It tells the agent to start here when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" comes up.

It is the parent of the Neon Postgres skill and the second most installed skill in neondatabase/agent-skills, after neon-postgres. As of 24 October 2026, its skills.sh page listed 228.5K installs (snapshot, 24 October 2026).

What does it do?

The skill is model-invoked. The SKILL.md is long, and it covers seven topics.

Backend primitives. It describes Lakebase Postgres, Auth (managed Better Auth), Object Storage (S3-compatible, branches with the project), Functions (long-running serverless functions near the database), the AI Gateway (one API for many models), Realtime (beta, live SQL queries) and an optional Data API. It notes Object Storage, Functions, AI Gateway and Realtime are only in four AWS regions: aws-us-east-2, aws-us-east-1, aws-eu-central-1 and aws-ap-southeast-1.

Architecture. The default it recommends is a full-stack app, with Next.js on Vercel first, that queries Postgres from route handlers or Neon Functions. "Neon does not host the frontend." It offers the Data API only as a migration path for apps that already use PostgREST or a supabase-js database client, warning that browser-facing RLS "is easy to get wrong."

Converting an existing app. Five steps: map the capabilities you need, reuse what is already there, choose Neon services only for undecided needs, provision only when infrastructure is missing, then verify the real flow (sign-in, upload, API call). It says not to replace a working Better Auth, Clerk, Supabase Auth, S3 or supplied DATABASE_URL unless you ask.

Routing to child skills. Two tables in the SKILL.md send each need to the right place, combined here:

Need Where the skill sends it
SQL, schema, inspect, search neon-postgres
Login, users, sessions neon-auth (Managed Better Auth)
Branch type for dev, preview, test or CI neon-postgres-branches
Files and uploads neon-object-storage
APIs, cron, WebSocket or SSE servers neon-functions
LLM calls neon-ai-gateway
Live queries neon-realtime
High egress costs neon-postgres-egress-optimizer

Setup. "Prefer the CLI over the MCP server" unless the user says otherwise or the CLI isn't available. The agent checks neon --version, installs the CLI with npm i -g neon if needed, and reuses existing credentials. A human signs in with neon login; an unattended agent must not open browser authentication. neon init sets up agent tooling and a project in one step, neon mcp --agent <agent> -y installs the MCP server, and neon link writes project IDs to a git-ignored .neon file.

neon.ts and the branch-first loop. neon.ts is Neon's TypeScript config file (from @neon/config) that declares which services each branch gets. neon config plan shows a dry-run diff and neon deploy applies it, then pulls env vars into .env.local. For daily work, "Create a Neon branch any time you would create a git branch": neon checkout <name> --create makes a branch and pulls its DATABASE_URL, and neon diff shows schema changes against the parent.

Docs, logs and resources. The agent looks up pages in https://neon.com/docs/llms.txt and fetches them as Markdown, queries branch logs with neon logs query, and uses @neon/sdk to manage projects, branches and snapshots.

The references/ folder adds six files: auth.md, claimable-neon.md, function-triggers.md, logs-loki.md, parse-env.md and sdk.md.

How do you install it?

Neon's agent skills docs and the repo README list these routes.

Just this skill, with the skills CLI. The command on skills.sh:

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

Run npx skills add neondatabase/agent-skills for every Neon skill. The folder lands in .claude/skills/neon/ in your project, or ~/.claude/skills/neon/ with -g, the standard Claude Code skill locations.

With the Neon CLI. From the SKILL.md and Neon's docs:

neon skills -s neon

Add --global for a user-level install. neon skills update refreshes installed Neon skills.

One-step setup. Neon's docs suggest running this in the project folder, then restarting your editor and asking your assistant to "Get started with Neon":

npx neon@latest init

It installs agent tooling (a plugin, or skills and the MCP server), links a Neon project and can write a neon.ts file.

Claude Code plugin. The README's commands are /plugin marketplace add neondatabase/agent-skills and /plugin install neon-postgres@neon, which bundle Neon skills with the Neon MCP Server. Neon's docs say editor plugins currently bundle the core Postgres skill set and suggest npx skills add neondatabase/agent-skills -y for Functions, Object Storage, AI Gateway and Realtime, though the repo's plugin folder already ships copies of those skills, including neon. See Claude Code plugins.

Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills. For Cursor, the README also offers /add-plugin neon-postgres.

How do you use it?

Ask at the level of the app, not the database. The skill decides which Neon service fits and which child skill to load.

Example prompts (suggestions, not quotes from the repo):

  • Get started with Neon for this Next.js app. (also the README's first example)
  • Give me a quick temporary Postgres database. I don't have a Neon account yet.
  • Add file uploads to this app. Use Neon Object Storage if nothing else is set up.
  • Create a Neon branch for this feature, then show me the schema diff before I merge.
  • Write a neon.ts that gives every new dev branch a 7-day TTL and a scale-to-zero compute.

Expect the agent to inspect your repo first. The skill tells it to keep existing auth and storage providers unless you ask to migrate.

Tips and limits

From the SKILL.md and skills.sh, not from testing:

  • Region limits. Object Storage, Functions, AI Gateway and Realtime work only in the four regions above. The skill tells the agent to check your region before guiding you through them.
  • Silent feedback. After your task is done, the skill tells the agent to check for neon feedback or an MCP send_feedback tool and, if one works without prompting, send one report about Neon-side problems with secrets stripped. It says, "No need to tell the user whether feedback was sent." Add a rule to your CLAUDE.md or AGENTS.md if you don't want that.
  • Env files. link, checkout and deploy write variables like DATABASE_URL into .env or .env.local by default. Use --no-env-pull on link or checkout if you inject env at runtime.
  • Claimable projects expire. Per the SKILL.md, unclaimed projects expire after 72 hours today and claim codes after 15 minutes.
  • Costs. The skill notes compute can scale to zero but "storage is still billed." Check Neon's pricing page for current plans.
  • Audits. On 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub, Socket and Snyk, all audited 17 October 2026. Gen Agent Trust Hub listed fetching Neon docs as an indirect prompt injection surface while rating the skill safe.
  • License. Apache-2.0, from the repo's LICENSE file; the skill folder has none of its own. You can copy and change it if you keep the license and notices.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box; Kipt reads the SKILL.md and its six references/ files. Paste the repo link instead and Kipt lists every Neon skill to pick from, such as neon-postgres and neon-postgres-branches. Your library stays in a private GitHub repo you own and installs 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

Questions

What is the neon skill?

neon is the parent Agent Skill in Neon's official neondatabase/agent-skills repo. It gives a coding agent an overview of Neon's backend primitives around Lakebase Postgres (Auth, Object Storage, Functions, AI Gateway and Realtime), the CLI and MCP setup, the neon.ts config file and a branch-first workflow. It routes detailed work to child skills.

How do I install the neon skill?

Run npx skills add https://github.com/neondatabase/agent-skills --skill neon, or use the Neon CLI with neon skills -s neon. Neon's docs also offer npx neon@latest init, which installs agent tooling, links a Neon project and can write a neon.ts file.

What is the difference between the neon and neon-postgres skills?

neon is the overview: choosing Neon services, setup, neon.ts and the branch workflow. neon-postgres is a child skill for database work such as an existing DATABASE_URL, SQL, schema changes, inspection and search. The neon skill's description says neon-postgres wins for those tasks.

Can the neon skill create a database without a Neon account?

Yes, through Claimable Neon. With no account, the skill points the agent to a claimable project path; the SKILL.md says unclaimed projects currently expire after 72 hours and claim codes after 15 minutes. Functions, Object Storage and AI Gateway need the project to be claimed first.

Does the neon skill send data to Neon?

It can send feedback. After your task is done, the skill tells the agent to silently check for neon feedback or an MCP send_feedback tool and, if one runs without interaction, submit one report about Neon-side problems, with secrets removed. It also says: 'No need to tell the user whether feedback was sent.'

More in Skill directory

All guides

Keep your prompts and skills in one place, in your own GitHub. Install every skill with one command.

Get started

Kipt is an independent product, not affiliated with or endorsed by Anthropic, OpenAI, Cursor or GitHub. Claude, ChatGPT, Codex, Cursor and GitHub are trademarks of their owners.