vybekiit 0.7.4 → 0.7.7

package/dist/global-skills/neon-postgres/SKILL.md

@@ -1,284 +1,74 @@
 ---
 name: neon-postgres
 description: >-
-  Guides and best practices for working with Neon Serverless Postgres.
-  Covers setup, connection methods, branching, autoscaling, scale-to-zero,
-  read replicas, connection pooling, Neon Auth, and the Neon CLI, MCP server,
-  REST API, TypeScript SDK, and Python SDK.
-  Use when users ask about "Neon setup", "connect to Neon", "Neon project",
-  "DATABASE_URL", "serverless Postgres", "Neon CLI", "neon", "Neon MCP",
+  Guides and best practices for working with Lakebase Postgres, the database
+  behind Neon. Covers setup, connection methods and drivers, pooled vs direct
+  connections, branching, schema migrations, autoscaling, scale-to-zero, instant
+  restore, read replicas, connection pooling, IP allow lists, and logical
+  replication.
+  Use when users ask about "Lakebase Postgres", "Neon setup", "connect to Neon",
+  "Neon project", "DATABASE_URL", "serverless Postgres", "Neon CLI", "neon", "Neon MCP",
   "Neon Auth", "@neondatabase/serverless", "@neondatabase/neon-js",
-  "scale to zero", "Neon autoscaling", "Neon read replica", or
-  "Neon connection pooling".
+  "scale to zero", "Neon autoscaling", "Neon read replica",
+  "Neon connection pooling", or "schema migrations".
+metadata:
+  parent: neon
+  source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres
 ---
 
-# Neon Serverless Postgres
+**FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
 
