Vercel Deploy

Deploy any project to Vercel instantly via the claimable-preview flow. No Vercel account or CLI authentication required.

Overview

This skill automates Vercel deployments through a bundled scripts/deploy.sh script that uses Vercel's claimable deployment endpoint. The script packages the project, detects the framework, uploads it, and returns two URLs: a live Preview URL and a Claim URL to transfer ownership to a Vercel account.

What it automates:

• Project packaging into .tar.gz (excludes node_modules, .git, .env*)
• Framework detection from package.json dependencies (40+ frameworks)
• Upload to codex-deploy-skills.vercel.sh/api/deploy
• Preview URL and Claim URL retrieval

Time saved: ~5-10 minutes per deployment

Triggers

When to Run

This automation activates when the user:

• Asks to "deploy", "publish", "host", or "push live" to Vercel
• Wants a preview URL for their project
• Says to deploy a frontend, full-stack app, or static site to Vercel
• Mentions Vercel by name in a deployment context

Manual Invocation

/vercel-deploy [path]

Process

Step 1: Validate Project

Before deploying, verify the project directory exists and contains deployable content:

ls package.json 2>/dev/null || ls *.html 2>/dev/null || echo "No deployable content found"

For projects with package.json, ensure dependencies can be resolved. For static HTML projects without package.json, the script handles them natively.

Step 2: Run the Deploy Script

Execute the bundled deployment script:

bash scripts/deploy.sh [path-to-project]

The script performs these steps internally:

1. Package: Creates a staging directory, copies files (excluding node_modules, .git, .env*), and generates a .tar.gz archive
2. Detect framework: Parses package.json for known dependency signatures
3. Upload: POSTs the tarball to the deployment endpoint via curl
4. Return URLs: Extracts previewUrl and claimUrl from the JSON response

Pass a .tgz file directly to skip the packaging step:

bash scripts/deploy.sh /path/to/project.tgz

Step 3: Handle Static HTML Projects

For projects without package.json:

• Framework is set to null (Vercel serves static files)
• If exactly one .html file exists and it is not named index.html, the script renames it to index.html so Vercel serves it at the root path (/)

Step 4: Present Results

Always show both URLs to the user after a successful deployment:

Preview URL: https://skill-deploy-abc123.vercel.app
Claim URL:   https://vercel.com/claim-deployment?code=...

View your site at the Preview URL.
To transfer this deployment to your Vercel account, visit the Claim URL.

The script also outputs structured JSON to stdout for programmatic consumption:

{
  "previewUrl": "https://skill-deploy-abc123.vercel.app",
  "claimUrl": "https://vercel.com/claim-deployment?code=...",
  "deploymentId": "dpl_...",
  "projectId": "prj_..."
}

Framework Detection

The deploy script auto-detects frameworks by matching dependency names in package.json. Detection order matters -- more specific frameworks are checked first.

Static HTML projects (no package.json) use null as the framework value.

Verification

Success Indicators

• deploy.sh exits with code 0
• Output JSON contains a non-empty previewUrl field
• Preview URL is an HTTPS link matching *.vercel.app
• Claim URL is present for account transfer

Failure Handling

Escalated Network Access

The deployment requires outbound HTTPS to codex-deploy-skills.vercel.sh. When sandboxing blocks this:

The deploy needs escalated network access to reach Vercel's deployment endpoint.
Rerun with sandbox_permissions=require_escalated to proceed.

Examples

Example 1: Deploy Current Directory

User: Deploy this to Vercel

[Validates: package.json exists, detects Next.js]
[Runs: bash scripts/deploy.sh .]
→ Detected framework: nextjs
→ Deployment successful!

Preview URL: https://skill-deploy-a1b2c3.vercel.app
Claim URL:   https://vercel.com/claim-deployment?code=abc123

Your site is live at the Preview URL.
Visit the Claim URL to transfer it to your Vercel account.

Example 2: Deploy a Subdirectory

User: Deploy the frontend folder to Vercel

[Runs: bash scripts/deploy.sh ./frontend]
→ Detected framework: vite
→ Deployment successful!

Preview URL: https://skill-deploy-d4e5f6.vercel.app
Claim URL:   https://vercel.com/claim-deployment?code=def456

Example 3: Deploy Static HTML

User: Put this HTML page on Vercel

[Validates: no package.json, found page.html]
[Runs: bash scripts/deploy.sh .]
→ Renaming page.html to index.html...
→ Deployment successful!

Preview URL: https://skill-deploy-g7h8i9.vercel.app

Example 4: Deploy Pre-built Tarball

User: Deploy this tarball I already have

[Runs: bash scripts/deploy.sh /tmp/my-project.tgz]
→ Using provided tarball...
→ Deployment successful!

Preview URL: https://skill-deploy-j0k1l2.vercel.app

Safety

Idempotency

Each deployment creates a new independent preview with its own URL. Running the skill multiple times produces multiple deployments -- previous previews remain accessible.

Reversibility

Deployments are ephemeral previews. Claiming a deployment transfers it to a Vercel account where it can be deleted from the dashboard. Unclaimed previews expire automatically.

Prerequisites

Before running, ensure:

• curl is installed and available on PATH
• tar is installed for project packaging
• Network access to codex-deploy-skills.vercel.sh is available
• Project contains deployable content (package.json or HTML files)

Packaging Rules

The script excludes these paths from the deployment tarball:

• node_modules/ -- rebuilt by Vercel during build
• .git/ -- version history not needed for deploy
• .env and .env.* -- secrets must not be uploaded

Bundled References

• Vercel Project Configuration -- vercel.json settings, build overrides, and environment variables
• Troubleshooting Guide -- Common deployment failures and resolution steps