* Update the Neon skills to match current Neon behavior
A pass over the Neon skills against the docs and live Neon in us-east-2 turned up
a few details to bring up to date.
AI Gateway: use current model IDs (gemini-3-flash), lean on /v1/models and
models.dev instead of a fixed provider list since the catalog shifts, and clarify
that the native Anthropic and Gemini dialects take the SDK base URL (/anthropic,
/gemini) with the SDK appending the rest of the path.
Functions: the invocation URL's compute cell is per-branch, so show it as a
placeholder instead of a hardcoded value, and note that waitUntil is functional
(a no-op only off-platform), not a stub.
Logs: a branch that cannot serve logs returns a typed 404 (reason
telemetry_not_enabled or branch_not_found), and severity filtering uses
--severity-text as an exact, case-sensitive match because --minimum-severity is
unsupported by the branch log backend.
Also remove the outdated new-projects-only note from the beta services.
Co-authored-by: Isaac
* Update plugins/neon-postgres/skills/neon-functions/SKILL.md
Co-authored-by: Andre Landgraf <andre.timo.landgraf@gmail.com>
* Clarify `waitUntil` usage and behavior
---------
Co-authored-by: Andre Landgraf <andre.timo.landgraf@gmail.com>
* Recommend a pg pool error listener on Neon Functions.
Idle disconnects from scale-to-zero and pooler reclaim are uncaughtExceptions unless the pool has an error listener.
* Define isIdleDisconnect in the LISTEN/NOTIFY pool snippet.
Copying only that block still has to attach a working error listener.
* Listen for idle errors on the dedicated LISTEN Client too.
A Client without an error listener is the same uncaughtException as an unlistened pool.
* Note that a LISTEN error listener leaves the feed down until isolate restart.
Crash-based reconnect was the old recovery; swallowing the error keeps the isolate and the dead listener.
* Recommend attachDatabasePool for idle pg pool errors.
* Remove redundant comments from function examples.
* Require @neon/functions 0.8.0 and restore the reconnect handler comments.
* Warn that attachDatabasePool would silence a dead LISTEN feed.
* Add a Kimi Code plugin manifest and release 1.1.2
Kimi Code reads its own kimi.plugin.json rather than the portable
plugin.json, and it does not read mcp.json, so the manifest declares the
Neon MCP Server inline. It points at skills/ in place, so like the root
Agent Plugins package it needs no vendoring.
Wiring it into sync-versions.mjs keeps its version generated from
package.json like every other manifest, and adding it to the workflow's
path filter keeps a Kimi-only edit from skipping validate:versions. The
bump to 1.1.2 releases the accumulated skill changes along with it.
* Tell Kimi users to run /new, not /reload, after installing
Adds an Observability section to the neon overview covering branch logs,
with source-specific sections in neon-functions and neon-object-storage.
Logs cover Neon Functions and Object Storage only; Postgres computes and
the AI Gateway emit nothing yet, and --source pg_endpoint is accepted but
comes back empty. Availability is region gating, not enrollment.
Documents the three silent failure modes an agent would otherwise report
as "you have no logs": the wrong branch, a source that emits nothing, and
--logql selecting on entity_type rather than source. Covers the CLI, the
MCP read tools, the @neon/sdk shape including its result envelope, and the
Loki-compatible read API for direct HTTP calls.
* Add migration guidance and a pooled-connection gotcha to neon-postgres
Support sees migrations, dumps, and logical replication run over the pooled
connection string, which PgBouncer's transaction mode cannot serve. The
neon-postgres skill held the pooled-vs-direct table but never named the failure
modes or said to test a migration on a branch first.
* Correct the pooling mechanics and attribute the env var to neon env pull
Transaction-mode pooling returns the backend after each transaction, so session
state persists within a transaction and is lost in the next one. Cite the
search_path example the docs use instead of the Prisma prepared-statement error,
which PgBouncer 1.22's protocol-level support makes ambiguous. DATABASE_URL_UNPOOLED
is what neon env pull writes, not an inherent property of the connection string.
* Say session state is not preserved for a client, not that it is destroyed
The backend may still hold the state; what transaction pooling removes is the
guarantee that the same client gets that backend back.
* Add a migration-specific gotcha naming the tools and the errors they emit
An agent that has just hit "prepared statement s0 already exists" or an
intermittent SQLSTATE 25006 has no reason to connect either to pooling. Name the
symptom, the tool, and the fix so the entry is reachable from the failure.
* Match the trigger to what a user says and the heading to the error they see
"Neon schema migrations" is a product noun nobody types; the prompt is "run my
migration". The gotcha heading named the cause, so an agent scanning headings
after a failure had nothing to match against, unlike the neon skill's
"invalid domain" precedent.
* Adopt Daniel Price's wording from #82 for both additions
His phrasing is the one to keep — the pooled/direct decision as two labelled
bullets, and the failure modes in one sentence. That collapses the two Gotchas
entries into his single one, whose heading already leads with migrations.
* Make SQLSTATE 25006 greppable and keep the directUrl fix
The other two errors appear as literal strings an agent can match; 25006 was
described in prose only, and it is the one that reads as infrastructure
flakiness. Restore the directUrl pointer too — without it the plausible fix is
swapping DATABASE_URL, which costs the application its pooling. Drops the
duplicated reason and tool list from Migrations, leaving one copy in the gotcha.
Clients implementing the Agent Plugins v1 specification look for a
manifest at the plugin root, so today this repo is only installable
through the Claude and Cursor packaging under plugins/. Adding a root
plugin.json and mcp.json makes the repository itself a conforming
portable package that reads skills/ in place, with no vendoring.
The v1 manifest schema is closed, so the client fields the existing
manifests carry (skills, mcpServers, logo, displayName) cannot appear
at the top level and MCP configuration moves to its own file. The root
mcp.json therefore spells the transport "streamable-http" while
plugins/neon-postgres/mcp.json keeps Claude and Cursor's "http" for the
same endpoint; the two files are intentionally not copies.
Apart from the version bump below, the packaging under plugins/ is
untouched, so existing Claude and Cursor installs behave as before.
validate-agent-plugin.mjs gates the new files in CI, checking the closed
manifest field set, MCP transport and containment rules, and skill
discovery. It shares the frontmatter semantics skills-ref uses so the
two validators cannot disagree about the same SKILL.md. Containment is
checked all the way down a skill rather than only at its root, since a
nested symlink escaping the repo would otherwise ship to a v1 client.
A link that will not resolve is reported rather than passing as
contained on the strength of a failed realpath.
Releases this as 1.1.1, and makes package.json the single source of
truth for that number. The root manifest added a sixth place the
version is declared and nothing kept them in step, so a bump that
missed one could publish a catalog entry advertising a different
version than the plugin it installs. sync-versions.mjs generates all
six from package.json, the pre-commit hook runs it the way it already
runs sync-plugin-skills.mjs, and validate:versions is that same script
in --check mode so CI still catches a hand-edited manifest. A release
is now one edit: bump package.json and commit.
The rewrite is a surgical text replacement rather than a JSON
re-serialize, so every manifest keeps its formatting. Nothing is written
until every file re-parses to exactly the expected result.
package-lock.json declares the version twice as well, but it repeats
"version" for every dependency, which makes a text rewrite unsafe; npm
owns that file, so the script checks it and leaves it alone.
The check refuses to pass quietly on a file it did not understand: one
that exists but declares no version is an error, and so is one that
cannot be read, since reporting "in sync" for a file never opened would
defeat the point. Each failure carries its own remedy, and the
sync:versions hint is withheld from the two that command cannot repair.
The hook stages only the manifests sync-versions.mjs reports rewriting,
which it prints to stdout. Staging all six unconditionally would sweep
an in-progress edit to a description or keyword list into an unrelated
commit, since those files are hand-authored apart from the version
field. The vendored skills are still staged a directory at a time so a
deletion is staged too, which is safe because every file under
plugins/*/skills is generated. That loop skips a directory that does
not exist: an unmatched glob is passed through literally, and git add
would abort the commit with a pathspec error the first time a plugin
ships without one of the two client packaging formats.
Also adds the marketplace catalogs to the workflow path filters; editing
one previously skipped CI even though validate:plugins reads them.
It said the /v1beta belongs to Google rather than Neon, which frames Gemini as an
exception. It is not: every native dialect is /<provider>/<that provider's own API
version>, so openai/v1, anthropic/v1 and gemini/v1beta are the same shape. The version
differs because the providers version differently.
Explaining it invited the reading it was meant to prevent — that something about
Gemini is irregular. The list is uniform, so it can just be read.
WebSockets on Neon Functions are now served by calling `upgradeWebSocket(request)`
from `@neon/functions` inside the ordinary `fetch` handler and returning the
response it produces. The skill documents that and only that.
const { socket, response } = upgradeWebSocket(req);
socket.addEventListener("message", (event) => socket.send(event.data));
return response;
`socket` is a standard WHATWG `WebSocket`. There is one entrypoint, no protocol
library to install, and refusing a handshake is returning a `Response` with a
status -- so auth is an ordinary early return rather than bytes written to a raw
socket.
Hono needs nothing special now: `upgradeWebSocket` takes a `Request`, so a route
calls it with `c.req.raw` and returns the response, with auth as normal
middleware. The `createNeonWebSocket` adapter reference is deleted -- it existed
only to bridge Hono's helper onto a raw Node handshake, and there is no raw
handshake to bridge to.
The heartbeat guidance changes with it. The standard `WebSocket` interface has no
`ping()`, so the server-side keepalive is an application-level message the client
ignores, not a protocol ping frame.
Fan-out, reconnect, and the cross-isolate guidance are unchanged in substance;
the snippets are renamed off `ws` since nothing is named after the library any
more.
* neon-ai-gateway: prefer the short dialect paths
Every dialect is reachable at a short and a long path. The docs lead with the short
one and @neondatabase/ai-sdk-provider uses it, but this skill still told agents to
point google-genai at /ai-gateway/gemini and described that prefix as where Gemini
"is still served", which reads as if it were the only option.
Both forms verified against a live branch. The short Gemini path keeps its gemini
segment under /v1 rather than being a bare /v1 route, and a bare /gemini/v1beta is not
served at all, so that exception is now stated instead of implied.
Also corrects the Anthropic base URL: the SDK appends /v1/messages itself, so the base
should be /anthropic, not /anthropic/v1.
* Sync the plugin mirror after the skill edit
plugins/neon-postgres/skills/ is a generated copy of skills/, checked by
validate:plugin-skills. Editing the source alone left the two out of sync and turned
CI red.
* Stop mentioning the /ai-gateway path form
The short paths are the source of truth. The skill described the longer
/ai-gateway/<dialect>/... form as an equivalent alternative, which invites an agent to
write it, and described the Gemini route as "the short form", which implies another
form exists. Neither is mentioned now.
The long form still resolves on the gateway and is not deprecated, so nothing breaks
for anyone already using it — it simply is not something we document.
* Move the Gemini route to /gemini/v1beta
The customer-facing Gemini path drops its /v1 prefix so every native dialect is
provider-prefixed at the root, matching /openai/v1 and /anthropic/v1. Google's own
/v1beta stays in the path, so the route reads /gemini/v1beta/models/{model}:action and
the google-genai base URL becomes ${NEON_AI_GATEWAY_BASE_URL}/gemini.
Lands ahead of the gateway: the new path still returns 404 at the time of this commit
and the /v1/gemini form is what serves today. Shipping the docs first is deliberate —
see neondatabase/website#5456, which this follows.
The plugin already ships skills for Object Storage, Functions, and the AI
Gateway, but the description only advertised projects, databases, and
branches, so installers had no way to know the rest was there. Name the
primitives instead, and add "lakebase" as a keyword/tag so the plugin is
discoverable under the database's current name.
Drop the hardcoded skill list from the README's plugin section as well; it
had already drifted to three of the eight vendored skills, and omitting the
names keeps it accurate as skills come and go.
The Sentry reference landed in #56 describing NEON_BRANCH as the branch
ID. It is the name, matching what SKILL.md already documented, so
PRODUCTION_BRANCH is a branch name too.
Both the Cursor and Claude Code marketplaces gate plugin updates on the
manifest version field: installed users only re-pull when it changes. The
version had been frozen at 1.0.0 across 14+ commits to skills/, so neither
Cursor nor Claude users were receiving the updated skills.
Bump all five version fields in lockstep so both platforms ship the current
skills as 1.1.0:
- .cursor-plugin/marketplace.json (metadata.version)
- plugins/neon-postgres/.cursor-plugin/plugin.json (version)
- .claude-plugin/marketplace.json (metadata.version, plugins[].version)
- plugins/neon-postgres/.claude-plugin/plugin.json (version)
Co-authored-by: Isaac
* docs(neon-functions): refresh Sentry reference with verified setup
Rewrites references/sentry.md from a deployment tested end to end:
errors, structured logs, and gen_ai agent traces all verified live.
Fixes the NEON_BRANCH description (env var holds the branch ID, not
the name).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Move reasoning to prose, lean code samples, add env var table
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Require @sentry/node >=10.67.0 instead of the OTel global workaround
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* Sync vendored plugin copy of the Sentry reference
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: Andre Landgraf <andre.timo.landgraf@gmail.com>
Lakebase Postgres is reachable through Neon or through Databricks, so a claim
that only holds on the Neon path has to name it. Three strings named no access
path and travel detached from any heading that would supply one:
- the skills.sh Database Workflows blurb, where "projects" is a Neon concept
- the README blurb for neon-postgres, which indexes neon.com/docs specifically
- the neon skill's pointer to neon-postgres-agent-platforms, about operating at
fleet scale across Neon orgs
Left bare where the sentence already says Neon, and where the claim holds on
both access paths — including the "# Lakebase Postgres" heading, whose next
paragraph spells out both paths.
"Neon and Lakebase Postgres" coordinates the brand with one of its own
components as a peer. The old copy had no such problem, because "Neon
Serverless Postgres" was a single product name — so the replacement for a
brand-scope string is "Neon" alone, not brand plus component.
Twelve strings: both marketplace manifests, package.json, the AGENTS.md
overview, the skills.sh Core group, and the seven parent-skill pointer lines.
Database-scope copy is unchanged and still says Lakebase Postgres.
Dropping "Postgres" from the two manifest descriptions and package.json costs
nothing for discovery: both already carry it in tags and keywords.
The database product is Lakebase Postgres, reached either through Neon or
through Databricks. Public copy in this repo still called it "Neon Serverless
Postgres" and "Neon Postgres", and called Neon itself "the Neon platform" — a
framing we cannot use, since Neon is not a platform separate from the Databricks
Platform.
Rewrites the prose in all eight skills, the README, both marketplace manifests,
skills.sh.json, and package.json. Adds a Terminology section to AGENTS.md so the
rules survive the next contributor, and records that skill and plugin ids are
identifiers rather than copy.
Skill ids, plugin ids, CLI flags, env var names, and code samples are unchanged.
Plugin copies under plugins/ regenerated with npm run sync:plugins.
* skills: clarity and structure pass across all eight skills
Reflow and restructure the skills for agent readability without changing any
guidance: front-load blocking preconditions (beta region, paid-plan gating) above
the setup steps that depend on them, order sections so cross-referenced material
is defined before it's cited, de-duplicate repeated env/parseEnv/skill-update
prose, convert human-facing phrasing to directives, and align frontmatter
descriptions with what each body actually covers.
* skills: make CLI the default tool path, fix functions deploy flags
The neon-postgres-branches skill told agents to check MCP first, which
contradicted the parent neon skill. MCP is now the documented fallback for
when the CLI is unavailable, blocked, unauthenticated, or the user asks for it.
Also corrects `neon functions deploy` to `--src` (verified against the CLI);
`--path`/`--entry` do not exist.
* skills(neon): lead with neon.ts, document verified env pull scoping
Moves Neon Infrastructure as Code above Branch-First Dev Flow so the config
layer is introduced before the loop that applies it, since neon.ts shapes what
env pull and checkout do and every sibling skill declares its service there.
To keep references resolving backward, `neon checkout` is now defined in Useful
CLI Commands (it was already cited there before being introduced), and "How
checkout composes with neon.ts" moves into the branch-first section.
Documents env pull's with/without-neon.ts behavior, verified against live Neon:
without neon.ts it pulls the vars of whatever services the branch has
provisioned; with neon.ts it pulls only declared services and fails fast on a
declared-but-missing one. The AI Gateway is the exception -- it needs no
provisioning, and is pulled only when declared.
* skills: condense env pull note, fix wrong AI Gateway pull claim
Trims the env pull behavior note in the neon skill to one sentence.
Corrects the ai-gateway skill, which claimed env pull writes the gateway vars
"on a branch that already has the gateway enabled". Verified against live Neon:
branch state alone never produces them -- neon.ts must declare preview.aiGateway.
* neon: refresh overview, architecture, and getting-started guidance
Rework the neon skill overview: clarify what Neon is and how a branch
works, describe recommended architectures (full-stack + Functions), and
rewrite the getting-started flow around `npx neon init`. Note the source
repos for each skill and add an "Updating Skills" section. Also fix
spelling/grammar and heading-case inconsistencies.
* skills: make neon the parent skill and slim its children
Platform-level guidance (docs discovery, getting started, neon.ts, SDKs) now
lives only in the neon skill, so neon-postgres can focus on Postgres itself
instead of restating it. Each child declares the relationship under metadata,
since skills-ref rejects unknown top-level frontmatter fields, and tells the
agent how to fetch or install the parent when it isn't already present.
* chore: sync vendored plugin skills with skills/
Regenerated after rebasing onto the plugin-vendoring change, so the copies
under plugins/neon-postgres/ match the reworked source skills.
The neon-postgres plugin exposed its skills via symlinks pointing outside
the plugin root (../../../skills/*). Cursor and Claude silently drop
out-of-root symlinks when installing a plugin from git, so the plugin
shipped its MCP server but none of its skills.
Replace the symlinks with committed real copies of every skill, generated
from the top-level skills/ source of truth by a one-way sync script
(scripts/sync-plugin-skills.mjs, driven by an in-script PLUGIN_SKILLS map;
"*" vendors all skills). A pre-commit hook wired via the prepare script
runs the sync automatically, and validate:plugin-skills (in validate:ci)
plus the cursor/claude plugin validators fail on drift or any in-plugin
symlink so this cannot silently regress.
Bundle the neon, neon-postgres, and neon-postgres-branches skills in the
Claude/Cursor neon-postgres plugin (drop neon-postgres-egress-optimizer)
and update plugin/README descriptions to match. Add CONTRIBUTING.md and an
AGENTS.md note pointing to the OpenAI (openai/plugins) and Grok
(xai-org/plugin-marketplace) marketplaces, where skill changes must be
mirrored via remote PRs.
Restructure plugin packaging into per-plugin folders so Claude and Cursor manifests, MCP config, and branding are co-located while shared skills are symlinked from top-level skills. Add plugin-manager guidance and CI validation scripts/workflow to prevent marketplace and manifest path regressions as additional plugins are added.
Co-authored-by: Cursor <cursoragent@cursor.com>
Philip Olson