-Guide the user through any Neon-related task: setup, connections, branching, and advanced features. Deliver a working Neon connection, a completed feature configuration, or a specific answer from the official Neon docs.
-
-Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres.
-
-## Neon Documentation
-
-The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data.
-
-### Fetching Docs as Markdown
-
-Any Neon doc page can be fetched as markdown in two ways:
-
-1. **Append `.md` to the URL** (simplest): https://neon.com/docs/introduction/branching.md
-2. **Request `text/markdown`** on the standard URL: `curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching`
-
-Both return the same markdown content. Use whichever method your tools support.
-
-### Finding the Right Page
-
-The docs index lists every available page with its URL and a short description:
-
-```
-https://neon.com/docs/llms.txt
-```
-
-Common doc URLs are organized in the topic links below. If you need a page not listed here, search the docs index: https://neon.com/docs/llms.txt. Don't guess URLs.
-
-## What Is Neon
-
-Use this for architecture explanations and terminology (organizations, projects, branches, endpoints) before giving implementation advice.
-
-Link: https://neon.com/docs/introduction/architecture-overview.md
-
-## Getting Started
-
-Use this section when guiding a user through first-time Neon setup.
-
-### Check Status Quo
-
-Before starting setup, inspect the user's codebase and environment:
-
-- Existing database connection code
-- Existing Neon MCP server or Neon CLI configuration
-- Existence of a `.env` file and `DATABASE_URL` environment variable
-- Existing ORM (Prisma, Drizzle, TypeORM) configuration
-
-### Self-Driving Setup With Neon's CLI or MCP Server
-
-Offer to inspect existing connected Neon projects or create new ones using the Neon CLI or MCP server. If neither is set up yet, run init with the `--agent` flag. Use `npx -y` to skip the package install prompt. Auth is handled automatically. If the user is not logged in, it opens their browser for OAuth and waits for completion before proceeding.
+If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
 
 ```bash
-npx -y neon@latest init --agent <agent-name>
-```
-
-Supported `--agent` values: `cursor`, `copilot`, `claude`, `claude-desktop`, `codex`, `opencode`, `cline`, `gemini-cli`, `goose`, `zed`.
-
-This installs the Neon extension (for Cursor/VS Code) or MCP server (for other agents), creates an API key, and adds the `neon-postgres` agent skill to the project.
-
-If `init` is not suitable, the individual steps can be run non-interactively:
-
-- **Extension:** `cursor --install-extension databricks.neon-local-connect`
-- **MCP server:** `npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>`
-- **Agent skill:** `npx skills add neondatabase/agent-skills --skill neon-postgres --agent <agent-name> -y`
-
-For full CLI installation options, see https://neon.com/docs/reference/cli-install.md
-
-### Setup Flow
-
-**1. Select Organization and Project**
-
-Use MCP server or CLI to list organizations and projects. Let the user select an existing project or create a new one.
-
-**2. Get Connection String**
-
-Use MCP server or CLI to get the connection string. Store it in `.env` as `DATABASE_URL`. Read the file first before modifying to avoid overwriting existing values.
-
-**3. Pick Connection Method & Driver**
-
-Refer to the connection methods guide to pick the correct driver based on deployment platform: https://neon.com/docs/connect/choose-connection.md
-
-**4. User Authentication with Neon Auth (if needed)**
-
-Skip for CLI tools, scripts, or apps without user accounts. If the app needs auth: use MCP server `provision_neon_auth` tool, then see the auth overview (https://neon.com/docs/auth/overview.md) for setup. For auth + database queries, see the JavaScript SDK reference (https://neon.com/docs/reference/javascript-sdk.md).
-
-**5. ORM Setup (optional)**
-
-Check for existing ORM (Prisma, Drizzle, TypeORM). If none, ask if they want one. For Drizzle integration, see https://neon.com/docs/guides/drizzle.md.
-
-**6. Schema Setup**
-
-- Check for existing migration files or ORM schemas
-- If none: offer to create an example schema or design one together
-
-### Resume Support
-
-If resuming setup, check what's already configured (MCP connection, `.env` with `DATABASE_URL`, dependencies, schema) and continue from the next incomplete step.
-
-### Security Reminders
-
-Remind users to use environment variables for credentials, never commit connection strings, and use least-privilege database roles.
-
-## Connection Methods & Drivers
-
-Use this when you need to pick the correct transport and driver based on runtime constraints (TCP, HTTP, WebSocket, edge, serverless, long-running).
-
-Link: https://neon.com/docs/connect/choose-connection.md
-
-### Recommended: Drizzle + the right driver for your runtime
-
-Always pair Neon with an ORM such as **Drizzle** for easy schema management and migrations. Pick the driver based on how the runtime treats your code:
-
-- **Long-running or shared-runtime environments → node-postgres (`pg`).** Neon Functions, and any host where the function runtime is shared across requests / runs on fluid compute (e.g. **Vercel** with Fluid compute), keep a module-scope process alive across many requests. Open a `pg` pool **once at module scope** and reuse it across requests.
-- **Fully isolated serverless (Lambda-style) → Neon's serverless driver (`@neondatabase/serverless`).** Hosts like **Netlify** spin up a fresh, isolated instance per request, so a persistent TCP pool can't be reused; the serverless driver queries over HTTP and is built for this.
-
-**Neon Functions / Vercel / fluid compute — Drizzle + node-postgres:**
-
-```typescript
-import { drizzle } from "drizzle-orm/node-postgres";
-import { Pool } from "pg";
-import * as schema from "./schema";
-
-// Created once at module scope; reused by every request the instance handles.
-const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
-const db = drizzle({ client: pool, schema });
+npx skills add neondatabase/agent-skills --skill neon
 ```
 
-On **Vercel** (Fluid compute) also attach the pool with `attachDatabasePool` from `@vercel/functions`, so the function runtime drains idle connections before an instance suspends:
-
-```typescript
-import { drizzle } from "drizzle-orm/node-postgres";
-import { Pool } from "pg";
-import { attachDatabasePool } from "@vercel/functions";
-import * as schema from "./schema";
-
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-attachDatabasePool(pool); // let the Vercel runtime manage the pooled connections
-const db = drizzle({ client: pool, schema });
-```
-
-**Netlify and other fully-isolated serverless — Drizzle + Neon serverless driver:**
-
-```typescript
-import { drizzle } from "drizzle-orm/neon-http";
-import { neon } from "@neondatabase/serverless";
-
-const sql = neon(process.env.DATABASE_URL!);
-const db = drizzle({ client: sql });
-```
-
-### Serverless Driver
-
-Use this for `@neondatabase/serverless` patterns, including HTTP queries, WebSocket transactions, and runtime-specific optimizations.
+# Lakebase Postgres
 
-Link: https://neon.com/docs/serverless/serverless-driver.md
+Lakebase Postgres is the database at the core of Neon. It runs on the lakebase architecture — OLTP built directly on cloud object storage — which decouples storage from compute to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres.
 
-### Neon JS SDK
+It is the same database whether you reach it through Neon or through Databricks; this skill covers the Neon access path.
 
-Use this for combined Neon Auth + Data API workflows with PostgREST-style querying and typed client setup.
+## Setup Flow
 
-Link: https://neon.com/docs/reference/javascript-sdk.md
+### 1. Select the organization and project
 
-## Developer Tools
+Use the CLI (default) or MCP server to list organizations and projects. Let the user select an existing project or create a new one. Check the `.neon` file for an existing linked project or branch.
 
-Use this for local development enablement with `npx -y neon@latest init --agent <agent-name>`, VSCode extension setup, and Neon MCP server configuration.
+### 2. Get the connection string
 
-| Tool             | URL                                             |
-| ---------------- | ----------------------------------------------- |
-| CLI Init Command | https://neon.com/docs/reference/cli-init.md     |
-| VSCode Extension | https://neon.com/docs/local/vscode-extension.md |
-| MCP Server       | https://neon.com/docs/ai/neon-mcp-server.md     |
-| Neon CLI         | https://neon.com/docs/reference/neon-cli.md     |
+Use the CLI (default), `neon env pull`, or the MCP server to get the connection string. Store it in `.env` as `DATABASE_URL`. Read the file first before modifying it, to avoid overwriting existing values.
 
-### Neon CLI
+#### When to use pooled vs direct connections
 
-Use this for terminal-first workflows, scripts, and CI/CD automation with `neon`.
+| Use case                                 | Connection type  |
+| ---------------------------------------- | ---------------- |
+| Web applications, serverless functions   | Pooled (-pooler) |
+| Schema migrations                        | Direct           |
+| pg_dump / pg_restore                     | Direct           |
+| Logical replication                      | Direct           |
+| Long-running analytics with temp tables  | Direct           |
+| Admin tasks needing SET or session state | Direct           |
+| LISTEN / NOTIFY                          | Direct           |
 
-Link: https://neon.com/docs/reference/neon-cli.md
+### 3. Pick the connection method and driver
 
-## Neon Admin API
+Always pair Neon with an ORM such as **Drizzle** for easy schema management and migrations. Refer to the connection methods guide to pick the correct driver based on how the runtime treats your code: https://neon.com/docs/connect/choose-connection.md.
 
-The Neon Admin API can be used to manage Neon resources programmatically. It is used behind the scenes by the Neon CLI and MCP server, but can also be used directly for more complex automation workflows or when embedding Neon in other applications.
+Recommendations:
 
-### Neon REST API
+- Drizzle as ORM (see https://neon.com/docs/guides/drizzle.md)
+- On Vercel, use `node-postgres` (`npm install pg`) with Vercel Fluid compute and `import { attachDatabasePool } from "@vercel/functions";`
+- On Cloudflare, use `node-postgres` with Cloudflare Hyperdrive
+- On Neon Functions, use `node-postgres`, as the functions are long-running and reuse the pool across requests.
+- Use the `@neondatabase/serverless` driver for serverless and edge environments (for example, when using Netlify) — HTTP transport for one-shot queries, WebSocket for transaction support. Link: https://neon.com/docs/serverless/serverless-driver.md
 
-Use this for direct HTTP automation, endpoint-level control, API key auth, rate-limit handling, and operation polling.
+### 4. Set up the schema
 
-Link: https://neon.com/docs/reference/api-reference.md
+Manage schemas and migrations as code. Avoid running ad hoc schema migrations against your database, since they're hard to manage.
 
-### Neon TypeScript SDK
-
-Use this when implementing typed programmatic control of Neon resources in TypeScript via `@neon/sdk` (the fetch-based, zero-dependency successor to `@neondatabase/api-client`).
-
-Link: https://neon.com/docs/reference/typescript-sdk.md
-
-### Neon Python SDK
-
-Use this when implementing programmatic Neon management in Python with the `neon-api` package.
-
-Link: https://neon.com/docs/reference/python-sdk.md
-
-## Neon Auth
-
-Use this for managed user authentication setup, UI components, auth methods, and Neon Auth integration pitfalls in Next.js and React apps.
-
-Link: https://neon.com/docs/auth/overview.md
-
-Neon Auth is also embedded in the Neon JS SDK. Depending on your use case, you may want to use the Neon JS SDK instead of Neon Auth alone. See https://neon.com/docs/connect/choose-connection.md for more details.
-
-## Neon Infrastructure as Code (`neon.ts`)
-
-`neon.ts` is Neon's branch config and infrastructure-as-code file: declare which services your branches have, get type-safe env vars, and program per-branch compute — all in TypeScript (see the `neon` skill for the full reference). Postgres always exists on every branch, so you never declare the database itself; what you codify here is the Postgres-adjacent surface — Neon Auth, the Data API, and per-branch compute settings (autoscaling and scale-to-zero).
-
-Add it with `@neon/config`:
-
-```bash
-npm i @neon/config
-```
-
-```typescript
-// neon.ts
-import { defineConfig } from "@neon/config/v1";
-
-export default defineConfig({
-  auth: true, // Neon Auth (adds NEON_AUTH_* env vars)
-  dataApi: true, // Data API (adds NEON_DATA_API_URL); requires auth: true (or an external IdP)
-  // Postgres exists on every branch; tune its compute per branch:
-  branch: (branch) => {
-    if (branch.exists) return {}; // leave existing branches untouched
-    if (branch.isDefault) return { protected: true }; // prod keeps default compute
-    return {
-      ttl: "7d", // non-prod branches auto-expire (max 30d)
-      postgres: {
-        computeSettings: {
-          autoscalingLimitMinCu: 0.25, // scale to zero
-          autoscalingLimitMaxCu: 1, // keep dev/preview cheap
-          suspendTimeout: "5m",
-        },
-      },
-    };
-  },
-});
-```
-
-Reconcile the declaration from the CLI — the Neon equivalent of `terraform plan` / `apply`:
-
-```bash
-neon config status   # print the branch's live config
-neon config plan     # dry-run diff of what apply would change
-neon config apply    # provision the declared services / settings
-neon deploy          # alias for `neon config apply`
-```
-
-Because `neon checkout` applies the policy as it **creates** a branch, a fresh branch comes up with these compute settings (and Auth / Data API) already in place. Checking out an _existing_ branch never reconciles it — run `neon deploy` to apply changes.
-
-Since `neon.ts` is TypeScript, invalid combinations fail to compile with an actionable message: the Data API verifies requests with Neon Auth by default, so `dataApi: true` without `auth: true` is a type error (the fix — `auth: true`, or `authProvider: 'external'` with a `jwksUrl` — is in the message). See the `neon` skill's type-safe config note.
-
-Read the resulting env back, typed and validated against the policy, with `parseEnv` from `@neon/env`:
-
-```typescript
-import { parseEnv } from "@neon/env";
-import config from "./neon";
-
-const env = parseEnv(config);
-env.postgres.databaseUrl; // typed; enabling auth / dataApi above surfaces env.auth / env.dataApi
-```
+If you're using an ORM, follow your ORM's best practices to manage schemas and migrations. For example, if using Drizzle, only use Drizzle for schema and migration management unless instructed otherwise.
 
 ## Branching
 
@@ -292,18 +82,18 @@ Key points:
 
 Link: https://neon.com/docs/introduction/branching.md
 
-For detailed branch creation workflows (normal vs schema-only branches, reset-from-parent, CLI/MCP selection), use the `neon-postgres-branches` skill if available
-
-Or fetch the full branching skill from the following URL:
-
-https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md
-
-If this skill is not installed you can use the following command to install it:
+For detailed branch creation workflows (normal vs schema-only branches, reset-from-parent, CLI/MCP selection), use the `neon-postgres-branches` skill. If it isn't installed, fetch it from https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md or install it with:
 
 ```bash
 npx skills add neondatabase/agent-skills --skill neon-postgres-branches
 ```
 
+## Migrations
+
+Test a migration on a branch of production, against production-like data, before applying it to production.
+
+Use a **direct (non-pooled)** connection string when you run the migration, not a pooled one. `neon connection-string` returns the direct string by default; make sure the hostname does not include the `-pooler` suffix.
+
 ## Autoscaling
 
 Use this when the user needs compute to scale automatically with workload and wants guidance on CU sizing and runtime behavior.
@@ -316,7 +106,7 @@ Use this when optimizing idle costs and discussing suspend/resume behavior, incl
 
 Key points:
 
-- Idle computes suspend automatically (default 5 minutes, configurable) (unless disabled - launch & scale plan only)
+- Idle computes suspend automatically after a default of 5 minutes; the timeout is configurable, and suspension can only be disabled on the Launch and Scale plans.
 - First query after suspend typically has a cold-start penalty (around hundreds of ms)
 - Storage remains active while compute is suspended.
 
@@ -374,3 +164,14 @@ Key points:
 - Useful for replicating to/from external Postgres systems.
 
 Link: https://neon.com/docs/guides/logical-replication-guide.md
+
+## Gotchas
+
+### Pooled vs direct connections: use the direct URL for migrations, dumps, and replication
+
+Neon gives you two connection strings for the same database: a **pooled** one (hostname with the `-pooler` suffix) and a **direct/unpooled** one (no `-pooler` suffix). `neon env pull` writes them as `DATABASE_URL` and `DATABASE_URL_UNPOOLED`. The pooled connection routes through PgBouncer in transaction mode, which doesn't support session-level operations. Choose the right one:
+
+- **Pooled (`DATABASE_URL`)** — your application's normal query traffic, especially serverless and connection-per-request workloads.
+- **Direct (`DATABASE_URL_UNPOOLED`)** — schema migrations (Prisma Migrate, Drizzle Kit, Alembic, and others), `pg_dump` / `pg_restore`, logical replication, `LISTEN`/`NOTIFY`, and anything relying on `SET` or other session state.
+
+Running migrations, dumps, or replication over the pooled connection can fail, and never in a way that names pooling: `prepared statement "s0" already exists` from Prisma Migrate, a `SET search_path` that doesn't persist past its own transaction so the next query reports `relation "mytable" does not exist`, or a write intermittently hitting a read-only transaction (`SQLSTATE 25006`) that a pooled backend inherited from an earlier client. Migration tools generally take both strings at once — Prisma's `directUrl` alongside `url` — so point that at the direct one rather than swapping `DATABASE_URL` and losing pooling for the application. See https://neon.com/docs/connect/connection-pooling.md.

package/dist/global-skills/neon-postgres-branches/SKILL.md

@@ -4,15 +4,27 @@ description: >-
   Choose and create the right Neon branch type for testing and development.
   Use when users ask about Neon branching, migration testing with real data,
   isolated test environments, schema-only branch workflows for sensitive data,
-  or branch creation via Neon CLI or Neon MCP. Triggers include "Neon branch",
-  "test migrations safely", "branch production data", "schema-only branch",
-  "reset branch" and "sensitive data testing".
+  resetting a branch from its parent, branch expiration and CI/CD branch
+  lifecycles, or branch creation via Neon CLI or Neon MCP. Triggers include
+  "Neon branch", "test migrations safely", "branch production data",
+  "schema-only branch", "reset branch", "branch per PR" and
+  "sensitive data testing".
+metadata:
+  parent: neon
+  source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres-branches
 ---
 
-# Neon Postgres Branching
+**FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
 
-The outcome of this skill should be a created Neon branch (or a clear, actionable next step if creation cannot proceed).
-Choose the correct branch type, then execute branch creation via MCP or CLI.
+If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
+
+```bash
+npx skills add neondatabase/agent-skills --skill neon
+```
+
+# Lakebase Postgres Branching
+
+**Outcome:** a created Neon branch — or a clear, actionable next step if creation cannot proceed. Choose the correct branch type, then execute branch creation with the CLI (or MCP where the CLI isn't usable).
 
 - **Normal branch** for realistic migration and query testing with real data.
 - **Schema-only branch (Beta)** for sensitive data workflows where structure is needed without copying rows.
@@ -29,21 +41,20 @@ If the request is ambiguous, ask one clarifying question:
 
 ## Tool Selection: CLI or MCP
 
-Always support both Neon CLI and Neon MCP server. Prefer the tool the user already has installed and authenticated.
+Support both the Neon CLI and the Neon MCP server, but **default to the CLI**. Use MCP only when the CLI is unavailable or blocked in your environment, cannot be authenticated, or the user explicitly asks for MCP.
 
-MCP link: https://neon.com/docs/ai/neon-mcp-server.md
-CLI link: https://neon.com/docs/reference/cli-quickstart
+- CLI link: https://neon.com/docs/cli/quickstart.md
+- MCP link: https://neon.com/docs/ai/neon-mcp-server.md
 
 ### Selection order
 
-1. Check MCP first in MCP-enabled environments:
-   - If Neon MCP tools are available and authenticated (for example, listing projects works), use MCP.
-2. If MCP is unavailable or not authenticated, check CLI:
-   - Run `neon --version` to confirm CLI is installed.
+1. Check the CLI first:
+   - Run `neon --version` to confirm the CLI is installed.
    - Run `neon projects list` to confirm auth/context.
-3. If CLI is missing, direct installation via quickstart.
-4. If CLI is installed but not authenticated, guide the user through `neon auth` (or API key auth), then continue.
-5. If both MCP and CLI paths are unsuccessful, use the Neon REST API:
+2. If the CLI is missing, direct installation via quickstart.
+3. If the CLI is installed but not authenticated, guide the user through `neon auth` (or API key auth), then continue.
+4. Switch to MCP when the CLI cannot be used — no CLI access in the environment, execution blocked, or authentication not possible — or when the user explicitly asks for MCP. Confirm Neon MCP tools are available and authenticated (for example, listing projects works), then follow the MCP branch flow below.
+5. If neither path is successful, use the Neon REST API:
    - https://neon.com/docs/guides/branching-neon-api.md
 
 ### MCP branch flow
@@ -62,22 +73,22 @@ Link: https://neon.com/docs/introduction/branching.md
 
 ### Steps
 
-1. Use MCP if already available/authenticated; otherwise verify CLI with `neon --version`.
+1. Settle the tool path first (see [Selection order](#selection-order)): verify the CLI with `neon --version`, and fall back to MCP only if the CLI isn't usable.
 2. Ensure project context is set (`neon set-context --project-id <your-project-id>`) or include `--project-id` on commands.
-3. Create branch:
+3. Create the branch:
 
-```bash
-neon branches create \
-  --name <branch-name> \
-  --parent <parent-branch-id-or-name> \
-  --expires-at 2026-12-15T18:02:16Z
-```
+   ```bash
+   neon branches create \
+     --name <branch-name> \
+     --parent <parent-branch-id-or-name> \
+     --expires-at 2026-12-15T18:02:16Z
+   ```
 
 4. Optionally fetch a connection string for the new branch:
 
-```bash
-neon connection-string <branch-name>
-```
+   ```bash
+   neon connection-string <branch-name>
+   ```
 
 ## Create a Schema-Only Branch (Beta, Sensitive Data)
 
@@ -87,27 +98,27 @@ Link: https://neon.com/docs/guides/branching-schema-only.md
 
 ### Steps
 
-1. Use MCP if already available/authenticated; otherwise verify CLI with `neon --version`.
-2. Create schema-only branch:
+1. Settle the tool path first (see [Selection order](#selection-order)): verify the CLI with `neon --version`, and fall back to MCP only if the CLI isn't usable.
+2. Create the schema-only branch:
 
-```bash
-neon branches create \
-  --name <schema-only-branch-name> \
-  --parent <parent-branch-id-or-name> \
-  --schema-only \
-  --expires-at 2026-12-15T18:02:16Z
-```
+   ```bash
+   neon branches create \
+     --name <schema-only-branch-name> \
+     --parent <parent-branch-id-or-name> \
+     --schema-only \
+     --expires-at 2026-12-15T18:02:16Z
+   ```
 
-If multiple projects exist, include:
+   If multiple projects exist, include `--project-id`:
 
-```bash
-neon branches create \
-  --name <schema-only-branch-name> \
-  --parent <parent-branch-id-or-name> \
-  --schema-only \
-  --project-id <your-project-id> \
-  --expires-at 2026-12-15T18:02:16Z
-```
+   ```bash
+   neon branches create \
+     --name <schema-only-branch-name> \
+     --parent <parent-branch-id-or-name> \
+     --schema-only \
+     --project-id <your-project-id> \
+     --expires-at 2026-12-15T18:02:16Z
+   ```
 
 ### Beta Support Guidance (Mandatory)
 
@@ -118,7 +129,7 @@ Schema-only branching is in Beta. If users report unexpected behavior, errors, o
 2. Recommend opening a support conversation in the Neon Discord:
    - https://discord.gg/92vNTzKDGp
 
-## Reset from parent
+## Reset from Parent
 
 Use this when a child branch has drifted and the user wants a clean refresh from the parent branch's latest schema and data.
 
@@ -149,7 +160,7 @@ Link: https://neon.com/docs/guides/reset-from-parent.md
 neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name>
 ```
 
-If project context is not already set, include project ID:
+If project context is not already set, include the project ID:
 
 ```bash
 neon branches reset <id|name> --parent --preserve-under-name <backup-branch-name> --project-id <project-id>
@@ -253,7 +264,7 @@ Common CI/CD use cases for Neon branches:
 
 1. Recommend a normal branch and explain why.
 2. Share docs link: https://neon.com/docs/introduction/branching
-3. Check the available/authenticated tool path first (MCP, otherwise CLI with `neon --version`).
+3. Check the tool path first (CLI with `neon --version`; MCP only if the CLI isn't usable).
 4. Provide commands:
    - `neon branches create --name migration-test --parent main --expires-at 2026-12-15T18:02:16Z`
    - `neon connection-string migration-test`
@@ -266,14 +277,14 @@ Common CI/CD use cases for Neon branches:
 
 1. Recommend schema-only branch and explain why.
 2. Share docs link: https://neon.com/docs/guides/branching-schema-only
-3. Check the available/authenticated tool path first (MCP, otherwise CLI with `neon --version`).
+3. Check the tool path first (CLI with `neon --version`; MCP only if the CLI isn't usable).
 4. Provide command:
    - `neon branches create --name compliance-dev --parent main --schema-only --project-id <your-project-id> --expires-at 2026-12-15T18:02:16Z`
 5. Mention Beta support path:
    - https://console.neon.tech/app/projects?modal=feedback
    - https://discord.gg/92vNTzKDGp
 
-## Further reading
+## Further Reading
 
 - https://neon.com/docs/guides/branch-expiration.md
 - https://neon.com/docs/guides/neon-github-integration.md

package/dist/global-skills/neon-postgres-egress-optimizer/SKILL.md

@@ -9,12 +9,25 @@ description: >-
   from their database to their application. Also use when reviewing query
   patterns for cost efficiency, even if the user doesn't explicitly mention
   egress or data transfer.
+metadata:
+  parent: neon
+  source: https://github.com/neondatabase/agent-skills/tree/main/skills/neon-postgres-egress-optimizer
 ---
 
+**FIRST**: Use the parent `neon` skill for a Neon overview, getting started with Neon, Neon development best practices, and more.
+
+If the `neon` skill is not installed, fetch it from https://neon.com/docs/ai/skills/neon/SKILL.md or install it with:
+
+```bash
+npx skills add neondatabase/agent-skills --skill neon
+```
+
 # Postgres Egress Optimizer
 
 Guide the user through diagnosing and fixing application-side query patterns that cause excessive data transfer (egress) from their Postgres database. Most high egress bills come from the application fetching more data than it uses.
 
+Work the four steps in order: **diagnose** which queries transfer the most data, **analyze** the codebase behind them, **fix** the anti-patterns, then **verify** nothing broke and the transfer actually dropped.
+
 ## Step 1: Diagnose
 
 Identify which queries transfer the most data. The primary tool is the `pg_stat_statements` extension.
@@ -31,7 +44,7 @@ If this errors, the extension needs to be created:
 CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
 ```
 
-On Neon, it is available by default but may need this CREATE EXTENSION step.
+On Neon the extension is available by default, but it may still need this CREATE EXTENSION step.
 
 ### Handle empty stats
 
@@ -96,7 +109,7 @@ Rank findings by estimated egress impact:
 - **Extreme call frequency** on even small queries adds up. A query called 50,000 times/day returning 10 rows each = 500,000 rows/day.
 - **Cross-reference with the schema** to identify which columns are wide. Look for JSONB, TEXT, BYTEA, and large VARCHAR columns.
 
-## Step 2: Analyze codebase
+## Step 2: Analyze the Codebase
 
 For each query identified in Step 1, or for each database query in the codebase if no stats are available, check:
 
@@ -114,6 +127,8 @@ Apply the appropriate fix for each problem found. Below are the most common egre
 
 **Problem:** The query fetches all columns but the application only uses a few. Large columns (JSONB blobs, TEXT fields) get transferred over the wire and discarded.
 
+**Fix:** Name only the columns the response needs.
+
 **Before:**
 
 ```sql
@@ -132,6 +147,8 @@ SELECT id, name, price, image_urls FROM products;
 
 This is easy to miss because the application may work fine with small datasets. But at scale, an unpaginated endpoint returning 10,000 rows with even moderate column widths can transfer hundreds of megabytes per day.
 
+**Fix:** Bound the result set with `ORDER BY` plus `LIMIT`/`OFFSET`.
+
 **Before:**
 
 ```sql
@@ -181,6 +198,8 @@ GROUP BY p.category_id;
 
 This is distinct from the SELECT \* problem. Even if you select only needed columns, a JOIN still repeats the parent data for every child row. The fix is structural: avoid the join entirely.
 
+**Fix:** Split the join into two queries, one per table.
+
 **Before:**
 
 ```sql
@@ -241,7 +260,7 @@ neon config apply   # apply to the current branch (neon deploy is an alias)
 
 This is complementary, not a substitute: query-pattern fixes are what actually reduce egress charges, while these settings keep non-production compute and storage from quietly inflating the same bill. Because `neon checkout` applies the policy when it creates a branch, new dev/preview branches inherit the cheap profile automatically.
 
-## Further reading
+## Further Reading
 
 - https://neon.com/docs/introduction/network-transfer.md
 - https://neon.com/docs/introduction/cost-optimization.md