Desplegar en Vercel
Despliega cualquier proyecto en Vercel. Siempre despliega como vista previa (no producción) a menos que el usuario solicite explícitamente producción.
El objetivo es llevar al usuario a la mejor configuración a largo plazo: su proyecto vinculado a Vercel con despliegues mediante git push. Cada método a continuación intenta acercar al usuario más a ese estado.
Paso 1: Recopilar el estado del proyecto
Ejecuta las cuatro comprobaciones antes de decidir qué método usar:
# 1. Verificar si hay un remoto git
git remote get-url origin 2>/dev/null
# 2. Verificar si está vinculado localmente a un proyecto de Vercel (cualquier archivo significa vinculado)
cat .vercel/project.json 2>/dev/null || cat .vercel/repo.json 2>/dev/null
# 3. Verificar si la CLI de Vercel está instalada y autenticada
vercel whoami 2>/dev/null
# 4. Listar equipos disponibles (si está autenticado)
vercel teams list --format json 2>/dev/null
Selección de equipo
Si el usuario pertenece a varios equipos, presenta todos los slugs de equipo disponibles como una lista con viñetas y pregunta a cuál desplegar. Una vez que el usuario elija un equipo, continúa inmediatamente al siguiente paso, no pidas confirmación adicional.
Pasa el slug del equipo mediante --scope en todos los comandos posteriores de la CLI (vercel deploy, vercel link, vercel inspect, etc.):
vercel deploy [path] -y --no-wait --scope <team-slug>
Si el proyecto ya está vinculado (existe .vercel/project.json o .vercel/repo.json), el orgId en esos archivos determina el equipo, no es necesario preguntar de nuevo. Si solo hay un equipo (o solo una cuenta personal), omite la pregunta y úsalo directamente.
Acerca del directorio .vercel/: Un proyecto vinculado tiene:
.vercel/project.json: creado porvercel link(vinculación de proyecto único). ContieneprojectIdyorgId..vercel/repo.json: creado porvercel link --repo(vinculación basada en repositorio). ContieneorgId,remoteNamey un arrayprojectsque mapea directorios a IDs de proyecto de Vercel.
Cualquiera de los dos archivos significa que el proyecto está vinculado. Verifica ambos.
NO uses vercel project inspect, vercel ls o vercel link para detectar el estado en un directorio no vinculado; sin un archivo de configuración .vercel/, mostrarán un prompt interactivo (o con --yes, vincularán silenciosamente como efecto secundario). Solo vercel whoami es seguro ejecutarlo en cualquier lugar.
Paso 2: Elegir un método de despliegue
Vinculado (existe .vercel/) + tiene remoto git → Git Push
Este es el estado ideal. El proyecto está vinculado y tiene integración git.
-
Pregunta al usuario antes de hacer push. Nunca hagas push sin aprobación explícita:
Este proyecto está conectado a Vercel mediante git. Puedo hacer commit y push para activar un despliegue. ¿Quieres que continúe? -
Haz commit y push:
git add . git commit -m "deploy: <descripción de los cambios>" git pushVercel construye automáticamente desde el push. Las ramas que no son de producción obtienen despliegues de vista previa; la rama de producción (generalmente
main) obtiene un despliegue de producción. -
Recupera la URL de vista previa. Si la CLI está autenticada:
sleep 5 vercel ls --format jsonLa salida JSON tiene un array
deployments. Encuentra la entrada más reciente. Su campourles la URL de vista previa.Si la CLI no está autenticada, dile al usuario que revise el panel de Vercel o los checks de estado de commit en su proveedor git para la URL de vista previa.
Vinculado (existe .vercel/) + sin remoto git → vercel deploy
El proyecto está vinculado pero no hay repositorio git. Despliega directamente con la CLI.
vercel deploy [path] -y --no-wait
Usa --no-wait para que la CLI regrese inmediatamente con la URL del despliegue en lugar de bloquear hasta que termine la construcción (las construcciones pueden tardar). Luego verifica el estado del despliegue con:
vercel inspect <deployment-url>
Para despliegues de producción (solo si el usuario lo solicita explícitamente):
vercel deploy [path] --prod -y --no-wait
No vinculado + CLI autenticada → Vincular primero, luego desplegar
La CLI funciona pero el proyecto aún no está vinculado. Esta es la oportunidad para llevar al usuario al mejor estado.
-
Pregunta al usuario a qué equipo desplegar. Presenta los slugs de equipo del Paso 1 como una lista con viñetas. Si solo hay un equipo (o solo una cuenta personal), omite este paso.
-
Una vez seleccionado un equipo, continúa directamente a vincular. Dile al usuario lo que sucederá pero no pidas confirmación por separado:
Vinculando este proyecto al equipo <team> en Vercel. Esto creará un proyecto de Vercel para desplegar y habilitará despliegues automáticos en futuros git push. -
Si existe un remoto git, usa vinculación basada en repositorio con el alcance del equipo seleccionado:
vercel link --repo --scope <team-slug>Esto lee la URL del remoto git y la compara con proyectos existentes de Vercel que se despliegan desde ese repositorio. Crea
.vercel/repo.json. Esto es mucho más confiable quevercel link(sin--repo), que intenta coincidir por nombre de directorio y a menudo falla cuando la carpeta local y el proyecto de Vercel tienen nombres diferentes.Si no hay remoto git, recurre a la vinculación estándar:
vercel link --scope <team-slug>Esto solicita al usuario seleccionar o crear un proyecto. Crea
.vercel/project.json. -
Luego despliega usando el mejor método disponible:
- Si existe un remoto git → haz commit y push (ver método git push arriba)
- Si no hay remoto git →
vercel deploy [path] -y --no-wait --scope <team-slug>, luegovercel inspect <url>para verificar el estado
No vinculado + CLI no autenticada → Instalar, autenticar, vincular, desplegar
La CLI de Vercel no está configurada en absoluto.
-
Instala la CLI (si aún no está instalada):
npm install -g vercel -
Autentica:
vercel loginEl usuario completa la autenticación en su navegador. Si se ejecuta en un entorno no interactivo donde no es posible iniciar sesión, salta al fallback sin autenticación de abajo.
-
Pregunta a qué equipo desplegar: presenta los slugs de equipo de
vercel teams list --format jsoncomo una lista con viñetas. Si solo hay un equipo / cuenta personal, omite el paso. Una vez seleccionado, continúa inmediatamente. -
Vincula el proyecto con el alcance del equipo seleccionado (usa
--reposi existe un remoto git, de lo contrariovercel linksimple):vercel link --repo --scope <team-slug> # si existe remoto git vercel link --scope <team-slug> # si no hay remoto git -
Despliega usando el mejor método disponible (git push si existe remoto, de lo contrario
vercel deploy -y --no-wait --scope <team-slug>, luegovercel inspect <url>para verificar el estado).
Fallback sin autenticación, sandbox de claude.ai
Cuándo usarlo: Último recurso cuando la CLI no se puede instalar o autenticar en el sandbox de claude.ai. Esto no requiere autenticación. Devuelve una URL de vista previa (sitio en vivo) y una URL de reclamo (transferencia a tu cuenta de Vercel).
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh [path]
Argumentos:
path- Directorio a desplegar, o un archivo.tgz(por defecto: directorio actual)
Ejemplos:
# Desplegar directorio actual
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh
# Desplegar proyecto específico
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project
# Desplegar tarball existente
bash /mnt/skills/user/deploy-to-vercel/resources/deploy.sh /path/to/project.tgz
El script detecta automáticamente el framework desde package.json, empaqueta el proyecto (excluyendo node_modules, .git, .env), lo sube y espera a que termine la construcción.
Dile al usuario: "Tu despliegue está listo en [previewUrl]. Reclámalo en [claimUrl] para gestionar tu despliegue."
Fallback sin autenticación. Sandbox de Codex
Cuándo usarlo: En el sandbox de Codex donde la CLI puede no estar autenticada. Codex se ejecuta en un entorno sandbox por defecto; prueba la CLI primero y recurre al script de despliegue si falla la autenticación.
-
Verifica si la CLI de Vercel está instalada (no se necesita escalación para esta verificación):
command -v vercel -
Si
vercelestá instalada, intenta desplegar con la CLI:vercel deploy [path] -y --no-wait -
Si
vercelno está instalada o la CLI falla con "No existing credentials found", usa el script de fallback:skill_dir="<path-to-skill>" # Desplegar directorio actual bash "$skill_dir/resources/deploy-codex.sh" # Desplegar proyecto específico bash "$skill_dir/resources/deploy-codex.sh" /path/to/project # Desplegar tarball existente bash "$skill_dir/resources/deploy-codex.sh" /path/to/project.tgz
El script maneja la detección de framework, empaquetado y despliegue. Espera a que termine la construcción y devuelve JSON con previewUrl y claimUrl.
Dile al usuario: "Tu despliegue está listo en [previewUrl]. Reclámalo en [claimUrl] para gestionar tu despliegue."
Acceso de red escalado: Solo escala el comando de despliegue real si el sandbox bloquea la llamada de red (sandbox_permissions=require_escalated). No escale la verificación command -v vercel.
Notas específicas para agentes
Claude Code / agentes basados en terminal
Tienes acceso completo al shell. NO uses la ruta /mnt/skills/. Sigue el flujo de decisión anterior usando la CLI directamente.
Para el fallback sin autenticación, ejecuta el script de despliegue desde la ubicación de instalación de la habilidad:
bash ~/.claude/skills/deploy-to-vercel/resources/deploy.sh [path]
La ruta puede variar según dónde haya instalado la habilidad el usuario.
Entornos sandbox (claude.ai)
Es probable que no puedas ejecutar vercel login o git push. Ve directamente al fallback sin autenticación, sandbox de claude.ai.
Codex
Codex se ejecuta en un sandbox. Verifica primero si la CLI está disponible, luego recurre al script de despliegue. Ve al fallback sin autenticación. Sandbox de Codex.
Salida
Siempre muestra al usuario la URL de despliegue.
- Git push: Usa
vercel ls --format jsonpara encontrar la URL de vista previa. Si la CLI no está autenticada, dile al usuario que revise el panel de Vercel o los checks de estado de commit. - CLI deploy: Muestra la URL devuelta por
vercel deploy --no-wait. Usavercel inspect <url>para verificar el estado de la construcción e informar al usuario. - Fallback sin autenticación: Muestra tanto la URL de vista previa como la URL de reclamo:
¡Despliegue exitoso! URL de vista previa: https://my-app-abc123.vercel.app URL de reclamo: https://vercel.com/claim-deployment?code=... Visita tu sitio en la URL de vista previa. Para transferir este despliegue a tu cuenta de Vercel, visita la URL de reclamo.
No hagas curl ni consultes la URL desplegada para verificar que funciona. Solo devuelve el enlace.
Solución de problemas
Error de Egreso de Red (claude.ai)
Si el despliegue falla debido a restricciones de red en claude.ai, dile al usuario:
El despliegue falló debido a restricciones de red. Para solucionarlo:
1. Ve a https://claude.ai/settings/capabilities
2. Agrega *.vercel.com a los dominios permitidos
3. Intenta desplegar de nuevo
Acceso de Red Escalado (Codex / entornos sandbox)
Si el despliegue falla debido a problemas de red (timeouts, errores de DNS, restablecimientos de conexión) en un entorno sandbox, vuelve a ejecutarlo con permisos escalados (sandbox_permissions=require_escalated). No escale la verificación inicial de disponibilidad de la CLI, solo escala el comando de despliegue real.
Ejemplo de indicación al usuario:
El despliegue necesita acceso de red escalado para desplegar en Vercel. Puedo
volver a ejecutar el comando con permisos escalados, ¿quieres que continúe?
Fallo de Autenticación de CLI
Si vercel login o vercel deploy falla con errores de autenticación, recurre al script de despliegue sin autenticación (variante de claude.ai o Codex, según el entorno).