opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/ci-cd-and-automation/SKILL.md

@@ -0,0 +1,403 @@
+---
+name: ci-cd-and-automation
+description: Automates CI/CD pipeline setup. Use when setting up or modifying build and deployment pipelines. Use when you need to automate quality gates, configure test runners in CI, or establish deployment strategies.
+risk: unknown
+source: https://github.com/addyosmani/agent-skills/tree/main/skills/ci-cd-and-automation
+source_repo: addyosmani/agent-skills
+source_type: community
+date_added: 2026-07-01
+license: MIT
+license_source: https://github.com/addyosmani/agent-skills/blob/main/LICENSE
+---
+
+# CI/CD and Automation
+
+## Overview
+
+Automate quality gates so that no change reaches production without passing tests, lint, type checking, and build. CI/CD is the enforcement mechanism for every other skill — it catches what humans and agents miss, and it does so consistently on every single change.
+
+**Shift Left:** Catch problems as early in the pipeline as possible. A bug caught in linting costs minutes; the same bug caught in production costs hours. Move checks upstream — static analysis before tests, tests before staging, staging before production.
+
+**Faster is Safer:** Smaller batches and more frequent releases reduce risk, not increase it. A deployment with 3 changes is easier to debug than one with 30. Frequent releases build confidence in the release process itself.
+
+## When to Use
+
+- Setting up a new project's CI pipeline
+- Adding or modifying automated checks
+- Configuring deployment pipelines
+- When a change should trigger automated verification
+- Debugging CI failures
+
+## The Quality Gate Pipeline
+
+Every change goes through these gates before merge:
+
+```
+Pull Request Opened
+    │
+    ▼
+┌─────────────────┐
+│   LINT CHECK     │  eslint, prettier
+│   ↓ pass         │
+│   TYPE CHECK     │  tsc --noEmit
+│   ↓ pass         │
+│   UNIT TESTS     │  jest/vitest
+│   ↓ pass         │
+│   BUILD          │  npm run build
+│   ↓ pass         │
+│   INTEGRATION    │  API/DB tests
+│   ↓ pass         │
+│   E2E (optional) │  Playwright/Cypress
+│   ↓ pass         │
+│   SECURITY AUDIT │  npm audit
+│   ↓ pass         │
+│   BUNDLE SIZE    │  bundlesize check
+└─────────────────┘
+    │
+    ▼
+  Ready for review
+```
+
+**No gate can be skipped.** If lint fails, fix lint — don't disable the rule. If a test fails, fix the code — don't skip the test.
+
+## GitHub Actions Configuration
+
+### Basic CI Pipeline
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Type check
+        run: npx tsc --noEmit
+
+      - name: Test
+        run: npm test -- --coverage
+
+      - name: Build
+        run: npm run build
+
+      - name: Security audit
+        run: npm audit --audit-level=high
+```
+
+### With Database Integration Tests
+
+```yaml
+  integration:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: testdb
+          POSTGRES_USER: ci_user
+          POSTGRES_PASSWORD: ${{ secrets.CI_DB_PASSWORD }}
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - name: Run migrations
+        run: npx prisma migrate deploy
+        env:
+          DATABASE_URL: postgresql://ci_user:${{ secrets.CI_DB_PASSWORD }}@localhost:5432/testdb
+      - name: Integration tests
+        run: npm run test:integration
+        env:
+          DATABASE_URL: postgresql://ci_user:${{ secrets.CI_DB_PASSWORD }}@localhost:5432/testdb
+```
+
+> **Note:** Even for CI-only test databases, use GitHub Secrets for credentials rather than hardcoding values. This builds good habits and prevents accidental reuse of test credentials in other contexts.
+
+### E2E Tests
+
+```yaml
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - run: npm ci
+      - name: Install Playwright
+        run: npx playwright install --with-deps chromium
+      - name: Build
+        run: npm run build
+      - name: Run E2E tests
+        run: npx playwright test
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+```
+
+## Feeding CI Failures Back to Agents
+
+The power of CI with AI agents is the feedback loop. When CI fails:
+
+```
+CI fails
+    │
+    ▼
+Copy the failure output
+    │
+    ▼
+Feed it to the agent:
+"The CI pipeline failed with this error:
+[paste specific error]
+Fix the issue and verify locally before pushing again."
+    │
+    ▼
+Agent fixes → pushes → CI runs again
+```
+
+**Key patterns:**
+
+```
+Lint failure → Agent runs `npm run lint --fix` and commits
+Type error  → Agent reads the error location and fixes the type
+Test failure → Agent follows debugging-and-error-recovery skill
+Build error → Agent checks config and dependencies
+```
+
+## Deployment Strategies
+
+### Preview Deployments
+
+Every PR gets a preview deployment for manual testing:
+
+```yaml
+# Deploy preview on PR (Vercel/Netlify/etc.)
+deploy-preview:
+  runs-on: ubuntu-latest
+  if: github.event_name == 'pull_request'
+  steps:
+    - uses: actions/checkout@v4
+    - name: Deploy preview
+      run: npx vercel --token=${{ secrets.VERCEL_TOKEN }}
+```
+
+### Feature Flags
+
+Feature flags decouple deployment from release. Deploy incomplete or risky features behind flags so you can:
+
+- **Ship code without enabling it.** Merge to main early, enable when ready.
+- **Roll back without redeploying.** Disable the flag instead of reverting code.
+- **Canary new features.** Enable for 1% of users, then 10%, then 100%.
+- **Run A/B tests.** Compare behavior with and without the feature.
+
+```typescript
+// Simple feature flag pattern
+if (featureFlags.isEnabled('new-checkout-flow', { userId })) {
+  return renderNewCheckout();
+}
+return renderLegacyCheckout();
+```
+
+**Flag lifecycle:** Create → Enable for testing → Canary → Full rollout → Remove the flag and dead code. Flags that live forever become technical debt — set a cleanup date when you create them.
+
+### Staged Rollouts
+
+```
+PR merged to main
+    │
+    ▼
+  Staging deployment (auto)
+    │ Manual verification
+    ▼
+  Production deployment (manual trigger or auto after staging)
+    │
+    ▼
+  Monitor for errors (15-minute window)
+    │
+    ├── Errors detected → Rollback
+    └── Clean → Done
+```
+
+### Rollback Plan
+
+Every deployment should be reversible:
+
+```yaml
+# Manual rollback workflow
+name: Rollback
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to rollback to'
+        required: true
+
+jobs:
+  rollback:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Rollback deployment
+        run: |
+          # Deploy the specified previous version
+          npx vercel rollback ${{ inputs.version }}
+```
+
+## Environment Management
+
+```
+.env.example       → Committed (template for developers)
+.env                → NOT committed (local development)
+.env.test           → Committed (test environment, no real secrets)
+CI secrets          → Stored in GitHub Secrets / vault
+Production secrets  → Stored in deployment platform / vault
+```
+
+CI should never have production secrets. Use separate secrets for CI testing.
+
+## Automation Beyond CI
+
+### Dependabot / Renovate
+
+```yaml
+# .github/dependabot.yml
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+```
+
+### Build Cop Role
+
+Designate someone responsible for keeping CI green. When the build breaks, the Build Cop's job is to fix or revert — not the person whose change caused the break. This prevents broken builds from accumulating while everyone assumes someone else will fix it.
+
+### PR Checks
+
+- **Required reviews:** At least 1 approval before merge
+- **Required status checks:** CI must pass before merge
+- **Branch protection:** No force-pushes to main
+- **Auto-merge:** If all checks pass and approved, merge automatically
+
+## CI Optimization
+
+When the pipeline exceeds 10 minutes, apply these strategies in order of impact:
+
+```
+Slow CI pipeline?
+├── Cache dependencies
+│   └── Use actions/cache or setup-node cache option for node_modules
+├── Run jobs in parallel
+│   └── Split lint, typecheck, test, build into separate parallel jobs
+├── Only run what changed
+│   └── Use path filters to skip unrelated jobs (e.g., skip e2e for docs-only PRs)
+├── Use matrix builds
+│   └── Shard test suites across multiple runners
+├── Optimize the test suite
+│   └── Remove slow tests from the critical path, run them on a schedule instead
+└── Use larger runners
+    └── GitHub-hosted larger runners or self-hosted for CPU-heavy builds
+```
+
+**Example: caching and parallelism**
+```yaml
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '22', cache: 'npm' }
+      - run: npm ci
+      - run: npm run lint
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '22', cache: 'npm' }
+      - run: npm ci
+      - run: npx tsc --noEmit
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '22', cache: 'npm' }
+      - run: npm ci
+      - run: npm test -- --coverage
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "CI is too slow" | Optimize the pipeline (see CI Optimization below), don't skip it. A 5-minute pipeline prevents hours of debugging. |
+| "This change is trivial, skip CI" | Trivial changes break builds. CI is fast for trivial changes anyway. |
+| "The test is flaky, just re-run" | Flaky tests mask real bugs and waste everyone's time. Fix the flakiness. |
+| "We'll add CI later" | Projects without CI accumulate broken states. Set it up on day one. |
+| "Manual testing is enough" | Manual testing doesn't scale and isn't repeatable. Automate what you can. |
+
+## Red Flags
+
+- No CI pipeline in the project
+- CI failures ignored or silenced
+- Tests disabled in CI to make the pipeline pass
+- Production deploys without staging verification
+- No rollback mechanism
+- Secrets stored in code or CI config files (not secrets manager)
+- Long CI times with no optimization effort
+
+## Verification
+
+After setting up or modifying CI:
+
+- [ ] All quality gates are present (lint, types, tests, build, audit)
+- [ ] Pipeline runs on every PR and push to main
+- [ ] Failures block merge (branch protection configured)
+- [ ] CI results feed back into the development loop
+- [ ] Secrets are stored in the secrets manager, not in code
+- [ ] Deployment has a rollback mechanism
+- [ ] Pipeline runs in under 10 minutes for the test suite
+
+## Limitations
+
+- Use this skill only when the task clearly matches its upstream source and local project context.
+- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
+- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.

