bryan-inkeep · May 22, 2026 · May 22, 2026
diff --git a/README.md b/README.md
@@ -28,6 +28,12 @@ A comprehensive index of Neon Serverless Postgres documentation and best practic
 
 Choose and create the right Neon branch type for migration testing and isolated development workflows, including schema-only branches for sensitive data and reset-from-parent workflows to quickly realign child branches.
 
+### Neon Auth
+
+[skills/neon-auth](skills/neon-auth/SKILL.md)
+
+Provision and configure Neon Auth for an app so users can sign in with email/password or OAuth without standing up a separate auth service. Covers trusted origins, OAuth providers, the email provider, and wiring the Neon JS SDK into a Next.js or React project.
+
 ### Claimable Postgres
 
 [skills/claimable-postgres](skills/claimable-postgres/SKILL.md)

diff --git a/skills/neon-auth/SKILL.md b/skills/neon-auth/SKILL.md
@@ -0,0 +1,106 @@
+---
+name: neon-auth
+description: >-
+  Provision and configure Neon Auth for an app so users can sign in with
+  email/password or OAuth without standing up a separate auth service. Use
+  when users ask to add authentication to a Next.js, React, or Node project
+  backed by Neon, configure trusted origins or OAuth providers, manage the
+  email provider, or wire Neon Auth into the Neon JS SDK. Triggers include
+  "Neon Auth", "add authentication", "sign in with Neon", "OAuth provider",
+  "trusted origins", "JWKS URL", "@neondatabase/neon-js auth", "neon auth
+  email provider", and "set up Neon Auth for my Next.js app".
+---
+
+# Neon Auth
+
+The outcome of this skill should be a Neon project branch with Neon Auth provisioned and the application wired up to authenticate users against it.
+
+Neon Auth provides managed user authentication infrastructure for Neon projects — email/password, OAuth providers, JWT-based sessions, and an email provider — without operating a separate auth service.
+
+Official docs: https://neon.com/docs/auth/overview
+
+## When To Use
+
+Pick Neon Auth when the user wants any of:
+
+- Email/password sign-in.
+- OAuth sign-in (for example Google, GitHub).
+- A JWKS endpoint they can verify in their backend.
+- A managed email provider for transactional auth mail.
+
+If the user has an existing auth provider (Clerk, Auth0, custom JWT) and is not asking to replace it, do not provision Neon Auth — recommend their existing provider keep emitting JWTs and point them at Neon's external JWKS configuration on the Data API instead.
+
+## Tool Selection: MCP or Console
+
+Prefer the tool the user already has installed and authenticated.
+
+1. **Neon MCP server** (preferred when available): `provision_neon_auth`, `get_neon_auth_config`, and `configure_neon_auth` cover the full lifecycle.
+2. **Neon Console**: https://console.neon.tech — visual configuration when MCP is not available.
+3. **Neon REST API**: fall back to the API when neither MCP nor Console is appropriate (for example, scripting bulk provisioning).
+
+MCP overview: https://neon.com/docs/ai/neon-mcp-server
+
+## Provision
+
+Provision Neon Auth on the branch the application will authenticate against — typically the default branch for a project.
+
+### MCP path
+
+1. Confirm the target project and branch:
+   - `list_projects` to find the project.
+   - `describe_project` to confirm branches.
+2. Call `provision_neon_auth` for the chosen branch. If Neon Auth is already provisioned, the tool returns the existing configuration instead of erroring — surface that to the user rather than re-running.
+3. Read back the resulting `base_url`, `jwks_url`, and default sign-in methods with `get_neon_auth_config`. The user will need `jwks_url` for backend JWT verification.
+
+### What you get
+
+- `base_url`: hosted Neon Auth endpoint for this branch.
+- `jwks_url`: public JWKS endpoint for verifying issued JWTs.
+- Default trusted origins (typically `http://localhost:3000` for development).
+- A default allowed auth method (email + password).
+
+Secrets such as OAuth client secrets and SMTP passwords are redacted in `get_neon_auth_config` responses; configure them with `configure_neon_auth`.
+
+## Configure
+
+Use `configure_neon_auth` to:
+
+- Add or remove trusted origins (production domains, preview deployment hosts).
+- Toggle localhost as a trusted origin during development.
+- Enable, disable, or tune email-and-password sign-in (for example, require email verification).
+- Add, update, or remove OAuth providers (client ID and secret per provider).
+- Configure the email provider (SMTP host, port, credentials, from address).
+- Send a test email after configuring the provider, before relying on it for production sign-in flows.
+
+When updating production configuration, ask the user to confirm trusted origins and OAuth redirect URIs are correct before applying — a wrong trusted origin will break sign-in for real users.
+
+## Wire Up the App
+
+For Next.js or React, integrate via the Neon JS SDK (`@neondatabase/neon-js`), which has Neon Auth helpers built in. The SDK reads the Neon Auth `base_url` and `jwks_url` from environment variables, so emit those into the project's `.env` after provisioning (do not overwrite existing keys without confirmation).
+
+For backend verification in any language, validate incoming JWTs against `jwks_url`. The Neon Auth-issued JWT's `sub` claim is the user ID.
+
+## Agent Workflow
+
+1. **Confirm intent**: confirm the user wants Neon to host their auth (not just verify external JWTs). If they only need JWT verification, point them at the Neon Data API external-JWKS path instead.
+2. **Pick branch**: confirm which Neon branch should host auth — usually the default branch.
+3. **Provision**: call `provision_neon_auth` via MCP; if already provisioned, surface the existing config.
+4. **Read config**: call `get_neon_auth_config` and share `base_url` and `jwks_url` with the user.
+5. **Add trusted origins**: ask the user for their production and preview domains, then call `configure_neon_auth` to add them.
+6. **OAuth providers (optional)**: if requested, gather client IDs and secrets and add them via `configure_neon_auth`. Remind the user that secrets are redacted on read and cannot be recovered through the API.
+7. **Email provider (optional)**: if email/password sign-in is enabled, configure the email provider and send a test email before considering setup complete.
+8. **Write env**: emit `NEON_AUTH_BASE_URL` and `NEON_AUTH_JWKS_URL` to the project's `.env`. Do not overwrite existing keys without confirmation.
+9. **Report**: tell the user which branch was provisioned, where credentials were written, and what trusted origins are now active.
+
+## Safety and UX Notes
+
+- Never write Neon Auth secrets (OAuth client secrets, SMTP passwords) into committed files. They belong in environment variables or a secret manager.
+- After writing to a `.env` file, check that it is covered by `.gitignore`. If not, warn the user. Do not modify `.gitignore` without confirmation.
+- Do not enable email/password sign-in in production without first configuring the email provider — users will not be able to verify their addresses.
+- When removing a trusted origin, confirm with the user — removing the live production origin will lock real users out.
+
+## Further reading
+
+- https://neon.com/docs/auth/overview
+- https://neon.com/docs/ai/neon-mcp-server
+- https://neon.com/docs/connect/choose-connection