Skip to content
Dave Klein

Deploy and verify

Download the skill2 KB

Pushes a Vercel site through its own publish path, expects the pipeline’s side effects, and confirms the deploy is live. Deploy and verify is one of the Claude Code skills I wrote for building this site, with the site-specific values turned into placeholders and examples so it works on any project. The skill is the SKILL.md below, exactly as it ships in the zip.

Install

unzip deploy-verify.zip -d ~/.claude/skills

That installs it for every project. For one project, unzip into that project’s .claude/skills/ instead. Either way, Claude Code reads the folder on its next session and applies the skill when a request matches its description:

Push a site to production through its own publish path and verify the deploy on Vercel. Encodes the rule that a deploy is a git push (never the Vercel CLI or a deploy tool), the side effects a pre-push pipeline leaves behind, the MCP verification path, and the known failure modes (a preflight that never ran, a stale webhook, bot-challenged curl, oversized functions). Invoke for any push, deploy, or "is production live?" request.

Inside the zip

  • —deploy-verify/SKILL.md · 4 KB

The skill

A production deploy is a git push to the production branch of a Vercel-connected repo. Nothing else. Not vercel deploy, not vercel --prod, not a deploy tool in an MCP server. Those bypass the repo’s own pipeline and leave production on a commit that is not on main.

Before the push

  1. Run whatever the build runs that a dev server never does. Convention checks that live in a prebuild script (a search index that must cover every page, a rule that every video carries a poster, a lint on generated files) fail on Vercel after a clean local compile. If the project has a preflight script, run it. If it does not, run the typecheck and each prebuild check by hand, and stop on the first failure. Two deploys can fail in one day on checks that took ten seconds to run locally.
  2. Know the project’s push command. Many sites wrap git push in a script that rebases onto origin first, runs publish steps, and pushes once. Use that script when it exists. A bare git push still works but can be rejected when a GitHub Action has committed to main in the meantime.

Expect the pipeline’s side effects

A pre-push or publish pipeline typically does some of the following. Do not fight it:

  • Regenerates tracked files (a changelog from the git log, commit statistics, an SEO description, optimized images) and amends them into the pushed commit.
  • Bumps the version from conventional commits (feat! or BREAKING for major, feat for minor, fix, style, chore, refactor for patch) and amends that too. The push output prints the pre-amend hash; run git fetch afterwards and expect local HEAD to differ from what the terminal printed.
  • Adds a follow-up commit of its own (chore(images): ... [skip ci] is a common shape).

For a verification build that leaves the tree alone, run the framework’s build directly (npx next build) rather than npm run build, which triggers the prebuild rewrites.

Verify the deploy

  1. list_deployments (Vercel MCP) and find the deployment for the pushed SHA. That is the post-amend SHA from git fetch, not the hash the push printed.
  2. Poll get_deployment until readyState is READY. Builds take two to three minutes. Confirm the production aliases (the apex domain and www) are attached.
  3. BUILDING for a long time, or ERROR: read the build logs (list_deployment_events, newest first) and diagnose before pushing again. The failing line is usually within the last twenty events.
  4. Check content on production through the Vercel MCP’s fetch tool or a real browser. A plain curl against a production domain behind bot protection returns a challenge page, not the site.

Known failure modes

  • The push created zero deploy records. The Vercel to GitHub webhook is stale. In the Vercel dashboard: Settings, Git, disconnect and reconnect the repository, then push a trivial commit to trigger a build.
  • “Function exceeds 250 MB.” A route reads files with fs through process.cwd(), a loop variable, or any indirection the file tracer cannot evaluate statically, so Next bundles all of public/ (or the whole repo) into every function that imports the module. Fix: import generated JSON statically, and keep every filesystem read a literal readFileSync(path.join(<constant dir>, ...)) at the call site. Do not enable the large-functions setting to hide it. Verify before pushing: build, then sum the sizes listed in .next/server/app/<route>/route.js.nft.json.
  • A prebuild check failed on Vercel that “we already check for.” Confirm the local preflight is actually called from the push script, not only described in its comments.

Report

Say which SHA is live, that the aliases are attached, and what the pipeline amended. If the deploy failed, quote the failing log line and say what you changed before the second push.