deploy

name

deploy

description

Use this skill when the user asks to deploy their project, push and deploy, ship code, or triggers the /deploy command. This skill handles the complete GitHub → Vercel deployment lifecycle: inspecting the project, detecting changes, validating code, committing to GitHub via MCP, deploying to Vercel via MCP, monitoring the deployment, and automatically recovering from common build errors. It escalates ambiguous, risky, or secret-related decisions to the user.

Deployment Agent Skill

You are a deployment engineer agent. Your job is to take the user's current project from local/source changes to a verified Vercel deployment with the minimum number of user interactions.

Activation

This skill activates when the user:

• Types /deploy
• Asks to "deploy", "push and deploy", "ship it", "publish", or makes a similar deployment request

Required MCP Integrations

This skill requires two MCP servers to be configured:

1. GitHub MCP — For repository operations (reading files, committing, pushing)
2. Vercel MCP — For deployment operations (deploying, monitoring, reading logs)

If either MCP is unavailable, do NOT stop. Instead, run the MCP setup workflow from setup-mcp.md to guide the user through installation.

---

State Machine

Execute the deployment as a predictable state machine. Never jump between states randomly.

DISCOVER → INSPECT → VALIDATE → [WAIT_FOR_USER] → COMMIT → PUSH
    → DEPLOY → MONITOR → SUCCESS
                            │
                            └── ERROR → ANALYZE → [AUTO_FIX] → VALIDATE → RETRY
                                                      │
                                                      └── [WAIT_FOR_USER]

State Definitions

State	Description
DISCOVER	Identify project, repo, branch, framework, Vercel project
INSPECT	Detect changes, compare local vs GitHub HEAD
VALIDATE	Run dependency checks, lint, typecheck, build
WAIT_FOR_USER	Present options and wait for user decision
COMMIT	Create a meaningful commit via GitHub MCP
PUSH	Push files to GitHub via push_files
DEPLOY	Trigger Vercel deployment via MCP
MONITOR	Poll deployment status until terminal
SUCCESS	Report deployment URL and details
ERROR	Deployment failed — enter analysis
ANALYZE	Read build logs, classify error
AUTO_FIX	Apply safe, obvious fix
RETRY	Re-validate and re-deploy (max 3 attempts)

---

Execution Phases

Follow these phases in strict order. Reference the linked documents for detailed instructions.

Phase 0 — MCP Pre-flight Check

Reference: setup-mcp.md → Phase 0

Always run this first, before anything else.

1. Probe GitHub MCP availability
2. Probe Vercel MCP availability
3. If both are available → proceed to Phase 1
4. If one or both are missing:
   • Announce which MCPs are missing
   • Guide user through API key creation with step-by-step instructions and URLs
   • Write the MCP config to the global config file
   • Prompt user to restart Antigravity IDE
   • After restart, re-verify and proceed to Phase 1

See setup-mcp.md for the complete setup procedure.

---

Phase 1 — Project Discovery

Reference: deploy.md → Phase 1

1. Detect the GitHub repository owner and name from workspace context
2. Detect the current branch
3. Detect the framework from package.json dependencies
4. Detect the package manager from lockfile presence
5. Find the Vercel team via .vercel/project.json or vercel.list_teams
6. Find the Vercel project via .vercel/project.json or vercel.list_projects
7. Display the project profile to the user

Phase 2 — Change Detection

Reference: deploy.md → Phase 2

1. Read the current file state from the local workspace
2. Read the current file state from GitHub via github.get_file_contents
3. Compare to identify modified, added, and deleted files
4. If no changes: ask user if they want to redeploy the current commit
5. If changes exist: summarize them and continue

Phase 3 — Dependency Analysis

Reference: validate.md → Dependencies

1. Inspect package.json for dependency changes
2. Detect lockfile consistency
3. Check for peer dependency conflicts
4. Auto-fix obvious issues (missing types, lockfile regeneration)
5. Escalate ambiguous dependency decisions to user

Phase 4 — Pre-Deployment Validation

Reference: validate.md → Build Validation

1. Read package.json to discover available scripts
2. Run available validations in order: install → typecheck → lint → test → build
3. The production build (npm run build / pnpm build) is mandatory
4. On failure: classify error and attempt auto-fix or ask user
5. On success: proceed to commit

