neon 4.2.0 → 4.3.0

package/README.md

@@ -759,6 +759,38 @@ On a TTY the command asks for config location (global is the default), then agen
 
 The default mints an account-wide API key (or reuses the Bearer already configured for Neon at `https://mcp.neon.tech/mcp`) and writes it into each selected agent's config. That key reaches everything the account can, in every organization. Revoke it with `neon api-keys revoke <id>`. `--oauth` writes the URL with no `Authorization` header; the agent signs in on first use. `--project` writes into the project config (`.cursor/mcp.json` and similar). `--read-only` adds `?readonly=true`. `--project-id` adds `?projectId=`. `--category` adds `?category=` (repeatable or comma-separated: `projects`, `branches`, `schema`, `querying`, `neon_auth`, `data_api`, `observability`, `docs`). Those query params restrict which MCP tools the server exposes; they do not change what the minted key can do.
 
+## Install Neon agent skills (`skills`)
+
+`neon skills` installs Neon agent skills by running `npx skills add`. It does not call the Neon API. This command needs Node.js 22.20 or newer. The rest of the CLI supports Node.js 20.19 or newer.
+
+```bash
+# Interactive: this directory, then agents, then skills, then confirm.
+$ neon skills
+
+# Skip prompts. This directory, every detected agent, the default skills.
+$ neon skills -y
+
+$ neon skills -s neon -s neon-ai-gateway --agent cursor
+
+$ neon skills --agent cursor --agent claude-code
+
+# User-level skills.
+$ neon skills --global
+
+# Update installed skills in this directory.
+$ neon skills update
+$ neon skills update -y
+$ neon skills update --global -y
+```
+
+On a TTY the command asks which agents and which skills, then shows a summary to confirm. Detected agents start selected from project-folder markers such as `.cursor`. Default skills start selected. `neon-postgres-agent-platforms` is offered and starts unselected.
+
+`-y` skips those questions and installs the default skills. `--skill` / `-s` names specific skills and skips the skill picker. `--agent` and `--global` still apply. Without a TTY, pass `-y` or `--skill`. `--agent` alone is not enough.
+
+`--skill` names: `claimable-postgres`, `neon`, `neon-ai-gateway`, `neon-functions`, `neon-object-storage`, `neon-postgres`, `neon-postgres-branches`, `neon-postgres-egress-optimizer`, `neon-postgres-agent-platforms`.
+
+`--agent` names match `neon mcp`, minus agents that cannot install skills: `antigravity`, `cline`, `cline-cli`, `claude-code`, `claude-desktop`, `codex`, `cursor`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `opencode`, `vscode`, `windsurf`, `zed`. `mcporter` is a known MCP name that is then skipped.
+
 ## Snapshots (`snapshots`)
 
 `neon snapshots` (alias `neon snapshot`) manages **snapshots** — point-in-time backups of a branch that you can list, rename, expire, restore into a branch, or schedule automatically. Snapshots are a Beta Neon feature and were previously only available in the Console and REST API; this command group brings them to the CLI.
@@ -1139,6 +1171,7 @@ Id   Name      Project         Created At            Last Used At          Last
 | bootstrap                                                                  |                                                                                                              | Scaffold a project from a template |
 | init                                                                       |                                                                                                              | Set up a project for a coding agent |
 | mcp                                                                        |                                                                                                              | Install the Neon MCP server         |