package/bundled-skills/claimable-postgres/SKILL.md

@@ -1,18 +1,27 @@
 ---
 name: claimable-postgres
-description: Provision instant temporary Postgres databases via Claimable Postgres by Neon (pg.new). No login or credit card required. Use for quick Postgres environments and throwaway DATABASE_URL for prototyping.
+description: Provision instant temporary Postgres databases via Claimable Postgres by Neon (neon.new) with no login, signup, or credit card. Supports REST API, CLI, and SDK. Use when users ask for a quick Postgres environment, a throwaway DATABASE_URL for prototyping/tests, or "just give me a DB...
 risk: unknown
-source: community
+source: https://github.com/neondatabase/agent-skills/tree/main/skills/claimable-postgres
+source_repo: neondatabase/agent-skills
+source_type: official
+date_added: 2026-07-01
+license: Apache-2.0
+license_source: https://github.com/neondatabase/agent-skills/blob/main/LICENSE
 ---
 
 # Claimable Postgres
+## When to Use
+
+Use this skill when you need provision instant temporary Postgres databases via Claimable Postgres by Neon (neon.new) with no login, signup, or credit card. Supports REST API, CLI, and SDK. Use when users ask for a quick Postgres environment, a throwaway DATABASE_URL for prototyping/tests, or "just give me a DB...
+
 
 Instant Postgres databases for local development, demos, prototyping, and test environments. No account required. Databases expire after 72 hours unless claimed to a Neon account.
 
 ## Quick Start
 
 ```bash
-curl -s -X POST "https://pg.new/api/v1/database" \
+curl -s -X POST "https://neon.new/api/v1/database" \
   -H "Content-Type: application/json" \
   -d '{"ref": "agent-skills"}'
 ```