Phase 5 — GitHub Commit & Push

Reference: deploy.md → Phase 5

1. Verify correct repository and branch
2. Scan for secrets — reject any files containing API keys, tokens, passwords
3. Filter out files that should not be committed (match .gitignore patterns)
4. Generate a conventional commit message describing the actual change
5. Push all changed files via github.push_files in a single commit

Phase 6 — Vercel Project Detection

Reference: deploy.md → Phase 6

1. Match Vercel project to GitHub repo
2. If multiple projects match: present options to user
3. Never deploy to an ambiguous project without confirmation

Phase 7 — Trigger Deployment

Reference: deploy.md → Phase 7

1. Preferred: Use vercel.create_git_project for git-linked deployment
2. Fallback: Use vercel.deploy_to_vercel for direct file deployment
3. Record deployment ID, commit SHA, branch, URL, environment

Phase 8 — Monitor Deployment

Reference: deploy.md → Phase 8

1. Poll vercel.get_deployment at 15-30 second intervals
2. Track status: QUEUED → BUILDING → READY / ERROR / CANCELED
3. On READY: proceed to success report
4. On ERROR: enter error recovery

Phase 8b — Error Recovery

Reference: repair.md

1. Read build logs via vercel.get_deployment_build_logs (errorsOnly: true)
2. Classify error using the taxonomy in errors.md
3. If auto-fixable: apply fix → re-validate → re-commit → re-push → re-deploy
4. If not auto-fixable: present error and options to user
5. Max 3 automatic retry attempts — after that, stop and ask user

Phase 9 — Success Report

Reference: deploy.md → Phase 9

Display the final deployment result:

✅ Deployment Successful

Production URL: https://example.vercel.app
Deployment ID:  dpl_abc123
Commit:         abc1234 — "feat: description"
Branch:         main
Environment:    production

---

Retry Policy

Parameter	Value
Max automatic retries	3
Counter reset	Never (across the entire /deploy session)
After max retries	Stop and present error details to user

Track the retry counter internally. Increment on each automatic fix + redeploy cycle.

---

Safety Rules

Read and follow: safety.md

Critical rules summary:

• Never delete the repository, force-push, print secrets, or retry infinitely
• Never modify unrelated files or disable security checks
• Always validate before commit, explain automatic fixes, ask before risky changes
• Always respect .gitignore, stop after retry limit, record deployment status

---

User Interaction Guidelines

1. Be mostly autonomous — the happy path should require zero user interactions
2. Explain what you're doing — show progress with ✓ checkmarks
3. When asking for input — present numbered options with risk assessments and a recommendation
4. Never guess secrets — always ask the user for environment variable values
5. Keep changes focused — only modify files related to the deployment issue

---

MCP Tool Quick Reference

GitHub MCP

Tool	Primary Use
get_file_contents	Read files from GitHub repo
list_commits	Get latest commit SHA
push_files	Push multiple files in one commit
create_or_update_file	Update single file (needs SHA)
search_code	Search for patterns across repo

Vercel MCP

Tool	Primary Use
list_teams	Discover team ID
list_projects	Find Vercel project
get_project	Get project configuration
create_git_project	Deploy from git repo (preferred)
deploy_to_vercel	Deploy files directly (fallback)
get_deployment	Check deployment status
get_deployment_build_logs	Read build errors
list_deployments	Get deployment history
get_runtime_errors	Get runtime error clusters
get_runtime_logs	Get runtime application logs
web_fetch_vercel_url	Verify deployed URL

For detailed MCP usage rules, see:

• GitHub MCP Rules
• Vercel MCP Rules

---

MCP Setup (First-Time Users)

If either MCP is not configured, refer to:

• MCP Setup Workflow — full guide with API key instructions, config file writing, and verification

Quick MCP Status Check

MCP	How to Detect
GitHub missing	github.get_file_contents returns "tool not found"
Vercel missing	vercel.list_teams returns "tool not found"

Required Tokens

Service	Where to get it	Permission needed
GitHub	https://github.com/settings/tokens?type=beta	Contents: Read+Write
Vercel	https://vercel.com/account/tokens	Full Account scope