clawhubby @ranlywood

Clawhub Publish

Deploy to Vercel. Auto-activates for any Vercel task — editing a landing page, deploying, aliasing, updating a site.

view source

installs

stars

karma

SkillRank score ↗

8.2/ 10

evaluated by implexa, claude-haiku-4-5 · 2026-06-12

vercel-deploy-pro handles deployment to vercel with explicit auth flow, pre-deploy checklist, and post-deploy verification. covers file editing constraints, token management, sso removal, and common failure modes from field practice.

structure

9.0

trigger phrases

9.0

procedure

9.0

edge cases

7.0

documentation

8.0

strengths

view original SKILL.md from clawhubclick to expand

---
name: vercel-deploy
description: Deploy to Vercel. Auto-activates for any Vercel task — editing a landing page, deploying, aliasing, updating a site.
---

# Skill: Vercel Deploy

## When to activate (automatically, without prompting)

- any mention of Vercel, landing page, or site on vercel.app
- task "update site", "deploy", "fix landing"
- editing an HTML file in a project folder with `.vercel/project.json`

---

## Auth flow (before anything else)

```bash
vercel whoami 2>&1
```

**Authorized → proceed.**

**Not authorized → one-time setup:**

→ In Claude Code (has a browser):
```bash
vercel login
```

→ In OpenClaw or any headless agent:
1. Tell the user:
   > "Open vercel.com/account/tokens → Create Token → copy it and send it here. You only need to do this once."
2. Once received, verify:
```bash
export VERCEL_TOKEN=<token>
vercel whoami
```
3. Store securely — do NOT write the token to `~/.zshrc` or any file. Keep it in env for this session only, or ask the user to add it to their secrets manager.

---

## Creating or editing HTML files

**CRITICAL: Never output HTML in the response text.**

Always write directly to a file using the Write/Edit tool:
- ✅ Write tool → `index.html` → deploy
- ❌ Print HTML in response → copy-paste → deploy

Reason: large HTML files exceed the 32k output token limit and Claude hangs mid-generation. Writing to a file has no such limit.

If the file is very large (>300 lines), build it in logical sections using Edit tool rather than rewriting from scratch.

---

## Pre-deploy checklist (required)

### 1. Make ALL changes first
❌ ANTI-PATTERN: deploy after each individual edit
✅ Rule: all edits in file first → one deploy

### 2. Check for `.vercel/project.json`

```bash
ls .vercel/project.json
```

**File exists → proceed to deploy.**

**File does not exist → first deploy, Vercel will create the project automatically:**
```bash
vercel deploy --yes --prod
# Vercel creates the project and .vercel/project.json on first run
```

### 3. Verify changes are actually in the file
```bash
grep -c "expected string" index.html
```

---

## Deploy recipe

```bash
# Deploy (run from project folder)
vercel deploy --yes --prod 2>&1 | grep -E "https://|Error"

# If custom alias was not assigned automatically — set it manually:
# For personal accounts (no --scope needed):
vercel alias set <deploy-url> <alias>.vercel.app

# For team accounts only:
vercel alias set <deploy-url> <alias>.vercel.app --scope YOUR_TEAM_SCOPE
```

Note: `script -q /dev/null` suppresses interactive prompts on macOS but breaks on Linux. Use plain `vercel deploy` instead — `--yes` flag handles prompts cross-platform.

### Post-deploy verification (required)
```bash
curl -s https://<alias>.vercel.app | grep "expected string"
# 200 + expected string = ✅ done
```

---

## Removing SSO (if site is locked behind auth)

```bash
PROJECT_ID=$(python3 -c "import json; print(json.load(open('.vercel/project.json'))['projectId'])")
TOKEN=$(python3 -c "import json; print(json.load(open('$HOME/Library/Application Support/com.vercel.cli/auth.json'))['token'])")

# For personal accounts:
curl -s -X PATCH "https://api.vercel.com/v9/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ssoProtection":null,"passwordProtection":null,"trustedIps":null}'

# For team accounts — add teamId:
curl -s -X PATCH "https://api.vercel.com/v9/projects/$PROJECT_ID?teamId=YOUR_TEAM_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ssoProtection":null,"passwordProtection":null,"trustedIps":null}'
```

---

## Final output (always)

After a successful deploy, the last message to the user must be the public URL — nothing else:

```
✅ https://<alias>.vercel.app
```

---

## ❌ Anti-patterns (from practice)

| What went wrong | How to do it right |
|---|---|
| Generated HTML in response text (hit 32k token limit) | Always write HTML directly to file using Write/Edit tool |
| Deployed from home directory (wrong CWD) | Always deploy from the project folder with `.vercel/project.json` |
| Multiple deploys for separate edits | All edits → one deploy |
| Didn't verify file actually changed before deploying | `grep` before deploying |
| Didn't verify after deploy | `curl` on the live URL after every deploy |
| Used `--scope` on a personal account | `--scope` is for team accounts only |
| Used `script -q /dev/null` on Linux | Use plain `vercel deploy --yes` instead |
| Stored token in `~/.zshrc` | Keep token in env only, never write to files |
| Started with partial understanding | Read source fully first, make a diff, then apply all edits |