@@ -24,27 +33,27 @@ For other methods (CLI, SDK, Vite plugin), see [Which Method?](#which-method) be
 ## Which Method?
 
 - **REST API**: Returns structured JSON. No runtime dependency beyond `curl`. Preferred when the agent needs predictable output and error handling.
-- **CLI** (`npx get-db@latest --yes`): Provisions and writes `.env` in one command. Convenient when Node.js is available and the user wants a simple setup.
-- **SDK** (`get-db/sdk`): Scripts or programmatic provisioning in Node.js.
-- **Vite plugin** (`vite-plugin-db`): Auto-provisions on `vite dev` if `DATABASE_URL` is missing. Use when the user has a Vite project.
-- **Browser**: User cannot run CLI or API. Direct to https://pg.new.
+- **CLI** (`npx neon-new@latest --yes`): Provisions and writes `.env` in one command. Convenient when Node.js is available and the user wants a simple setup.
+- **SDK** (`neon-new/sdk`): Scripts or programmatic provisioning in Node.js.
+- **Vite plugin** (`vite-plugin-neon-new`): Auto-provisions on `vite dev` if `DATABASE_URL` is missing. Use when the user has a Vite project.
+- **Browser**: User cannot run CLI or API. Direct to https://neon.new.
 
 ## REST API
 
-**Base URL:** `https://pg.new/api/v1`
+**Base URL:** `https://neon.new/api/v1`
 
 ### Create a database
 
 ```bash
-curl -s -X POST "https://pg.new/api/v1/database" \
+curl -s -X POST "https://neon.new/api/v1/database" \
   -H "Content-Type: application/json" \
   -d '{"ref": "agent-skills"}'
 ```
 
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `ref` | Yes | Tracking tag that identifies who provisioned the database. Use `"agent-skills"` when provisioning through this skill. |
-| `enable_logical_replication` | No | Enable logical replication (default: false, cannot be disabled once enabled) |
+| Parameter                    | Required | Description                                                                                                           |
+| ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
+| `ref`                        | Yes      | Tracking tag that identifies who provisioned the database. Use `"agent-skills"` when provisioning through this skill. |
+| `enable_logical_replication` | No       | Enable logical replication (default: false, cannot be disabled once enabled)                                          |
 
 The `connection_string` returned by the API is a pooled connection URL. For a direct (non-pooled) connection (e.g. Prisma migrations), remove `-pooler` from the hostname. The CLI writes both pooled and direct URLs automatically.
 
@@ -56,7 +65,7 @@ The `connection_string` returned by the API is a pooled connection URL. For a di
   "status": "UNCLAIMED",
   "neon_project_id": "gentle-scene-06438508",
   "connection_string": "postgresql://...",
-  "claim_url": "https://pg.new/claim/019beb39-...",
+  "claim_url": "https://neon.new/claim/019beb39-...",
   "expires_at": "2026-01-26T14:19:14.580Z",
   "created_at": "2026-01-23T14:19:14.580Z",
   "updated_at": "2026-01-23T14:19:14.580Z"
@@ -66,23 +75,23 @@ The `connection_string` returned by the API is a pooled connection URL. For a di
 ### Check status
 
 ```bash
-curl -s "https://pg.new/api/v1/database/{id}"
+curl -s "https://neon.new/api/v1/database/{id}"
 ```
 
 Returns the same response shape. Status transitions: `UNCLAIMED` -> `CLAIMING` -> `CLAIMED`. After the database is claimed, `connection_string` returns `null`.
 
 ### Error responses
 
-| Condition | HTTP | Message |
-|-----------|------|---------|
-| Missing or empty `ref` | 400 | `Missing referrer` |
-| Invalid database ID | 400 | `Database not found` |
-| Invalid JSON body | 500 | `Failed to create the database.` |
+| Condition              | HTTP | Message                          |
+| ---------------------- | ---- | -------------------------------- |
+| Missing or empty `ref` | 400  | `Missing referrer`               |
+| Invalid database ID    | 400  | `Database not found`             |
+| Invalid JSON body      | 500  | `Failed to create the database.` |
 
 ## CLI
 
 ```bash
-npx get-db@latest --yes
+npx neon-new@latest --yes
 ```
 
 Provisions a database and writes the connection string to `.env` in one step. Always use `@latest` and `--yes` (skips interactive prompts that would stall the agent).
@@ -101,17 +110,17 @@ Get confirmation before proceeding.
 
 ### Options
 
-| Option | Alias | Description | Default |
-|--------|-------|-------------|---------|
-| `--yes` | `-y` | Skip prompts, use defaults | `false` |
-| `--env` | `-e` | .env file path | `./.env` |
-| `--key` | `-k` | Connection string env var key | `DATABASE_URL` |
-| `--prefix` | `-p` | Prefix for generated public env vars | `PUBLIC_` |
-| `--seed` | `-s` | Path to seed SQL file | none |
-| `--logical-replication` | `-L` | Enable logical replication | `false` |
-| `--ref` | `-r` | Referrer id (use `agent-skills` when provisioning through this skill) | none |
+| Option                  | Alias | Description                                                           | Default        |
+| ----------------------- | ----- | --------------------------------------------------------------------- | -------------- |
+| `--yes`                 | `-y`  | Skip prompts, use defaults                                            | `false`        |
+| `--env`                 | `-e`  | .env file path                                                        | `./.env`       |
+| `--key`                 | `-k`  | Connection string env var key                                         | `DATABASE_URL` |
+| `--prefix`              | `-p`  | Prefix for generated public env vars                                  | `PUBLIC_`      |
+| `--seed`                | `-s`  | Path to seed SQL file                                                 | none           |
+| `--logical-replication` | `-L`  | Enable logical replication                                            | `false`        |
+| `--ref`                 | `-r`  | Referrer id (use `agent-skills` when provisioning through this skill) | none           |
 
-Alternative package managers: `yarn dlx get-db@latest`, `pnpm dlx get-db@latest`, `bunx get-db@latest`, `deno run -A get-db@latest`.
+Alternative package managers: `yarn dlx neon-new@latest`, `pnpm dlx neon-new@latest`, `bunx neon-new@latest`, `deno run -A neon-new@latest`.
 
 ### Output
 
@@ -120,7 +129,7 @@ The CLI writes to the target `.env`:
 ```
 DATABASE_URL=postgresql://...              # pooled (use for application queries)
 DATABASE_URL_DIRECT=postgresql://...       # direct (use for migrations, e.g. Prisma)
-PUBLIC_POSTGRES_CLAIM_URL=https://pg.new/claim/...
+PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/...
 ```
 
 ## SDK
@@ -128,26 +137,27 @@ PUBLIC_POSTGRES_CLAIM_URL=https://pg.new/claim/...
 Use for scripts and programmatic provisioning flows.
 
 ```typescript
-import { instantPostgres } from 'get-db';
+import { instantPostgres } from "neon-new";
 
-const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } = await instantPostgres({
-  referrer: 'agent-skills',
-  seed: { type: 'sql-script', path: './init.sql' },
-});
+const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } =
+  await instantPostgres({
+    referrer: "agent-skills",
+    seed: { type: "sql-script", path: "./init.sql" },
+  });
 ```
 
 Returns `databaseUrl` (pooled), `databaseUrlDirect` (direct, for migrations), `claimUrl`, and `claimExpiresAt` (Date object). The `referrer` parameter is required.
 
 ## Vite Plugin
 
-For Vite projects, `vite-plugin-db` auto-provisions a database on `vite dev` if `DATABASE_URL` is missing. Install with `npm install -D vite-plugin-db`. See the [Claimable Postgres docs](https://neon.com/docs/reference/claimable-postgres#vite-plugin) for configuration.
+For Vite projects, `vite-plugin-neon-new` auto-provisions a database on `vite dev` if `DATABASE_URL` is missing. Install with `npm install -D vite-plugin-neon-new`. See the [Claimable Postgres docs](https://neon.com/docs/reference/claimable-postgres#vite-plugin) for configuration.
 
 ## Agent Workflow
 
 ### API path
 
 1. **Confirm intent:** If the request is ambiguous, confirm the user wants a temporary, no-signup database. Skip this if they explicitly asked for a quick or temporary database.
-2. **Provision:** POST to `https://pg.new/api/v1/database` with `{"ref": "agent-skills"}`.
+2. **Provision:** POST to `https://neon.new/api/v1/database` with `{"ref": "agent-skills"}`.
 3. **Parse response:** Extract `connection_string`, `claim_url`, and `expires_at` from the JSON response.
 4. **Write .env:** Write `DATABASE_URL=<connection_string>` to the project's `.env` (or the user's preferred file and key). Do not overwrite an existing key without confirmation.
 5. **Seed (if needed):** If the user has a seed SQL file, run it against the new database:
@@ -164,7 +174,7 @@ For Vite projects, `vite-plugin-db` auto-provisions a database on `vite dev` if
 3. **Gather options:** Use defaults unless context suggests otherwise (e.g., user mentions a custom env file, seed SQL, or logical replication).
 4. **Run:** Execute with `@latest --yes` plus the confirmed options. Always use `@latest` to avoid stale cached versions. `--yes` skips interactive prompts that would stall the agent.
    ```bash
-   npx get-db@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
+   npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
    ```
 5. **Verify:** Confirm the connection string was written to the intended file.
 6. **Report:** Tell the user where the connection string was written, which key was used, and that a claim URL is in the env file. Remind them: the database works now; claim within 72 hours to keep it permanently.
@@ -184,26 +194,51 @@ Always report:
 Claiming is optional. The database works immediately without it. To optionally claim, the user opens the claim URL in a browser, where they sign in or create a Neon account to claim the database.
 
 - **API/SDK:** Give the user the `claim_url` from the create response.
-- **CLI:** `npx get-db@latest claim` reads the claim URL from `.env` and opens the browser automatically.
+- **CLI:** `npx neon-new@latest claim` reads the claim URL from `.env` and opens the browser automatically.
 
 Users cannot claim into Vercel-linked orgs; they must choose another Neon org.
 
+## Neon Infrastructure as Code (`neon.ts`)
+
+Claimable databases are deliberately throwaway and provisioned through `neon.new` (above), so they aren't managed by `neon.ts`. Once a user **claims** a database into a Neon account it becomes a normal Neon project — at which point `neon.ts`, Neon's infrastructure-as-code file, is how you manage it going forward (see the `neon` skill for the full reference): declare the services its branches should have, program per-branch compute, and get type-safe env vars.
+
+```bash
+npm i @neon/config
+```
+
+```typescript
+// neon.ts
+import { defineConfig } from "@neon/config/v1";
+
+export default defineConfig({
+  auth: true, // Neon Auth, once you outgrow a bare connection string
+  dataApi: true, // Data API
+  branch: (branch) => (branch.exists ? {} : { ttl: "7d" }), // ephemeral non-default branches
+});
+```
+
+```bash
+neon config apply   # provision the declared services (neon deploy is an alias)
+```
+
+If a project needs branching, multiple services, or durable infrastructure tracked in version control, recommend claiming first and then adopting `neon.ts` — rather than re-provisioning throwaway claimable databases.
+
 ## Defaults and Limits
 
-| Parameter | Value |
-|-----------|-------|
-| Provider | AWS |
-| Region | us-east-2 |
-| Postgres | 17 |
+| Parameter | Value     |
+| --------- | --------- |
+| Provider  | AWS       |
+| Region    | us-east-2 |
+| Postgres  | 17        |
 
 Region cannot be changed for claimable databases. Unclaimed databases have stricter quotas. Claiming resets limits to free plan defaults.
 
-| | Unclaimed | Claimed (Free plan) |
-|---|-----------|---------------------|
-| Storage | 100 MB | 512 MB |
-| Transfer | 1 GB | ~5 GB |
-| Branches | No | Yes |
-| Expiration | 72 hours | None |
+|            | Unclaimed | Claimed (Free plan) |
+| ---------- | --------- | ------------------- |
+| Storage    | 100 MB    | 512 MB              |
+| Transfer   | 1 GB      | ~5 GB               |
+| Branches   | No        | Yes                 |
+| Expiration | 72 hours  | None                |
 
 ## Auto-provisioning
 
@@ -217,11 +252,8 @@ If the agent needs a database to fulfill a task (e.g. "build me a todo app with
 - If users need long-term persistence, instruct them to open the claim URL right away.
 - After writing credentials to an .env file, check that it's covered by .gitignore. If not, warn the user. Do not modify `.gitignore` without confirmation.
 
-
-## When to Use
-Use this skill when tackling tasks related to its primary domain or functionality as described above.
-
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- Use this skill only when the task clearly matches its upstream product or API scope.
+- Verify commands, API behavior, pricing, quotas, credentials, and deployment effects against current official documentation before making changes.
+- Do not treat generated examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.