+| skills                                                                     | `update`                                                                                                     | Install Neon agent skills           |
 | bucket                                                                     | `create`, `list`, `delete`, `object list`, `object get`, `object put`, `object delete` (incl. `--recursive`) | Manage buckets and their objects   |
 | [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                                              | Generate a completion script       |
 

package/dist/commands/auth.js

@@ -6,7 +6,7 @@ import { log } from "../log.js";
 import { getApiClient } from "../api.js";
 import { o as isOwnedCredentialPath } from "../_chunks/paths-g3DRqJiD.js";
 import { setAuthContext } from "../auth_context.js";
-import { isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isProfileCommand } from "../context.js";
+import { isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isProfileCommand, isSkillsCommand } from "../context.js";
 import { extendTokenSet } from "../utils/auth.js";
 import { auth, refreshToken } from "../auth.js";
 import { i as selectCredential, n as displacedProfileWarning, t as credentialInputs } from "../_chunks/auth_selection-Bx2NAgkk.js";
@@ -217,6 +217,7 @@ const ensureAuth = async (props) => {
 	if (isProfileCommand(props)) return;
 	if (isMcpOauth(props)) return;
 	if (props._[0] === "open") return;
+	if (isSkillsCommand(props)) return;
 	const isLocalDev = props._[0] === "dev";
 	const isBootstrap = props._[0] === "bootstrap";
 	const isInit = props._[0] === "init";

package/dist/commands/branches.js

@@ -24,8 +24,8 @@ const BRANCH_FIELDS = [
 	"name",
 	"id",
 	"current_state",
-	"created_at",
-	"expires_at"
+	"expires_at",
+	"created_at"
 ];
 const BRANCH_FIELDS_RESET = [
 	"name",

package/dist/commands/index.js

@@ -29,6 +29,7 @@ import { t as profile_exports } from "./profile.js";
 import { t as psql_exports } from "./psql.js";
 import { t as roles_exports } from "./roles.js";
 import { t as set_context_exports } from "./set_context.js";
+import { t as skills_exports } from "./skills.js";
 import { t as snapshots_exports } from "./snapshots.js";
 import { t as status_exports } from "./status.js";
 import { t as user_exports } from "./user.js";
@@ -60,6 +61,7 @@ var commands_default = [
 	open_exports,
 	init_exports,
 	mcp_exports,
+	skills_exports,
 	data_api_exports,
 	functions_exports,
 	dev_exports,

package/dist/commands/projects.js

@@ -12,6 +12,7 @@ import prompts from "prompts";
 //#region src/commands/projects.ts
 var projects_exports = /* @__PURE__ */ __exportAll({
 	PROJECT_FIELDS: () => PROJECT_FIELDS,
+	RECOVERABLE_PROJECT_FIELDS: () => RECOVERABLE_PROJECT_FIELDS,
 	REGIONS: () => REGIONS,
 	aliases: () => aliases,
 	builder: () => builder,
@@ -25,6 +26,14 @@ const PROJECT_FIELDS = [
 	"region_id",
 	"created_at"
 ];
+const RECOVERABLE_PROJECT_FIELDS = [
+	"id",
+	"name",
+	"recoverable_until",
+	"deleted_at",
+	"region_id",
+	"created_at"
+];
 const REGIONS = [
 	"aws-us-west-2",
 	"aws-ap-southeast-1",
@@ -185,11 +194,7 @@ const list = async (props) => {
 	const sharedProjects = props.orgId || props.recoverableOnly ? [] : await getList(props.apiClient.listSharedProjects);
 	const out = writer(props);
 	out.write(ownedProjects, {
-		fields: props.recoverableOnly ? [
-			...PROJECT_FIELDS,
-			"deleted_at",
-			"recoverable_until"
-		] : PROJECT_FIELDS,
+		fields: props.recoverableOnly ? RECOVERABLE_PROJECT_FIELDS : PROJECT_FIELDS,
 		title: "Projects",
 		emptyMessage: props.recoverableOnly ? "You don't have any recoverable projects." : "You don't have any projects yet. See how to create a new project:\n> neon projects create --help"
 	});
@@ -351,4 +356,4 @@ const onPromptState = (state) => {
 	}
 };
 //#endregion
-export { PROJECT_FIELDS, REGIONS, aliases, builder, command, describe, handler, projects_exports as t };
+export { PROJECT_FIELDS, RECOVERABLE_PROJECT_FIELDS, REGIONS, aliases, builder, command, describe, handler, projects_exports as t };

package/dist/commands/skills.js

@@ -0,0 +1,223 @@
+import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
+import { log } from "../log.js";
+import { writer } from "../writer.js";
+import { noPassthrough } from "../utils/flags.js";
+import { getAgentDisplayName } from "../mcp/agents.js";
+import "../init/agents.js";
+import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { mappedSkillsAgentNames } from "../skills/targets.js";
+import { confirmSkillsInstall, confirmSkillsUpdate } from "../skills/wizard.js";
+import { assertSkillsCanRun, resolveSkillsPlan } from "../skills/plan.js";
+import { assertSkillsNode, neonSkillsRetryCommand, neonSkillsUpdateRetryCommand, runSkillsCli, skillsAddArgs, skillsMetadata, skillsUpdateArgs, skillsUpdateDetail, skillsUpdateHadNothing } from "../skills/run.js";
+//#region src/commands/skills.ts
+var skills_exports = /* @__PURE__ */ __exportAll({
+	builder: () => builder,
+	command: () => command,
+	describe: () => describe,
+	handler: () => handler
+});
+const scopeLabel = (scope) => scope === "project" ? "this directory" : "user-level";
+const coerceAgents = (value) => {
+	if (value === void 0) return [];
+	const list = Array.isArray(value) ? value : [value];
+	if (list.length === 0) throw new Error("--agent needs a value. Pass one, or omit the flag entirely.");
+	return list.map((item) => {
+		if (typeof item !== "string" || item.trim() === "") throw new Error("--agent needs a value. Pass one, or omit the flag entirely.");
+		return item;
+	});
+};
+const coerceSkills = (value) => {
+	if (value === void 0) return [];
+	const list = Array.isArray(value) ? value : [value];
+	if (list.length === 0) throw new Error("--skill needs a value. Pass one, or omit the flag entirely.");
+	return list.map((item) => {
+		if (typeof item !== "string" || item.trim() === "") throw new Error("--skill needs a value. Pass one, or omit the flag entirely.");
+		return item;
+	});
+};
+const command = "skills";
+const describe = "Install Neon agent skills into coding agents";
+const builder = (argv) => argv.usage("$0 skills [command] [options]").command("update", "Update installed skills to the latest versions", (yargs) => yargs.usage("$0 skills update [options]").options({ global: {
+	type: "boolean",
+	default: false,
+	describe: "Update user-level skills (skills CLI -g). Default is this directory"
+} }).example("$0 skills update", "Interactive: confirm, then update skills in this directory").example("$0 skills update -y", "Update skills in this directory without prompting").example("$0 skills update --global -y", "Update user-level skills").strict().hide("agent").hide("skill").check((args) => {
+	noPassthrough("skills update")(args);
+	const agents = args.agent;
+	if (Array.isArray(agents) && agents.length > 0) throw new Error("neon skills update does not take --agent. It refreshes every installed skill in this directory (or --global).");
+	const skills = args.skill;
+	if (Array.isArray(skills) && skills.length > 0) throw new Error("neon skills update does not take --skill. It refreshes every installed skill in this directory (or --global).");
+	return true;
+}), (args) => updateHandler(args)).options({
+	yes: {
+		alias: "y",
+		type: "boolean",
+		default: false,
+		describe: "Skip prompts"
+	},
+	global: {
+		type: "boolean",
+		default: false,
+		describe: "Install user-level skills (skills CLI -g). Default is this directory"
+	},
+	agent: {
+		alias: "a",
+		type: "array",
+		string: true,
+		describe: "Coding agent to install into (repeatable). Skips the agent picker",
+		coerce: coerceAgents
+	},
+	skill: {
+		alias: "s",
+		type: "array",
+		string: true,
+		describe: "Skill to install (repeatable). Skips the skill picker",
+		coerce: coerceSkills
+	}
+}).example("$0 skills", "Interactive: this directory, agents, skills, then confirm").example("$0 skills -y", "This directory, detected agents, the default skills").example("$0 skills -s neon -s neon-ai-gateway --agent cursor", "Install named skills into specific agents").example("$0 skills --global", "Install user-level skills").strict().check(noPassthrough("skills"));
+const handler = async (props) => {
+	assertSkillsNode();
+	const cwd = process.cwd();
+	const yes = props.yes === true;
+	const interactive = canPickAgentsInteractively() && !yes;
+	const plan = await resolveSkillsPlan({
+		global: props.global === true,
+		agents: props.agent ?? [],
+		skills: props.skill ?? [],
+		yes,
+		cwd,
+		interactive
+	});
+	const mapped = mappedSkillsAgentNames(plan.agents);
+	for (const agent of plan.skipped) log.warning("Skipping %s: no skills mapping.", getAgentDisplayName(agent));
+	if (interactive) {
+		if (!await confirmSkillsInstall({
+			scope: plan.scope,
+			agents: plan.agents,
+			invocations: plan.invocations
+		})) {
+			log.info("Aborted. Nothing was written.");
+			return;
+		}
+	}
+	const metadata = skillsMetadata("skills");
+	const rows = [];
+	const failed = [];
+	const scope = scopeLabel(plan.scope);
+	for (const invocation of plan.invocations) {
+		const skills = invocation.skills.join(", ");
+		const args = skillsAddArgs({
+			source: invocation.source,
+			skills: invocation.skills,
+			agents: mapped,
+			global: plan.scope === "global",
+			metadata
+		});
+		try {
+			await runSkillsCli({
+				args,
+				cwd
+			});
+			rows.push({
+				scope,
+				skills,
+				agents: mapped.join(", "),
+				status: "installed"
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			rows.push({
+				scope,
+				skills,
+				agents: mapped.join(", "),
+				status: "failed",
+				error: "skills CLI failed"
+			});
+			failed.push({
+				label: skills,
+				message,
+				skills: invocation.skills
+			});
+		}
+	}
+	const out = writer(props);
+	out.write(rows, {
+		fields: [
+			"scope",
+			"skills",
+			"agents",
+			"status",
+			"error"
+		],
+		title: "Skills"
+	});
+	out.end();
+	if (failed.length === 0) {
+		log.info(plan.scope === "project" ? "Wrote skills in this directory." : "Wrote user-level skills.");
+		return;
+	}
+	const first = failed[0];
+	if (first === void 0) throw new Error("Failed to install Neon agent skills.");
+	const retry = neonSkillsRetryCommand({
+		skills: failed.flatMap((row) => row.skills),
+		agents: plan.agents,
+		global: plan.scope === "global"
+	});
+	if (first.message.includes("needs npx (Node.js)") || first.message.includes("needs Node.js")) throw new Error(first.message);
+	if (failed.length === rows.length) throw new Error(`${first.message}\nRetry with: ${retry}`);
+	throw new Error(`Failed to install Neon agent skills for: ${failed.map((row) => row.label).join(", ")}.\n${first.message}\nRetry with: ${retry}`);
+};
+const updateHandler = async (props) => {
+	assertSkillsNode();
+	const cwd = process.cwd();
+	const yes = props.yes === true;
+	const interactive = canPickAgentsInteractively() && !yes;
+	assertSkillsCanRun({
+		yes,
+		interactive,
+		action: "update"
+	});
+	const scope = props.global === true ? "global" : "project";
+	if (interactive) {
+		if (!await confirmSkillsUpdate({ scope })) {
+			log.info("Aborted. Nothing was written.");
+			return;
+		}
+	}
+	const rows = [];
+	const args = skillsUpdateArgs({ global: scope === "global" });
+	let failure;
+	try {
+		const result = await runSkillsCli({
+			args,
+			cwd
+		});
+		const output = `${result.stdout}\n${result.stderr}`;
+		rows.push({
+			scope: scopeLabel(scope),
+			status: skillsUpdateHadNothing(output) ? "none" : "updated",
+			detail: skillsUpdateDetail(output)
+		});
+	} catch (error) {
+		failure = error instanceof Error ? error.message : String(error);
+		rows.push({
+			scope: scopeLabel(scope),
+			status: "failed",
+			error: "skills CLI failed"
+		});
+	}
+	const out = writer(props);
+	out.write(rows, {
+		fields: [
+			"scope",
+			"status",
+			"detail",
+			"error"
+		],
+		title: "Skills"
+	});
+	out.end();
+	if (failure !== void 0) throw new Error(failure.includes("needs npx (Node.js)") || failure.includes("needs Node.js") ? failure : `${failure}\nRetry with: ${neonSkillsUpdateRetryCommand(scope === "global")}`);
+};
+//#endregion
+export { builder, command, describe, handler, skills_exports as t };

package/dist/commands/snapshots.js

@@ -18,8 +18,8 @@ const SNAPSHOT_FIELDS = [
 	"id",
 	"name",
 	"source_branch_id",
-	"created_at",
-	"expires_at"
+	"expires_at",
+	"created_at"
 ];
 const SCHEDULE_FIELDS = [
 	"frequency",

package/dist/context.js

@@ -51,6 +51,7 @@ const isProfileCommand = (args) => args._[0] === "profile" || args._[0] === "pro
 */
 const isApiKeysCommand = (args) => args._[0] === "api-keys" || args._[0] === "api-key";
 const isMcpCommand = (args) => args._[0] === "mcp";
+const isSkillsCommand = (args) => args._[0] === "skills";
 /** Raw argv is required because auth middleware runs before MCP flags are parsed. */
 const isMcpOauth = (args) => isMcpCommand(args) && argvEnablesMcpOauth(process.argv);
 const OAUTH_FALSE = /* @__PURE__ */ new Set([
@@ -130,6 +131,7 @@ const enrichFromContext = (args) => {
 	if (isApiKeysCommand(args)) return;
 	if (isProfileCommand(args)) return;
 	if (isMcpCommand(args)) return;
+	if (isSkillsCommand(args)) return;
 	const context = readContextFile(args.contextFile);
 	if (!args.orgId) args.orgId = context.orgId;
 	if (!args.projectId) args.projectId = context.projectId;
@@ -235,4 +237,4 @@ const globToRegExp = (pattern) => {
 	return new RegExp(`^${source}$`);
 };
 //#endregion
-export { applyContext, contextBranch, currentContextFile, enrichFromContext, ensureGitignored, isApiKeysCommand, isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isProfileCommand, readContextFile, setContext, updateContextFile, walkContextFile };
+export { applyContext, contextBranch, currentContextFile, enrichFromContext, ensureGitignored, isApiKeysCommand, isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isProfileCommand, isSkillsCommand, readContextFile, setContext, updateContextFile, walkContextFile };

package/dist/human_table.js

@@ -32,6 +32,12 @@ function displayWidth(s) {
 	}
 	return width;
 }
+function presentFields(data, fields) {
+	return fields.filter((field) => data.some((item) => {
+		const value = fieldValue(item, field);
+		return value !== void 0 && value !== "";
+	}));
+}
 function formatHumanChunk(chunk) {
 	const arrayData = Array.isArray(chunk.data) ? chunk.data : [chunk.data];
 	const isList = Array.isArray(chunk.data);
@@ -42,48 +48,28 @@ function formatHumanChunk(chunk) {
 		out += formatTitle(chunk.title, chunk.colorTitle) + "\n";
 	}
 	if (!arrayData.length) return out;
-	const fields = chunk.fields.filter((field) => arrayData.some((item) => {
-		const value = fieldValue(item, field);
-		return value !== void 0 && value !== "";
-	}));
+	if (isList) {
+		const fields = presentFields(arrayData, chunk.fields);
+		if (fields.length) {
+			const headers = fields.map(titleCaseField);
+			const rows = arrayData.map((item) => fields.map((field) => cellText(item, field, chunk.renderColumns)));
+			out += formatColumns(headers, rows, naturalWidths(headers, rows)) + "\n";
+		}
+		return out;
+	}
+	const fields = presentFields(arrayData, chunk.fields);
 	if (!fields.length) return out;
-	const headers = fields.map(titleCaseField);
-	const rows = arrayData.map((item) => fields.map((field) => cellText(item, field, chunk.renderColumns)));
-	const body = isList ? formatList(headers, rows, chunk.width) : formatStacked(headers, rows, chunk.width);
+	const body = formatStacked(fields.map(titleCaseField), arrayData.map((item) => fields.map((field) => cellText(item, field, chunk.renderColumns))), chunk.width);
 	if (body) out += body + "\n";
 	return out;
 }
 function formatTitle(title, colorTitle) {
 	return colorTitle ? chalk.bold(title) : title;
 }
-function formatList(headers, rows, width) {
-	if (headers.length === 1) return formatOneColumn(headers[0] ?? "", rows.map((row) => row[0] ?? ""));
-	if (width === void 0) return formatColumns(headers, rows, naturalWidths(headers, rows));
-	for (let n = headers.length; n >= 2; n--) {
-		const subsetHeaders = headers.slice(0, n);
-		const subsetRows = rows.map((row) => row.slice(0, n));
-		const natural = naturalWidths(subsetHeaders, subsetRows);
-		if (rowWidth(natural) <= width) return formatColumns(subsetHeaders, subsetRows, natural);
-		const fitted = tryFit(subsetHeaders, subsetRows, width);
-		if (fitted === void 0) continue;
-		if (!natural.slice(0, n - 1).every((col, i) => fitted[i] === col)) continue;
-		return formatColumns(subsetHeaders.map((cell, i) => truncateTo(cell, fitted[i] ?? 0)), subsetRows.map((row) => row.map((cell, i) => truncateTo(cell, fitted[i] ?? 0))), fitted);
-	}
-	return formatStacked(headers, rows, width);
-}
-function rowWidth(widths) {
-	if (widths.length === 0) return 0;
-	return widths.reduce((sum, col) => sum + col, 0) + (widths.length - 1) * GUTTER;
-}
-function formatOneColumn(header, values) {
-	const lines = [chalk.green(header)];
-	for (const value of values) lines.push(value);
-	return lines.join("\n");
-}
 function formatColumns(headers, rows, widths) {
 	const joinRow = (cells) => cells.map((cell, i) => {
 		const width = widths[i] ?? 0;
-		return i === cells.length - 1 ? truncateTo(cell, width) : padEndWidth(cell, width);
+		return i === cells.length - 1 ? cell : padEndWidth(cell, width);
 	}).join(" ".repeat(GUTTER)).trimEnd();
 	const lines = [chalk.green(joinRow(headers))];
 	for (const row of rows) lines.push(joinRow(row));
@@ -101,25 +87,6 @@ function formatStacked(headers, rows, width) {
 function stackedLine(header, value, labelWidth) {
 	return `${padEndWidth(header, labelWidth)}${" ".repeat(GUTTER)}${value}`;
 }
-function tryFit(headers, rows, width) {
-	const n = headers.length;
-	if (n === 0) return [];
-	const gutters = (n - 1) * GUTTER;
-	if (width <= gutters) return;
-	const budget = width - gutters;
-	if (budget < n * MIN_COL) return;
-	const widths = naturalWidths(headers, rows);
-	let overflow = widths.reduce((sum, col) => sum + col, 0) - budget;
-	if (overflow <= 0) return widths;
-	for (let i = n - 1; i >= 0 && overflow > 0; i--) {
-		const current = widths[i] ?? 0;
-		const take = Math.min(Math.max(current - MIN_COL, 0), overflow);
-		widths[i] = current - take;
-		overflow -= take;
-	}
-	if (overflow > 0) return;
-	return widths;
-}
 function naturalWidths(headers, rows) {
 	return headers.map((header, i) => Math.max(displayWidth(header), ...rows.map((row) => displayWidth(row[i] ?? ""))));
 }

package/dist/index.js

@@ -30,6 +30,7 @@ const NO_SUBCOMMANDS_VERBS = [
 	"open",
 	"init",
 	"mcp",
+	"skills",
 	"dev",
 	"deploy",
 	"diff",

package/dist/init/agents.js

@@ -1,4 +1,4 @@
-import { agentSupportsHttpMcp, agentSupportsProjectMcp, detectInstalledAgents, getAgentDisplayName, listMcpAgentIds, resolveAddMcpAgentId, tryResolveAddMcpAgentId } from "../mcp/agents.js";
+import { agentSupportsHttpMcp, agentSupportsProjectMcp, detectInstalledAgents, getAgentDisplayName, listMcpAgentIds, resolveAddMcpAgentId, tryResolveAddMcpAgentId, uniqueAgentIds } from "../mcp/agents.js";
 import { agents } from "add-mcp";
 //#region src/init/agents.ts
 const SKILLS_AGENT_BY_TYPE = {
@@ -48,4 +48,4 @@ function skillsPickerOptions() {
 	}));
 }
 //#endregion
-export { agentPickerHint, agentSupportsHttpMcp, agentSupportsProjectMcp, detectInstalledAgents, getAgentDisplayName, getSkillsAgentName, listMcpAgentIds, mcpPickerOptions, resolveAddMcpAgentId, skillsPickerOptions, supportsSkills, tryResolveAddMcpAgentId };
+export { agentPickerHint, agentSupportsHttpMcp, agentSupportsProjectMcp, detectInstalledAgents, getAgentDisplayName, getSkillsAgentName, listMcpAgentIds, mcpPickerOptions, resolveAddMcpAgentId, skillsPickerOptions, supportsSkills, tryResolveAddMcpAgentId, uniqueAgentIds };

package/dist/skills/catalog.js

@@ -0,0 +1,101 @@
+//#region src/skills/catalog.ts
+const AGENT_SKILLS_SOURCE = "neondatabase/agent-skills";
+const PLATFORMS_SKILLS_SOURCE = "neondatabase/neon-for-agent-platforms";
+const NEON_SKILL_CATALOG = [
+	{
+		skill: "claimable-postgres",
+		source: AGENT_SKILLS_SOURCE,
+		defaultSelected: true
+	},
+	{
+		skill: "neon",
+		source: AGENT_SKILLS_SOURCE,
+		defaultSelected: true
+	},
+	{
+		skill: "neon-ai-gateway",
+		source: AGENT_SKILLS_SOURCE,
+		defaultSelected: true
+	},
+	{
+		skill: "neon-functions",
+		source: AGENT_SKILLS_SOURCE,
+		defaultSelected: true
+	},
+	{
+		skill: "neon-object-storage",
+		source: AGENT_SKILLS_SOURCE,
+		defaultSelected: true
+	},
+	{
+		skill: "neon-postgres",
+		source: AGENT_SKILLS_SOURCE,
+		defaultSelected: true
+	},
+	{
+		skill: "neon-postgres-branches",
+		source: AGENT_SKILLS_SOURCE,
+		defaultSelected: true
+	},
+	{
+		skill: "neon-postgres-egress-optimizer",
+		source: AGENT_SKILLS_SOURCE,
+		defaultSelected: true
+	},
+	{
+		skill: "neon-postgres-agent-platforms",
+		source: PLATFORMS_SKILLS_SOURCE,
+		defaultSelected: false
+	}
+];
+const catalogBySkill = () => {
+	const map = /* @__PURE__ */ new Map();
+	for (const entry of NEON_SKILL_CATALOG) {
+		if (map.has(entry.skill)) throw new Error(`Duplicate catalog skill: ${entry.skill}`);
+		map.set(entry.skill, entry);
+	}
+	return map;
+};
+const CATALOG_BY_SKILL = catalogBySkill();
+const listSkillIds = () => NEON_SKILL_CATALOG.map((entry) => entry.skill);
+const defaultSkillEntries = () => NEON_SKILL_CATALOG.filter((entry) => entry.defaultSelected);
+function resolveSkillId(raw) {
+	if (raw === "*") throw new Error("neon skills does not accept --skill *. Pass --skill <name> for each skill, or omit --skill to install the default skills with -y.");
+	const entry = CATALOG_BY_SKILL.get(raw);
+	if (entry === void 0) throw new Error(`Unknown skill: "${raw}". Supported skills: ${listSkillIds().join(", ")}`);
+	return entry;
+}
+function uniqueSkillEntries(entries) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const entry of entries) {
+		if (seen.has(entry.skill)) continue;
+		seen.add(entry.skill);
+		out.push(entry);
+	}
+	return out;
+}
+const invocationsForSelection = (selected) => {
+	const unique = uniqueSkillEntries(selected);
+	if (unique.length === 0) throw new Error("No skills selected. Pass -y to install the default skills, or --skill <name>.");
+	const bySource = /* @__PURE__ */ new Map();
+	const sourceOrder = [];
+	for (const entry of unique) {
+		const list = bySource.get(entry.source);
+		if (list === void 0) {
+			bySource.set(entry.source, [entry.skill]);
+			sourceOrder.push(entry.source);
+		} else list.push(entry.skill);
+	}
+	return sourceOrder.map((source) => {
+		const skills = bySource.get(source);
+		if (skills === void 0 || skills.length === 0) throw new Error("skills add needs at least one --skill.");
+		return {
+			source,
+			skills
+		};
+	});
+};
+const yesInstallInvocations = () => invocationsForSelection(defaultSkillEntries());
+//#endregion
+export { AGENT_SKILLS_SOURCE, NEON_SKILL_CATALOG, PLATFORMS_SKILLS_SOURCE, defaultSkillEntries, invocationsForSelection, listSkillIds, resolveSkillId, uniqueSkillEntries, yesInstallInvocations };

package/dist/skills/plan.js

@@ -0,0 +1,57 @@
+import { tryResolveAddMcpAgentId } from "../mcp/agents.js";
+import "../init/agents.js";
+import { agentChoicesFrom, pickAgentsInteractively, resolveAgentSelection } from "../utils/agent_picker.js";
+import { invocationsForSelection, resolveSkillId, uniqueSkillEntries, yesInstallInvocations } from "./catalog.js";
+import { detectSkillsAgents, skillsInstallableAgents } from "./targets.js";
+import { pickSkillsInteractively } from "./wizard.js";
+//#region src/skills/plan.ts
+const assertSkillsCanRun = (options) => {
+	if (options.action === "update") {
+		if (options.yes || options.interactive) return;
+		throw new Error("No interactive terminal. Pass -y to update installed skills.");
+	}
+	if (options.yes || options.interactive || options.hasSkills === true) return;
+	throw new Error("No interactive terminal. Pass -y to install the default skills, or --skill <name>.");
+};
+async function resolveSkillsPlan(options) {
+	assertSkillsCanRun({
+		yes: options.yes,
+		interactive: options.interactive,
+		action: "install",
+		hasSkills: options.skills.length > 0
+	});
+	const specified = uniqueSkillEntries(options.skills.map(resolveSkillId));
+	const prompt = options.interactive && !options.yes;
+	const scope = options.global ? "global" : "project";
+	const available = skillsInstallableAgents();
+	const detected = await detectSkillsAgents({
+		scope,
+		cwd: options.cwd
+	});
+	const selected = await resolveAgentSelection({
+		specified: options.agents,
+		choices: agentChoicesFrom(available, detected),
+		detected,
+		message: "Which coding agents should get Neon agent skills? (space to toggle, enter to confirm)",
+		nonInteractiveMessage: scope === "project" ? `No coding agents detected in this project. Pass --agent <name>. Supported agents: ${available.join(", ")}` : `No coding agents detected. Pass --agent <name>. Supported agents: ${available.join(", ")}`,
+		resolveSpecified: (raw) => {
+			if (raw === "*") throw new Error("neon skills does not accept --agent *. Pass --agent <name> for each coding agent, or omit --agent to use detected agents.");
+			const id = tryResolveAddMcpAgentId(raw);
+			if (!id) throw new Error(`Unknown agent: "${raw}". Supported agents: ${available.join(", ")}`);
+			return id;
+		},
+		pick: prompt ? options.pickAgents ?? pickAgentsInteractively : void 0,
+		interactive: prompt
+	});
+	const agents = selected.filter((id) => available.includes(id));
+	const skipped = selected.filter((id) => !available.includes(id));
+	if (agents.length === 0) throw new Error(`None of the selected agents can install skills. Supported agents: ${available.join(", ")}`);
+	return {
+		scope,
+		agents,
+		skipped,
+		invocations: specified.length > 0 ? invocationsForSelection(specified) : options.yes ? yesInstallInvocations() : invocationsForSelection(await (options.pickSkills ?? pickSkillsInteractively)())
+	};
+}
+//#endregion
+export { assertSkillsCanRun, resolveSkillsPlan };

package/dist/skills/run.js

@@ -0,0 +1,119 @@
+import pkg_default from "../pkg.js";
+import { execa } from "execa";
+//#region src/skills/run.ts
+const TELEMETRY_BLOCKERS = ["DISABLE_TELEMETRY", "DO_NOT_TRACK"];
+const skillsMetadata = (command) => JSON.stringify({
+	origin: "neon-cli",
+	command,
+	version: pkg_default.version
+});
+const skillsChildEnv = (base = process.env) => {
+	const env = { ...base };
+	for (const key of TELEMETRY_BLOCKERS) delete env[key];
+	for (const key of Object.keys(env)) if (key.toUpperCase() === "NEON_API_KEY") delete env[key];
+	return env;
+};
+const SKILLS_MIN_NODE = "22.20.0";
+const nodeParts = (version) => {
+	const [major, minor, patch] = version.replace(/^v/, "").split(".").map((part) => Number.parseInt(part, 10));
+	return [
+		Number.isInteger(major) ? major : 0,
+		Number.isInteger(minor) ? minor : 0,
+		Number.isInteger(patch) ? patch : 0
+	];
+};
+const nodeMeetsMinimum = (current, minimum) => {
+	const left = nodeParts(current);
+	const right = nodeParts(minimum);
+	for (let i = 0; i < 3; i += 1) {
+		const a = left[i];
+		const b = right[i];
+		if (a === void 0 || b === void 0) return false;
+		if (a !== b) return a > b;
+	}
+	return true;
+};
+const assertSkillsNode = (version = process.version) => {
+	if (nodeMeetsMinimum(version, "22.20.0")) return;
+	throw new Error(`neon skills needs Node.js ${SKILLS_MIN_NODE} or newer to run the skills CLI. This process is Node.js ${version.replace(/^v/, "")}. Upgrade Node.js, then retry.`);
+};
+const skillsAddArgs = (options) => {
+	if (options.skills.length === 0) throw new Error("skills add needs at least one --skill.");
+	const args = [
+		"-y",
+		"skills",
+		"add",
+		options.source
+	];
+	for (const skill of options.skills) args.push("--skill", skill);
+	for (const agent of options.agents) args.push("--agent", agent);
+	if (options.global) args.push("-g");
+	args.push("-y", "--metadata", options.metadata);
+	return args;
+};
+const neonSkillsRetryCommand = (options) => {
+	const args = ["skills"];
+	for (const skill of options.skills) args.push("-s", skill);
+	for (const agent of options.agents) args.push("--agent", agent);
+	if (options.global) args.push("--global");
+	args.push("-y");
+	return `neon ${args.map(quoteNpxArg).join(" ")}`;
+};
+const neonSkillsUpdateRetryCommand = (global) => global ? "neon skills update --global -y" : "neon skills update -y";
+const quoteNpxArg = (part) => /[\s"'\\*]/.test(part) ? `'${part.replace(/'/g, `'\\''`)}'` : part;
+const npxCommand = (args) => `npx ${args.map(quoteNpxArg).join(" ")}`;
+const ANSI = /\u001b\[[0-9;]*[A-Za-z]/g;
+const UPDATE_BANNER = /^Checking for skill updates/i;
+const UPDATE_NOTHING = /No (?:project|global) skills (?:to update|to check|tracked in lock file|can be updated in place)|All global skills are up to date/i;
+const UPDATE_RESULT = /No (?:project|global) skills (?:to update|to check|tracked in lock file|can be updated in place)\.?|All global skills are up to date|(?:✓\s*)?Updated \d+ skills?(?:\(s\))?|(?:✗\s*)?Failed to update \d+ skills?(?:\(s\))?/i;
+const stripAnsi = (text) => text.replace(ANSI, "").replace(/\r/g, "");
+const skillsUpdateHadNothing = (output) => UPDATE_NOTHING.test(stripAnsi(output));
+const skillsUpdateDetail = (output) => {
+	const text = stripAnsi(output);
+	let last;
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (UPDATE_RESULT.test(trimmed)) last = trimmed;
+	}
+	if (last !== void 0) return last;
+	for (const line of text.split("\n").reverse()) {
+		const trimmed = line.trim();
+		if (trimmed.length === 0 || UPDATE_BANNER.test(trimmed)) continue;
+		return trimmed;
+	}
+};
+const skillsUpdateArgs = (options) => [
+	"-y",
+	"skills",
+	"update",
+	options.global ? "-g" : "-p",
+	"-y"
+];
+const runSkillsCli = async (options) => {
+	assertSkillsNode();
+	try {
+		const result = await execa("npx", options.args, {
+			cwd: options.cwd,
+			env: skillsChildEnv(),
+			extendEnv: false,
+			stdio: "pipe",
+			timeout: 12e4
+		});
+		return {
+			stdout: result.stdout,
+			stderr: result.stderr
+		};
+	} catch (error) {
+		if (isCommandMissing(error)) throw new Error("neon skills needs npx (Node.js) to run the skills CLI. Install Node.js, then retry.");
+		if (isExecaFailure(error)) {
+			const childOut = [error.stderr, error.stdout].filter((part) => typeof part === "string" && part.length > 0).join("\n");
+			const detail = childOut.length > 0 ? childOut : error.shortMessage;
+			throw new Error(detail.length > 0 ? `skills CLI failed:\n${detail}` : "skills CLI failed.");
+		}
+		throw error;
+	}
+};
+const isCommandMissing = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+const isExecaFailure = (error) => typeof error === "object" && error !== null && "shortMessage" in error && typeof error.shortMessage === "string";
+//#endregion
+export { SKILLS_MIN_NODE, assertSkillsNode, neonSkillsRetryCommand, neonSkillsUpdateRetryCommand, nodeMeetsMinimum, npxCommand, quoteNpxArg, runSkillsCli, skillsAddArgs, skillsChildEnv, skillsMetadata, skillsUpdateArgs, skillsUpdateDetail, skillsUpdateHadNothing };

package/dist/skills/targets.js

@@ -0,0 +1,23 @@
+import { detectInstalledAgents, listMcpAgentIds, uniqueAgentIds } from "../mcp/agents.js";
+import { getSkillsAgentName, supportsSkills } from "../init/agents.js";
+import { detectProjectAgents } from "add-mcp";
+//#region src/skills/targets.ts
+const skillsInstallableAgents = () => listMcpAgentIds().filter((id) => supportsSkills(id));
+const detectSkillsAgents = async (options) => {
+	const detected = options.scope === "project" ? detectProjectAgents(options.cwd) : await detectInstalledAgents();
+	return uniqueAgentIds(detected).filter((id) => supportsSkills(id));
+};
+const mappedSkillsAgentNames = (agents) => {
+	const names = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const agent of agents) {
+		const name = getSkillsAgentName(agent);
+		if (name === void 0 || seen.has(name)) continue;
+		seen.add(name);
+		names.push(name);
+	}
+	if (names.length === 0) throw new Error(`None of the selected agents can install skills. Supported agents: ${skillsInstallableAgents().join(", ")}`);
+	return names;
+};
+//#endregion
+export { detectSkillsAgents, mappedSkillsAgentNames, skillsInstallableAgents };

package/dist/skills/wizard.js

@@ -0,0 +1,73 @@
+import { getAgentDisplayName } from "../mcp/agents.js";
+import "../init/agents.js";
+import { canPickAgentsInteractively } from "../utils/agent_picker.js";
+import { NEON_SKILL_CATALOG } from "./catalog.js";
+import prompts from "prompts";
+//#region src/skills/wizard.ts
+const restoreCursorOnAbort = (state) => {
+	if (state.aborted) {
+		process.stdout.write("\x1B[?25h");
+		process.stdout.write("\n");
+		process.exit(1);
+	}
+};
+const pickSkillsInteractively = async () => {
+	if (!canPickAgentsInteractively()) throw new Error("No interactive terminal. Pass -y to install the default skills, or --skill <name>.");
+	const { skills } = await prompts({
+		onState: restoreCursorOnAbort,
+		type: "multiselect",
+		name: "skills",
+		message: "Which Neon agent skills should be installed? (space to toggle, enter to confirm)",
+		instructions: false,
+		min: 1,
+		choices: NEON_SKILL_CATALOG.map((entry) => ({
+			value: entry,
+			title: entry.skill,
+			selected: entry.defaultSelected
+		}))
+	});
+	if (!Array.isArray(skills) || skills.length === 0) throw new Error("No skills selected. Pass -y to install the default skills, or --skill <name>.");
+	return skills.filter(isSkillEntry);
+};
+const isSkillEntry = (value) => {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("source" in value) || !("skill" in value)) return false;
+	return typeof value.source === "string" && typeof value.skill === "string" && value.source.length > 0 && value.skill.length > 0;
+};
+const skillsInstallSummary = (options) => {
+	const skills = options.invocations.flatMap((invocation) => invocation.skills).join(", ");
+	const rows = [
+		["Config", options.scope === "project" ? "this directory" : "user-level"],
+		["Agents", options.agents.map(getAgentDisplayName).join(", ")],
+		["Skills", skills]
+	];
+	const labelWidth = Math.max(...rows.map(([label]) => label.length));
+	return rows.map(([label, value]) => `${label.padEnd(labelWidth)}  ${value}`).join("\n");
+};
+const confirmSkillsInstall = async (options) => {
+	if (!canPickAgentsInteractively()) return true;
+	process.stdout.write(`\n${skillsInstallSummary(options)}\n\n`);
+	const { ok } = await prompts({
+		onState: restoreCursorOnAbort,
+		type: "confirm",
+		name: "ok",
+		message: "Write Neon agent skills into these agents?",
+		initial: true
+	});
+	return ok === true;
+};
+const confirmSkillsUpdate = async (options) => {
+	if (!canPickAgentsInteractively()) return true;
+	const config = options.scope === "project" ? "this directory" : "user-level";
+	process.stdout.write(`\nConfig  ${config}\n\n`);
+	const { ok } = await prompts({
+		onState: restoreCursorOnAbort,
+		type: "confirm",
+		name: "ok",
+		message: "Update installed skills to the latest versions?",
+		initial: true
+	});
+	return ok === true;
+};
+//#endregion
+export { confirmSkillsInstall, confirmSkillsUpdate, pickSkillsInteractively, skillsInstallSummary };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",