## Gotchas
- `--name` is deprecated — don't use it
- `vercel project rm` doesn't support `--yes` — interactive only
- `vercelAuthentication` is NOT supported in API v9 — use `ssoProtection: null`
- After `vercel deploy --prod` the default alias is assigned automatically, custom alias is not (always verify)
- First deploy on a new project: no `.vercel/project.json` yet — just run `vercel deploy --yes --prod`, it creates the project automatically

related skills

semantically similar in the cross-vendor index

skills.sh

78% match

deployments-cicd

Vercel deployment and CI/CD expert guidance. Use when deploying, promoting, rolling back, inspecting deployments, building with --prebuilt, or configuring CI…

don't have the plugin yet? install it then click "run inline in claude" again.

restructured into implexa's 6-part format with explicit inputs, procedure steps with input/output pairs, decision logic moved to dedicated section, edge cases and gotchas integrated, sso removal extracted to separate subsection, and outcome signals made measurable.

Skill: Vercel Deploy Pro

intent

deploy web projects to vercel production with zero manual setup. this skill handles auth verification, file edits, pre-deploy validation, and live URL confirmation. auto-triggers on any mention of vercel, landing page updates, site deployments, or html edits in a project with .vercel/project.json. use this whenever you need to push changes live to vercel.app or manage custom aliases.

inputs

environment:

VERCEL_TOKEN (env var, optional): personal access token from vercel.com/account/tokens. required for headless agents or if not logged in via CLI. keep in env only, never commit or write to dotfiles.
current working directory: must be the project root containing .vercel/project.json (after first deploy) or a valid vercel project.
file system access: read/write to project files and .vercel/ config directory.

external connections:

vercel cli: vercel command must be installed and callable. tested on macos and linux.
vercel api v9: used for SSO/auth removal via curl. requires valid VERCEL_TOKEN.
http access: curl required for post-deploy verification. target vercel.app domain must be publicly accessible.

context:

project id: auto-discovered from .vercel/project.json on subsequent deploys. first deploy creates this file.
team scope (if applicable): YOUR_TEAM_SCOPE required only for team accounts using --scope flag.
html/file changes: source code edited before deploy, not generated in response text.

procedure

step 1: verify auth status

run vercel whoami 2>&1 to check if cli is authenticated.

input: none (check env state) output: success message with account email or "not authenticated" error.

step 2: if not authenticated, perform one-time login

input: user's vercel account credentials or personal token.

if in claude code (has browser): run vercel login interactively.

if in headless agent or openclaw: ask user to generate a token at vercel.com/account/tokens, then set export VERCEL_TOKEN=<token> and retry vercel whoami. do not persist token to files. store in session env only or direct user to their secrets manager.

output: verified vercel whoami response confirming authentication.

step 3: check for `.vercel/project.json`

run ls .vercel/project.json from project root.

input: project filesystem. output: file exists or file not found error.

step 4: if `.vercel/project.json` does not exist (first deploy)

run vercel deploy --yes --prod 2>&1 | grep -E "https://|Error".

vercel creates .vercel/project.json automatically on first run. do not manually create it.

