From 30f2fe57308792652702d0f92531876f77781ca0 Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Wed, 10 Jun 2026 18:51:56 -0700 Subject: [PATCH 1/5] docs(marketplace): simplify skill, emphasize discovery-first workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Trim marketplace SKILL.md from 491 lines to 212. Remove partner-facing content (building integrations, Observability deep-dive, per-integration code samples) and the hardcoded category list — those duplicate the live \`vercel integration categories\` output and go stale. Lead with a prominent "Discover BEFORE you scaffold" section so agents treat \`vercel integration discover\` as the first action on casual "build me X" prompts rather than scaffolding from memory. Document the multi-\`--category\` flag pattern alongside the new \`vercel integration categories\` subcommand. Regenerate skill-manifest.json (intents updated: drop "build integration", add "discover integrations"). --- generated/skill-manifest.json | 6 +- skills/marketplace/SKILL.md | 471 +++++++--------------------------- 2 files changed, 99 insertions(+), 378 deletions(-) diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index 7631eb4..c1e1217 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-06-09T19:39:41.807Z", + "generatedAt": "2026-06-11T01:51:43.238Z", "version": 2, "skills": { "vercel-agent": { @@ -1309,9 +1309,9 @@ ], "intents": [ "install integration", - "build integration", "manage marketplace", - "add third party service" + "add third party service", + "discover integrations" ], "entities": [ "Vercel Marketplace", diff --git a/skills/marketplace/SKILL.md b/skills/marketplace/SKILL.md index 58f4d02..371c83b 100644 --- a/skills/marketplace/SKILL.md +++ b/skills/marketplace/SKILL.md @@ -1,6 +1,6 @@ --- name: marketplace -description: Vercel Marketplace expert guidance — discovering, installing, and building integrations, auto-provisioned environment variables, unified billing, and the vercel integration CLI. Use when consuming third-party services, building custom integrations, or managing marketplace resources on Vercel. +description: Vercel Marketplace expert guidance — discovering, installing, and managing integrations via the `vercel integration` CLI, with auto-provisioned environment variables and unified billing. Use when consuming third-party services on Vercel. metadata: priority: 3 docs: @@ -20,9 +20,9 @@ retrieval: - add ons intents: - install integration - - build integration - manage marketplace - add third party service + - discover integrations entities: - Vercel Marketplace - integration @@ -42,36 +42,56 @@ chainTo: # Vercel Marketplace -You are an expert in the Vercel Marketplace — the integration platform that connects third-party services to Vercel projects with unified billing, auto-provisioned environment variables, and one-click setup. +You drive the Vercel Marketplace via the `vercel integration` CLI. It provisions third-party services (databases, auth, observability, AI, payments, etc.) into the linked project with auto-injected env vars and unified billing. + +## CRITICAL: Discover BEFORE you scaffold + +When the user asks you to build, create, scaffold, or describe an app — even casually ("build me X", "I want an app that does Z", "make me a dashboard") — your FIRST action is `vercel integration discover`, NOT writing application code. + +**Why this matters:** scaffolding code from memory hardcodes integrations from your training data, which are often outdated. The Marketplace is the live source of truth for what's available and provisions env vars for you automatically. + +**The workflow:** + +1. Read the user's prompt and identify what kinds of services they'll need (auth, storage, payments, AI, monitoring, etc.) — use your own judgment, the Marketplace organizes around standard categories. +2. Run `vercel integration categories` to get the canonical category slugs. +3. Run `vercel integration discover --category ` to filter. Use multiple `--category` flags in one call if the prompt has multiple needs. +4. Recommend specific integrations from the results. Only then write code. ## Consuming Integrations -### Linked Project Preflight +### Linked project preflight -Integration provisioning is project-scoped. Verify the repository is linked before running `integration add`. +Integration provisioning is project-scoped. Verify the repo is linked before any `add`/`connect`: ```bash -# Check whether this directory is linked to a Vercel project -test -f .vercel/project.json && echo "Linked" || echo "Not linked" - -# Link if needed -vercel link +test -f .vercel/project.json && echo "Linked" || vercel link ``` -If the project is not linked, do not continue with provisioning commands until linking completes. +If not linked, do not continue with provisioning until linking completes. ### Discovering Integrations ```bash -# Search the Marketplace catalog from CLI -vercel integration discover +# List canonical category slugs (always run this first when filtering) +vercel integration categories +vercel integration categories --json -# Filter by category -vercel integration discover --category databases -vercel integration discover --category monitoring +# Filter discover by category +vercel integration discover --category storage +vercel integration discover -c ai # shorthand -# List integrations already installed on this project -vercel integration list +# Multi-category in a single command (preferred when user has multiple needs) +vercel integration discover --category commerce --category payments --category auth +vercel integration discover -c storage -c ai +# Server-side union: returns integrations matching ANY listed category. + +# Specific integration by name (substring search across slug/name/description) +vercel integration discover postgres +vercel integration discover sentry + +# Full catalog (rare — usually narrow with --category) +vercel integration discover +vercel integration discover --format=json ``` For browsing the full catalog interactively, use the [Vercel Marketplace](https://vercel.com/marketplace) dashboard. @@ -79,413 +99,114 @@ For browsing the full catalog interactively, use the [Vercel Marketplace](https: ### Getting Setup Guidance ```bash -# Get agent-friendly setup guide for a specific integration +# Agent-friendly setup guide for a specific integration vercel integration guide -# Include framework-specific steps when available +# Framework-specific steps when available vercel integration guide --framework - -# Examples -vercel integration guide neon -vercel integration guide datadog --framework nextjs ``` -Use `--framework ` as the default discovery flow when framework-specific setup matters. The guide returns structured setup steps including required environment variables, SDK packages, and code snippets — ideal for agentic workflows. +Supported frameworks: `nextjs`, `remix`, `astro`, `nuxtjs`, `sveltekit`. The guide returns env vars, packages, and code snippets tailored to the framework. ### Installing an Integration -```bash -# Install from CLI -vercel integration add - -# Examples -vercel integration add neon # Postgres database -vercel integration add upstash # Redis / Kafka -vercel integration add clerk # Authentication -vercel integration add sentry # Error monitoring -vercel integration add sanity # CMS -vercel integration add datadog # Observability (auto-configures drain) -``` - -`vercel integration add` is the primary scripted/AI path. It installs to the currently linked project, auto-connects the integration, and auto-runs environment sync locally unless disabled. - -If the CLI hands off to the dashboard for provider-specific completion, treat that as fallback: - -```bash -vercel integration open -``` - -Complete the web step, then return to CLI verification (`vercel env ls` and local env sync check). - -### Auto-Provisioned Environment Variables - -When you install a Marketplace integration from a linked project, Vercel automatically provisions the required environment variables for that project. - -**IMPORTANT: Provisioning delay after install.** After installing a database integration (especially Neon), the resource may take **1–3 minutes** to fully provision. During this window, connection attempts return HTTP 500 errors. Do NOT debug the connection string or code — just wait and retry. If local env sync was disabled or skipped, run `vercel env pull .env.local --yes` after a brief wait to get the finalized credentials. +One command provisions the resource, connects it to the linked project, and pulls env vars locally: ```bash -# View environment variables added by integrations -vercel env ls - -# Example: after installing Neon, these are auto-provisioned: -# POSTGRES_URL — connection string -# POSTGRES_URL_NON_POOLING — direct connection -# POSTGRES_USER — database user -# POSTGRES_PASSWORD — database password -# POSTGRES_DATABASE — database name -# POSTGRES_HOST — database host -``` - -No manual `.env` file management is needed — the variables are injected into all environments (Development, Preview, Production) automatically. - -### Using Provisioned Resources - -```ts -// app/api/users/route.ts — using Neon auto-provisioned env vars -import { neon } from "@neondatabase/serverless"; - -// POSTGRES_URL is auto-injected by the Neon integration -const sql = neon(process.env.POSTGRES_URL!); - -export async function GET() { - const users = await sql`SELECT * FROM users LIMIT 10`; - return Response.json(users); -} -``` - -```ts -// app/api/cache/route.ts — using Upstash auto-provisioned env vars -import { Redis } from "@upstash/redis"; - -// KV_REST_API_URL and KV_REST_API_TOKEN are auto-injected -const redis = Redis.fromEnv(); - -export async function GET() { - const cached = await redis.get("featured-products"); - return Response.json(cached); -} -``` - -### Managing Integrations - -```bash -# List installed integrations -vercel integration ls - -# Check usage and billing for an integration -vercel integration balance +vercel integration add -# Remove an integration -vercel integration remove -``` +# Multi-product integrations use slash syntax +vercel integration add aws/aws-dynamodb -## Unified Billing +# Custom resource name +vercel integration add --name my-resource -Marketplace integrations use Vercel's unified billing system: +# Specific environments (defaults to all three) +vercel integration add --environment production --environment preview -- **Single invoice**: All integration charges appear on your Vercel bill -- **Usage-based**: Pay for what you use, scaled per integration's pricing model -- **Team-level billing**: Charges roll up to the Vercel team account -- **No separate accounts**: No need to manage billing with each provider individually +# Namespace env vars to avoid collisions +vercel integration add --prefix NEON2_ -```bash -# Check current usage balance for an integration -vercel integration balance datadog -vercel integration balance neon +# Non-interactive (CI / scripted) +vercel integration add --no-claim --format=json ``` -## Building Integrations - -### Integration Architecture - -Vercel integrations consist of: +Aliases: `vercel install ` and `vercel i `. -1. **Integration manifest** — declares capabilities, required scopes, and UI surfaces -2. **Webhook handlers** — respond to Vercel lifecycle events -3. **UI components** — optional dashboard panels rendered within Vercel -4. **Resource provisioning** — create and manage resources for users - -### Scaffold an Integration +If the CLI hands off to the dashboard for provider-specific completion, use the web fallback: ```bash -# Create a new integration project -npx create-vercel-integration my-integration - -# Or start from the template -npx create-next-app my-integration --example vercel-integration -``` - -### Integration Manifest - -```json -// vercel-integration.json -{ - "name": "my-integration", - "slug": "my-integration", - "description": "Provides X for Vercel projects", - "logo": "public/logo.svg", - "website": "https://my-service.com", - "categories": ["databases"], - "scopes": { - "project": ["env-vars:read-write"], - "team": ["integrations:read-write"] - }, - "installationType": "marketplace", - "resourceTypes": [ - { - "name": "database", - "displayName": "Database", - "description": "A managed database instance" - } - ] -} -``` - -### Handling Lifecycle Webhooks - -```ts -// app/api/webhook/route.ts -import { verifyVercelSignature } from "@vercel/integration-utils"; - -export async function POST(req: Request) { - const body = await req.json(); - - // Verify the webhook is from Vercel - const isValid = await verifyVercelSignature(req, body); - if (!isValid) { - return Response.json({ error: "Invalid signature" }, { status: 401 }); - } - - switch (body.type) { - case "integration.installed": - // Provision resources for the new installation - await provisionDatabase(body.payload); - break; - - case "integration.uninstalled": - // Clean up resources - await deprovisionDatabase(body.payload); - break; - - case "integration.configuration-updated": - // Handle config changes - await updateConfiguration(body.payload); - break; - } - - return Response.json({ received: true }); -} +vercel integration open ``` -### Provisioning Environment Variables - -```ts -// lib/provision.ts -async function provisionEnvVars( - installationId: string, - projectId: string, - credentials: { url: string; token: string }, -) { - const response = await fetch( - `https://api.vercel.com/v1/integrations/installations/${installationId}/env`, - { - method: "POST", - headers: { - Authorization: `Bearer ${process.env.VERCEL_INTEGRATION_TOKEN}`, - "Content-Type": "application/json", - }, - body: JSON.stringify({ - projectId, - envVars: [ - { - key: "MY_SERVICE_URL", - value: credentials.url, - target: ["production", "preview", "development"], - type: "encrypted", - }, - { - key: "MY_SERVICE_TOKEN", - value: credentials.token, - target: ["production", "preview", "development"], - type: "secret", - }, - ], - }), - }, - ); - - return response.json(); -} -``` +Complete the web step, then verify with `vercel env ls` and `vercel env pull .env.local --yes`. -### Integration CLI Commands +### Auto-Provisioned Environment Variables -The `vercel integration` CLI supports these subcommands: +Installing via Marketplace injects env vars into Development, Preview, and Production automatically. No `.env` editing needed. ```bash -# Discover integrations in the Marketplace catalog -vercel integration discover -vercel integration discover --category - -# Get agent-friendly setup guide -vercel integration guide -vercel integration guide --framework - -# Add (install) an integration -vercel integration add - -# List installed integrations -vercel integration list # alias: vercel integration ls - -# Check usage / billing balance -vercel integration balance - -# Open integration dashboard in browser (fallback when add redirects) -vercel integration open - -# Remove an integration -vercel integration remove +vercel env ls # see what was injected (names only) +vercel env pull .env.local --yes # sync to local ``` -> **Building integrations?** Use `npx create-vercel-integration` to scaffold, then deploy your -> integration app to Vercel normally with `vercel --prod`. Publish to the Marketplace via the -> [Vercel Partner Dashboard](https://vercel.com/docs/integrations). - -## Common Integration Categories +**Provisioning delay:** database integrations may take **1–3 minutes** to fully provision. HTTP 500 errors during this window are expected — do NOT debug connection strings or code, just wait and retry. Run `vercel env pull` again after a brief wait if needed. -| Category | Popular Integrations | Auto-Provisioned Env Vars | -| --------------------- | --------------------------------------------- | --------------------------------------- | -| Databases | Neon, Supabase, PlanetScale, MongoDB, Turso | `POSTGRES_URL`, `DATABASE_URL` | -| Cache/KV | Upstash Redis | `KV_REST_API_URL`, `KV_REST_API_TOKEN` | -| Auth | Clerk, Auth0, Descope | `CLERK_SECRET_KEY`, `AUTH0_SECRET` | -| CMS | Sanity, Contentful, Storyblok, DatoCMS | `SANITY_PROJECT_ID`, `CONTENTFUL_TOKEN` | -| Monitoring | Datadog, Sentry, Checkly, New Relic | `SENTRY_DSN`, `DD_API_KEY` | -| Payments | Stripe | `STRIPE_SECRET_KEY` | -| Feature Flags | LaunchDarkly, Statsig, Hypertune | `LAUNCHDARKLY_SDK_KEY` | -| AI Agents & Services | CodeRabbit, Braintrust, Sourcery, Chatbase | varies by integration | -| Video | Mux | `MUX_TOKEN_ID`, `MUX_TOKEN_SECRET` | -| Messaging | Resend, Knock, Novu | `RESEND_API_KEY` | -| Searching | Algolia, Meilisearch | `ALGOLIA_APP_ID`, `ALGOLIA_API_KEY` | -| Commerce | Shopify, Swell, BigCommerce | `SHOPIFY_ACCESS_TOKEN` | - -## Observability Integration Path - -Marketplace observability integrations (Datadog, Sentry, Axiom, Honeycomb, etc.) connect to Vercel's **Drains** system to receive telemetry. Understanding the data-type split is critical for correct setup. - -### Data-Type Split - -| Data Type | Delivery Mechanism | Integration Setup | -| ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **Logs** | Native drain (auto-configured by Marketplace install) | `vercel integration add ` auto-creates drain | -| **Traces** | Native drain (OpenTelemetry-compatible) | Same — auto-configured on install | -| **Speed Insights** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | -| **Web Analytics** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | - -> **Key distinction:** When you install an observability vendor via the Marketplace, it auto-configures drains for **logs and traces** only. Speed Insights and Web Analytics data require a separate, manually configured drain pointing to a custom endpoint. See `⤳ skill: observability` for drain setup details. - -### Agentic Flow: Observability Vendor Setup - -Follow this sequence when setting up an observability integration: - -#### 1. Pick Vendor +### Managing Integrations ```bash -# Discover observability integrations -vercel integration discover --category monitoring - -# Get setup guide for chosen vendor -vercel integration guide datadog +vercel integration list # resources for current project +vercel integration list --all # all team resources +vercel integration installations # team-level installations +vercel integration balance # billing balance (prepayment integrations) +vercel integration update --plan pro +vercel integration update --projects all +vercel integration remove --yes # uninstall ``` -#### 2. Install Integration - -```bash -# Install — auto-provisions env vars and creates log/trace drains -vercel integration add datadog -``` +### Resource Management -#### 3. Verify Drain Created +For per-resource operations after install: ```bash -# Confirm drain was auto-configured -curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \ - "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}' +vercel integration resource connect [project] +vercel integration resource disconnect --all --yes +vercel integration resource remove --disconnect-all --yes +vercel integration resource create-threshold ``` -Check the response for a drain pointing to the vendor's ingestion endpoint. If no drain appears, the integration may need manual drain setup — see `⤳ skill: observability` for REST API drain creation. +Short alias: `vc ir `. -#### 4. Validate Endpoint +## Operational Rules -```bash -# Send a test payload to the drain -curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ - "https://api.vercel.com/v1/drains//test?teamId=$TEAM_ID" -``` +- **Prefer the Marketplace path over provider CLIs.** Marketplace auto-provisions env vars, manages billing through Vercel, and works without separate provider accounts. +- **Never echo secret values.** Use `vercel env ls` to verify names only. +- **For CI / non-interactive runs**, pass `--yes` for confirmations, `--format=json` for machine-readable output, and `--no-claim` for sandbox resources to avoid prompts. +- **Don't enumerate categories or integrations from memory.** Run `vercel integration categories` or `vercel integration discover` — those are the live source of truth. -Confirm the vendor dashboard shows the test event arriving. +## Unified Billing -#### 5. Smoke Log Check +Marketplace integration charges roll up to the Vercel team's invoice. Per-integration billing: ```bash -# Trigger a deployment and check logs flow through -vercel logs --follow --since 5m - -# Check integration balance to confirm data is flowing -vercel integration balance datadog +vercel integration balance ``` -Verify that logs appear both in Vercel's runtime logs and in the vendor's dashboard. +## Two Integration Types -> **For drain payload formats and signature verification**, see `⤳ skill: observability` — the Drains section covers JSON/NDJSON schemas and `x-vercel-signature` HMAC-SHA1 verification. +- **Native integrations** — full two-way integration. No provider account needed. Billing through Vercel. +- **Connectable accounts** — connect an existing third-party account; prompts you to log in to the provider during install. Env vars still auto-provisioned. -### Speed Insights + Web Analytics Drains - -For observability vendors that also want Speed Insights or Web Analytics data, configure a separate drain manually: - -```bash -# Create a drain for Speed Insights + Web Analytics -curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ - -H "Content-Type: application/json" \ - "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" \ - -d '{ - "url": "https://your-vendor-endpoint.example.com/vercel-analytics", - "type": "json", - "sources": ["lambda"], - "environments": ["production"] - }' -``` - -> **Payload schema reference:** See `⤳ skill: observability` for Web Analytics drain payload formats (JSON array of `{type, url, referrer, timestamp, geo, device}` events). - -## Decision Matrix - -| Need | Use | Why | -| ----------------------------------------- | -------------------------------------------------- | ---------------------------------------------- | -| Add a database to your project | `vercel integration add neon` | Auto-provisioned, unified billing | -| Browse available services | `vercel integration discover` | CLI-native catalog search | -| Get setup steps for an integration | `vercel integration guide --framework ` | Framework-specific, agent-friendly setup guide | -| CLI redirects to dashboard during install | `vercel integration open ` | Fallback to complete provider web flow | -| Check integration usage/cost | `vercel integration balance ` | Billing visibility per integration | -| Build a SaaS integration | Integration SDK + manifest | Full lifecycle management | -| Centralize billing | Marketplace integrations | Single Vercel invoice | -| Auto-inject credentials | Marketplace auto-provisioning | No manual env var management | -| Add observability vendor | `vercel integration add ` | Auto-creates log/trace drains | -| Export Speed Insights / Web Analytics | Manual drain via REST API | Not auto-configured by vendor install | -| Manage integrations programmatically | Vercel REST API | `/v1/integrations` endpoints | -| Test integration locally | `vercel dev` | Local development server with Vercel features | +Both use the same `vercel integration` CLI commands. ## Cross-References -- **Drain configuration, payload formats, signature verification** → `⤳ skill: observability` -- **Drains REST API endpoints** → `⤳ skill: vercel-api` -- **CLI log streaming (`--follow`, `--since`, `--level`)** → `⤳ skill: vercel-cli` -- **Safe project setup sequencing (link, env pull, then run db/dev)** → `⤳ skill:bootstrap` +- Storage (Neon, Upstash, Blob, Edge Config) → see `vercel-storage` skill +- Auth (Clerk, Auth0, Descope) → see `auth` skill +- AI providers (xAI, Fal, DeepInfra, AI Gateway) → see `ai-gateway` skill + ## Official Documentation -- [Vercel Marketplace](https://vercel.com/marketplace) -- [Building Integrations](https://vercel.com/docs/integrations) -- [Integration CLI](https://vercel.com/docs/cli/integration) -- [Integration Webhooks](https://vercel.com/docs/integrations#webhooks) -- [Environment Variables](https://vercel.com/docs/environment-variables) -- [Drains Overview](https://vercel.com/docs/drains) -- [Drains Security](https://vercel.com/docs/drains/security) +- [Vercel Marketplace docs](https://vercel.com/docs/integrations) +- [`vercel integration` CLI reference](https://vercel.com/docs/cli/integration) +- [Marketplace catalog](https://vercel.com/marketplace) From 640add07ffd84f625b4b06171fd49541475568ee Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Wed, 10 Jun 2026 18:55:20 -0700 Subject: [PATCH 2/5] fix(commands): inline drain verification in marketplace template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The marketplace command template pulled the entire "Observability Integration Path" section from the marketplace skill, which was 50+ lines of vendor data-type tables and a 4-step setup flow — most of which the template's Step 7 didn't need. The simplified marketplace skill (this PR) removed that section, breaking the include resolver. Inline only what Step 7 actually uses: the drain verification curl command and the logs/traces vs Speed-Insights/Web-Analytics distinction. Regenerate commands/marketplace.md and build-from-skills manifest. --- commands/marketplace.md | 86 +---------------------- commands/marketplace.md.tmpl | 11 ++- generated/build-from-skills.manifest.json | 16 +---- generated/skill-manifest.json | 2 +- 4 files changed, 15 insertions(+), 100 deletions(-) diff --git a/commands/marketplace.md b/commands/marketplace.md index 304d696..2fae56c 100644 --- a/commands/marketplace.md +++ b/commands/marketplace.md @@ -138,96 +138,16 @@ Ask the user for confirmation before writing files. ### 7. Verify Drain (Observability Integrations) - -Marketplace observability integrations (Datadog, Sentry, Axiom, Honeycomb, etc.) connect to Vercel's **Drains** system to receive telemetry. Understanding the data-type split is critical for correct setup. - -### Data-Type Split - -| Data Type | Delivery Mechanism | Integration Setup | -| ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| **Logs** | Native drain (auto-configured by Marketplace install) | `vercel integration add ` auto-creates drain | -| **Traces** | Native drain (OpenTelemetry-compatible) | Same — auto-configured on install | -| **Speed Insights** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | -| **Web Analytics** | Custom drain endpoint only | Requires manual drain creation via REST API or Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) | - -> **Key distinction:** When you install an observability vendor via the Marketplace, it auto-configures drains for **logs and traces** only. Speed Insights and Web Analytics data require a separate, manually configured drain pointing to a custom endpoint. See `⤳ skill: observability` for drain setup details. - -### Agentic Flow: Observability Vendor Setup - -Follow this sequence when setting up an observability integration: - -#### 1. Pick Vendor - -```bash -# Discover observability integrations -vercel integration discover --category monitoring - -# Get setup guide for chosen vendor -vercel integration guide datadog -``` - -#### 2. Install Integration +Observability vendors installed via the Marketplace auto-create drains for **logs and traces only**. Speed Insights and Web Analytics need manual drain setup via the Dashboard or REST API. ```bash -# Install — auto-provisions env vars and creates log/trace drains -vercel integration add datadog -``` - -#### 3. Verify Drain Created - -```bash -# Confirm drain was auto-configured +# Confirm a drain was auto-configured for the vendor curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \ "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}' ``` -Check the response for a drain pointing to the vendor's ingestion endpoint. If no drain appears, the integration may need manual drain setup — see `⤳ skill: observability` for REST API drain creation. - -#### 4. Validate Endpoint - -```bash -# Send a test payload to the drain -curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ - "https://api.vercel.com/v1/drains//test?teamId=$TEAM_ID" -``` - -Confirm the vendor dashboard shows the test event arriving. - -#### 5. Smoke Log Check - -```bash -# Trigger a deployment and check logs flow through -vercel logs --follow --since 5m - -# Check integration balance to confirm data is flowing -vercel integration balance datadog -``` - -Verify that logs appear both in Vercel's runtime logs and in the vendor's dashboard. - -> **For drain payload formats and signature verification**, see `⤳ skill: observability` — the Drains section covers JSON/NDJSON schemas and `x-vercel-signature` HMAC-SHA1 verification. - -### Speed Insights + Web Analytics Drains - -For observability vendors that also want Speed Insights or Web Analytics data, configure a separate drain manually: - -```bash -# Create a drain for Speed Insights + Web Analytics -curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ - -H "Content-Type: application/json" \ - "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" \ - -d '{ - "url": "https://your-vendor-endpoint.example.com/vercel-analytics", - "type": "json", - "sources": ["lambda"], - "environments": ["production"] - }' -``` - -> **Payload schema reference:** See `⤳ skill: observability` for Web Analytics drain payload formats (JSON array of `{type, url, referrer, timestamp, geo, device}` events). - - **Drain present** → Proceed to health check. -- **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard or REST API. +- **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) or REST API. - **Drain errored** → Check the drain status in the Vercel Dashboard. Common fixes: endpoint URL typo, auth header missing, endpoint not accepting POST. ### 8. Run Local Health Check diff --git a/commands/marketplace.md.tmpl b/commands/marketplace.md.tmpl index 9ed1077..2fae56c 100644 --- a/commands/marketplace.md.tmpl +++ b/commands/marketplace.md.tmpl @@ -138,11 +138,16 @@ Ask the user for confirmation before writing files. ### 7. Verify Drain (Observability Integrations) - -{{include:skill:marketplace:Observability Integration Path}} +Observability vendors installed via the Marketplace auto-create drains for **logs and traces only**. Speed Insights and Web Analytics need manual drain setup via the Dashboard or REST API. + +```bash +# Confirm a drain was auto-configured for the vendor +curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \ + "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}' +``` - **Drain present** → Proceed to health check. -- **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard or REST API. +- **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) or REST API. - **Drain errored** → Check the drain status in the Vercel Dashboard. Common fixes: endpoint URL typo, auth header missing, endpoint not accepting POST. ### 8. Run Local Health Check diff --git a/generated/build-from-skills.manifest.json b/generated/build-from-skills.manifest.json index 60108cb..a07dbfe 100644 --- a/generated/build-from-skills.manifest.json +++ b/generated/build-from-skills.manifest.json @@ -1,6 +1,6 @@ { "version": 1, - "generatedAt": "2026-05-19T03:50:38.812Z", + "generatedAt": "2026-06-11T01:55:09.119Z", "templates": [ { "template": "agents/ai-architect.md.tmpl", @@ -290,18 +290,8 @@ { "template": "commands/marketplace.md.tmpl", "output": "commands/marketplace.md", - "dependencies": [ - "marketplace" - ], - "includes": [ - { - "marker": "{{include:skill:marketplace:Observability Integration Path}}", - "skillName": "marketplace", - "target": "Observability Integration Path", - "type": "section", - "lineNumber": 142 - } - ] + "dependencies": [], + "includes": [] }, { "template": "commands/status.md.tmpl", diff --git a/generated/skill-manifest.json b/generated/skill-manifest.json index c1e1217..ac9ec78 100644 --- a/generated/skill-manifest.json +++ b/generated/skill-manifest.json @@ -1,5 +1,5 @@ { - "generatedAt": "2026-06-11T01:51:43.238Z", + "generatedAt": "2026-06-11T01:55:09.087Z", "version": 2, "skills": { "vercel-agent": { From c92530e5e521c6b6e3127eade773bf873e4fc038 Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Wed, 10 Jun 2026 18:56:29 -0700 Subject: [PATCH 3/5] test(build-from-skills): regenerate snapshots after marketplace skill changes --- .../build-from-skills-integration.test.ts.snap | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/tests/__snapshots__/build-from-skills-integration.test.ts.snap b/tests/__snapshots__/build-from-skills-integration.test.ts.snap index 7f24c06..3205a08 100644 --- a/tests/__snapshots__/build-from-skills-integration.test.ts.snap +++ b/tests/__snapshots__/build-from-skills-integration.test.ts.snap @@ -47,10 +47,8 @@ exports[`dependency manifest manifest dependency snapshot 1`] = ` "template": "commands/env.md.tmpl", }, { - "dependencies": [ - "marketplace", - ], - "includeCount": 1, + "dependencies": [], + "includeCount": 0, "template": "commands/marketplace.md.tmpl", }, { @@ -106,9 +104,9 @@ exports[`CLI --json output shape --json output shape snapshot 1`] = ` "template": "commands/env.md", }, { - "dependencyCount": 1, + "dependencyCount": 0, "diagnosticCount": 0, - "resolvedCount": 1, + "resolvedCount": 0, "status": "unchanged", "template": "commands/marketplace.md", }, From ca4d37faecc5fd5990a86bbdc7dbb47612706e30 Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Thu, 11 Jun 2026 13:54:20 -0700 Subject: [PATCH 4/5] docs(marketplace): apply PR #99 review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address inline review comments from @bhrigu123 on the marketplace simplification PR: - Clarify "repo" → "local directory linked to a Vercel project" (preflight) - Drop "(rare — usually narrow with --category)" qualifier - Use "query" instead of "name" for discover substring search - Restore concrete `vercel integration guide` examples and clarify `` - Drop ".env.local" filename from `vercel env pull` (CLI default) - Remove inaccurate 1–3 minute provisioning-delay note - Clarify Connectable accounts require browser/Dashboard setup, not CLI - Restore data-type split table + Speed Insights drain example in /marketplace Co-Authored-By: Claude Opus 4.7 (1M context) --- commands/marketplace.md | 28 +++++++++++++++++++++++++--- commands/marketplace.md.tmpl | 28 +++++++++++++++++++++++++--- skills/marketplace/SKILL.md | 26 +++++++++++++------------- 3 files changed, 63 insertions(+), 19 deletions(-) diff --git a/commands/marketplace.md b/commands/marketplace.md index 2fae56c..4b658d5 100644 --- a/commands/marketplace.md +++ b/commands/marketplace.md @@ -114,7 +114,7 @@ Check that each variable name listed in the guide appears in the output. **Never - If local env sync was disabled or `.env.local` is stale, run: ```bash -vercel env pull .env.local --yes +vercel env pull --yes ``` - **All present** → Proceed to code changes. @@ -140,12 +140,34 @@ Ask the user for confirmation before writing files. Observability vendors installed via the Marketplace auto-create drains for **logs and traces only**. Speed Insights and Web Analytics need manual drain setup via the Dashboard or REST API. +| Data Type | Auto-configured by install? | How to set up | +| ------------------ | --------------------------- | -------------------------------------------------------------- | +| **Logs** | Yes | `vercel integration add ` | +| **Traces** | Yes | Same — auto-configured on install | +| **Speed Insights** | No | Manual drain via REST API or Dashboard (`/~/settings/log-drains`) | +| **Web Analytics** | No | Manual drain via REST API or Dashboard (`/~/settings/log-drains`) | + +Confirm the auto-created drain landed: + ```bash -# Confirm a drain was auto-configured for the vendor curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \ "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}' ``` +For Speed Insights / Web Analytics, create a drain manually: + +```bash +curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ + -H "Content-Type: application/json" \ + "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" \ + -d '{ + "url": "https://your-vendor-endpoint.example.com/vercel-analytics", + "type": "json", + "sources": ["lambda"], + "environments": ["production"] + }' +``` + - **Drain present** → Proceed to health check. - **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) or REST API. - **Drain errored** → Check the drain status in the Vercel Dashboard. Common fixes: endpoint URL typo, auth header missing, endpoint not accepting POST. @@ -175,7 +197,7 @@ After completing the apply-guide loop, confirm: - [ ] Integration guide was retrieved via `vercel integration guide --framework ` - [ ] Project was linked before provisioning started - [ ] All required environment variables are provisioned on Vercel -- [ ] Local env sync is up to date (auto-sync succeeded or `vercel env pull .env.local --yes` ran) +- [ ] Local env sync is up to date (auto-sync succeeded or `vercel env pull --yes` ran) - [ ] SDK package installed without errors - [ ] Code changes applied and match the guide's patterns - [ ] For observability integrations: drain verified and test payload received diff --git a/commands/marketplace.md.tmpl b/commands/marketplace.md.tmpl index 2fae56c..4b658d5 100644 --- a/commands/marketplace.md.tmpl +++ b/commands/marketplace.md.tmpl @@ -114,7 +114,7 @@ Check that each variable name listed in the guide appears in the output. **Never - If local env sync was disabled or `.env.local` is stale, run: ```bash -vercel env pull .env.local --yes +vercel env pull --yes ``` - **All present** → Proceed to code changes. @@ -140,12 +140,34 @@ Ask the user for confirmation before writing files. Observability vendors installed via the Marketplace auto-create drains for **logs and traces only**. Speed Insights and Web Analytics need manual drain setup via the Dashboard or REST API. +| Data Type | Auto-configured by install? | How to set up | +| ------------------ | --------------------------- | -------------------------------------------------------------- | +| **Logs** | Yes | `vercel integration add ` | +| **Traces** | Yes | Same — auto-configured on install | +| **Speed Insights** | No | Manual drain via REST API or Dashboard (`/~/settings/log-drains`) | +| **Web Analytics** | No | Manual drain via REST API or Dashboard (`/~/settings/log-drains`) | + +Confirm the auto-created drain landed: + ```bash -# Confirm a drain was auto-configured for the vendor curl -s -H "Authorization: Bearer $VERCEL_TOKEN" \ "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" | jq '.[] | {id, url, type, sources}' ``` +For Speed Insights / Web Analytics, create a drain manually: + +```bash +curl -X POST -H "Authorization: Bearer $VERCEL_TOKEN" \ + -H "Content-Type: application/json" \ + "https://api.vercel.com/v1/drains?teamId=$TEAM_ID" \ + -d '{ + "url": "https://your-vendor-endpoint.example.com/vercel-analytics", + "type": "json", + "sources": ["lambda"], + "environments": ["production"] + }' +``` + - **Drain present** → Proceed to health check. - **No drain found** → Integration may not auto-configure drains. Create one manually via Dashboard (`https://vercel.com/dashboard/{team}/~/settings/log-drains`) or REST API. - **Drain errored** → Check the drain status in the Vercel Dashboard. Common fixes: endpoint URL typo, auth header missing, endpoint not accepting POST. @@ -175,7 +197,7 @@ After completing the apply-guide loop, confirm: - [ ] Integration guide was retrieved via `vercel integration guide --framework ` - [ ] Project was linked before provisioning started - [ ] All required environment variables are provisioned on Vercel -- [ ] Local env sync is up to date (auto-sync succeeded or `vercel env pull .env.local --yes` ran) +- [ ] Local env sync is up to date (auto-sync succeeded or `vercel env pull --yes` ran) - [ ] SDK package installed without errors - [ ] Code changes applied and match the guide's patterns - [ ] For observability integrations: drain verified and test payload received diff --git a/skills/marketplace/SKILL.md b/skills/marketplace/SKILL.md index 371c83b..33d1a5e 100644 --- a/skills/marketplace/SKILL.md +++ b/skills/marketplace/SKILL.md @@ -61,7 +61,7 @@ When the user asks you to build, create, scaffold, or describe an app — even c ### Linked project preflight -Integration provisioning is project-scoped. Verify the repo is linked before any `add`/`connect`: +Integration provisioning is project-scoped. Verify the local directory is linked to a Vercel project before any `add`/`connect`: ```bash test -f .vercel/project.json && echo "Linked" || vercel link @@ -85,11 +85,11 @@ vercel integration discover --category commerce --category payments --category a vercel integration discover -c storage -c ai # Server-side union: returns integrations matching ANY listed category. -# Specific integration by name (substring search across slug/name/description) +# Specific integration by query (substring search across slug/name/description) vercel integration discover postgres vercel integration discover sentry -# Full catalog (rare — usually narrow with --category) +# Full catalog vercel integration discover vercel integration discover --format=json ``` @@ -98,12 +98,16 @@ For browsing the full catalog interactively, use the [Vercel Marketplace](https: ### Getting Setup Guidance +`` is the integration slug from `vercel integration discover` (e.g. `neon`, `sentry`, `clerk`). + ```bash # Agent-friendly setup guide for a specific integration -vercel integration guide +vercel integration guide neon +vercel integration guide sentry # Framework-specific steps when available -vercel integration guide --framework +vercel integration guide neon --framework nextjs +vercel integration guide clerk --framework sveltekit ``` Supported frameworks: `nextjs`, `remix`, `astro`, `nuxtjs`, `sveltekit`. The guide returns env vars, packages, and code snippets tailored to the framework. @@ -139,7 +143,7 @@ If the CLI hands off to the dashboard for provider-specific completion, use the vercel integration open ``` -Complete the web step, then verify with `vercel env ls` and `vercel env pull .env.local --yes`. +Complete the web step, then verify with `vercel env ls` and `vercel env pull --yes`. ### Auto-Provisioned Environment Variables @@ -147,11 +151,9 @@ Installing via Marketplace injects env vars into Development, Preview, and Produ ```bash vercel env ls # see what was injected (names only) -vercel env pull .env.local --yes # sync to local +vercel env pull --yes # sync to local (defaults to .env.local) ``` -**Provisioning delay:** database integrations may take **1–3 minutes** to fully provision. HTTP 500 errors during this window are expected — do NOT debug connection strings or code, just wait and retry. Run `vercel env pull` again after a brief wait if needed. - ### Managing Integrations ```bash @@ -194,10 +196,8 @@ vercel integration balance ## Two Integration Types -- **Native integrations** — full two-way integration. No provider account needed. Billing through Vercel. -- **Connectable accounts** — connect an existing third-party account; prompts you to log in to the provider during install. Env vars still auto-provisioned. - -Both use the same `vercel integration` CLI commands. +- **Native integrations** — full two-way integration installable directly via the `vercel integration` CLI. No provider account needed. Billing through Vercel. +- **Connectable accounts** — connect an existing third-party account. **Requires manual setup via the Vercel Dashboard in the browser** — the CLI doesn't drive the auth handshake. Once connected, env vars are still auto-provisioned to the linked project. ## Cross-References From 1fde8faa1c8170aac5cd7accdf9c5d231a4375de Mon Sep 17 00:00:00 2001 From: Jathin Pranav Singaraju Date: Thu, 11 Jun 2026 14:26:08 -0700 Subject: [PATCH 5/5] =?UTF-8?q?fix(marketplace):=20correct=20category=20sl?= =?UTF-8?q?ugs=20+=20categories=20--json=20=E2=86=92=20--format=3Djson?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three correctness bugs caught in review: - `--category auth` → `--category authentication` (live /v2/integrations/categories returns "authentication"; "auth" returns 0 results). Two occurrences: skills/marketplace/SKILL.md and commands/marketplace.md.tmpl. - `--category databases` → `--category storage` (same root cause; "databases" is not a valid slug). - `vercel integration categories --json` → `--format=json` (the categories subcommand uses validateJsonOutput per vercel/vercel#16576; --json was explicitly deprecated in that PR). Co-Authored-By: Claude Opus 4.7 (1M context) --- commands/marketplace.md | 4 ++-- commands/marketplace.md.tmpl | 4 ++-- skills/marketplace/SKILL.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/commands/marketplace.md b/commands/marketplace.md index 4b658d5..8f5dd92 100644 --- a/commands/marketplace.md +++ b/commands/marketplace.md @@ -44,9 +44,9 @@ No destructive operations unless the user explicitly confirms. Package installs vercel integration discover # Filter by category -vercel integration discover --category databases +vercel integration discover --category storage vercel integration discover --category monitoring -vercel integration discover --category auth +vercel integration discover --category authentication # List integrations already installed on this project vercel integration list diff --git a/commands/marketplace.md.tmpl b/commands/marketplace.md.tmpl index 4b658d5..8f5dd92 100644 --- a/commands/marketplace.md.tmpl +++ b/commands/marketplace.md.tmpl @@ -44,9 +44,9 @@ No destructive operations unless the user explicitly confirms. Package installs vercel integration discover # Filter by category -vercel integration discover --category databases +vercel integration discover --category storage vercel integration discover --category monitoring -vercel integration discover --category auth +vercel integration discover --category authentication # List integrations already installed on this project vercel integration list diff --git a/skills/marketplace/SKILL.md b/skills/marketplace/SKILL.md index 33d1a5e..69cd6b3 100644 --- a/skills/marketplace/SKILL.md +++ b/skills/marketplace/SKILL.md @@ -74,14 +74,14 @@ If not linked, do not continue with provisioning until linking completes. ```bash # List canonical category slugs (always run this first when filtering) vercel integration categories -vercel integration categories --json +vercel integration categories --format=json # Filter discover by category vercel integration discover --category storage vercel integration discover -c ai # shorthand # Multi-category in a single command (preferred when user has multiple needs) -vercel integration discover --category commerce --category payments --category auth +vercel integration discover --category commerce --category payments --category authentication vercel integration discover -c storage -c ai # Server-side union: returns integrations matching ANY listed category.