input: clean project folder. output: deployment url (e.g., https://project-abc123.vercel.app) and newly created .vercel/project.json.

step 5: apply all file edits

use write or edit tool to update html, config, or source files. make all changes in this step before proceeding to deploy.

anti-pattern: deploy after each individual edit. always batch edits into one deploy cycle.

input: file paths and content to write/edit. output: updated files on disk.

step 6: verify file changes are in place

run grep -c "expected string" <filename> or cat <filename> | head -20 to confirm edits were written.

input: filename and expected content string. output: grep count or file preview confirming changes exist.

step 7: deploy to production

from project root, run vercel deploy --yes --prod 2>&1 | grep -E "https://|Error".

input: updated project files, authenticated cli, .vercel/project.json present. output: deployment url printed to stdout. capture the url for next step.

step 8: assign custom alias (if needed)

if a custom alias was not assigned automatically during deploy, run the alias command based on account type.

for personal accounts:

vercel alias set <deploy-url> <alias>.vercel.app

for team accounts:

vercel alias set <deploy-url> <alias>.vercel.app --scope YOUR_TEAM_SCOPE

input: deploy-url from step 7, desired alias name, team scope (team accounts only). output: confirmation that alias was assigned.

step 9: post-deploy verification

run curl -s https://<alias>.vercel.app | grep "expected string".

input: live alias url and expected content to verify. output: http 200 response with expected string in body confirms success.

step 10: report final url

output only the public url in this format:

✅ https://<alias>.vercel.app

input: verified alias from step 9. output: single line url to user.

decision points

if vercel whoami fails (not authenticated):

in claude code: run vercel login interactively and retry.
in headless/openclaw: ask user for vercel token, set VERCEL_TOKEN env var in session, retry vercel whoami. never persist token to dotfiles or config files.

if .vercel/project.json does not exist:

first deploy scenario: run vercel deploy --yes --prod to auto-create project and config file.
subsequent deploys: this state should not occur. if it does, project was deleted or wrong directory. ask user to confirm project folder.

if deploy url has no automatic alias assigned:

run vercel alias set to assign custom domain manually.
for team accounts, include --scope YOUR_TEAM_SCOPE. for personal accounts, omit scope.

if post-deploy curl returns 404 or timeout:

wait 10-15 seconds and retry curl (vercel may still be propagating).
if persists, check that alias was correctly assigned in step 8 and that project has no SSO/password protection enabled.

if file changes don't appear in grep output (step 6):

write tool did not execute or file path is wrong.
re-run write/edit tool, confirm file path and content, then re-verify with grep or cat.
do not deploy until changes are confirmed on disk.

if site is behind SSO or password protection:

use the "removing sso" procedure (see below) to disable auth via curl to vercel api.
extract project id from .vercel/project.json and token from env.
for team accounts, append ?teamId=YOUR_TEAM_ID to api url.

output contract

success state:

final message is a single line with public vercel.app url in this format: ✅ https://<alias>.vercel.app
url is live and responds to curl with http 200 and expected content string in response body.
no token, secrets, or internal ids logged or printed.
.vercel/project.json exists in project root.

file outputs:

all edited files saved to disk in project directory.
no html, css, or js generated in response text (always write to file).

api outputs (if sso removal needed):

vercel api v9 patch request returns 200 with updated project json showing "ssoProtection": null.

outcome signal

user sees a single line: ✅ https://<alias>.vercel.app

user can immediately click the url and see the updated site live.

curl verification (step 9) confirms http 200 and expected content in response, proving deploy succeeded.

removing sso (if site is locked behind auth)

when to use: site deployment succeeded but vercel is blocking access with sso or password protection.

step 1: extract project id from config:

PROJECT_ID=$(python3 -c "import json; print(json.load(open('.vercel/project.json'))['projectId'])")

step 2: confirm vercel token is in env:

echo $VERCEL_TOKEN

if empty, ask user to provide token or re-run auth flow.

step 3: call vercel api to remove protection.

for personal accounts:

curl -s -X PATCH "https://api.vercel.com/v9/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ssoProtection":null,"passwordProtection":null,"trustedIps":null}'

for team accounts:

curl -s -X PATCH "https://api.vercel.com/v9/projects/$PROJECT_ID?teamId=YOUR_TEAM_ID" \
  -H "Authorization: Bearer $VERCEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ssoProtection":null,"passwordProtection":null,"trustedIps":null}'

step 4: verify response status is 200 and retry curl from step 9 of main procedure.

edge cases and gotchas

auth expiry: if vercel token expires mid-session, vercel whoami will fail. re-run auth flow and obtain new token. cli tokens do not refresh automatically.

rate limits: vercel api v9 allows 100 requests per minute per ip. sso removal is a single request, so unlikely to hit limit. large projects with many deployments may trigger limits on subsequent calls.

network timeouts: if curl post-deploy verification times out, vercel dns propagation may be slow (rare, usually <5 seconds). wait 15 seconds and retry. if url still times out after 30 seconds, check that deployment succeeded by running vercel inspect <alias>.

empty result sets: if grep finds zero matches in step 6, file edits did not persist or path is wrong. check file path and re-run write tool.

wrong working directory: deploy from project root only. deploying from parent or subdirectory will fail. always confirm .vercel/project.json exists in cwd before running vercel deploy.

deprecated flags: do not use --name flag (deprecated). do not use vercel project rm --yes (does not support yes flag, interactive only).

token storage: never write VERCEL_TOKEN to ~/.zshrc, ~/.bashrc, .env, or any file. keep in session env only. if user needs persistence, direct them to their secret manager (1password, github secrets, etc).

sso vs. passwordProtection: vercelAuthentication is not supported in api v9. use ssoProtection: null and passwordProtection: null separately. both must be set to null to fully unlock site.

scope flag: --scope YOUR_TEAM_SCOPE is required only for team accounts. using it on a personal account will fail with "not a team member" error.

html size limit: never output html in response text. large files (>300 lines) hit 32k output token limit and cause hang. always use write/edit tool. if file is very large, build it in logical sections using edit tool rather than rewriting from scratch.

credits: original skill by ranlywood. enriched for implexa quality standards.

Clawhub Publish

related skills

Skill: Vercel Deploy Pro

intent

inputs

procedure

step 1: verify auth status

step 2: if not authenticated, perform one-time login

step 3: check for .vercel/project.json

step 4: if .vercel/project.json does not exist (first deploy)

step 5: apply all file edits

step 6: verify file changes are in place

step 7: deploy to production

step 8: assign custom alias (if needed)

step 9: post-deploy verification

step 10: report final url

decision points

output contract

outcome signal

removing sso (if site is locked behind auth)

edge cases and gotchas

step 3: check for `.vercel/project.json`

step 4: if `.vercel/project.json` does not exist (first deploy)