ship-web
Skill2 starsChanged 5 months agoMITView on GitHub
Verification checklist that MUST run before declaring any web artifact (HTML, deck, page, doc) "shipped" / "live" / "done." Enforces viewport meta tag, responsive breakpoints, live-URL probe, cache-bust, format-fit. Born from the VibeSwap deck incident 2026-04-20 where viewport meta was missing and Will had to QA mobile three times before Claude caught it. Also triggers on any "deploy" / "push to vercel" / "go live" request for web artifacts.
- Commits and pushes
In this repository7 other files it gives its agents.
- classifySkill
- critical-qaSkill
- house-styleSkill
- literature-loopSkill
- marginal-contributionSkill
- md-to-pdfSkill
- trp2Skill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 10 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 26
Ask yourself: does the user have software to open the artifact I'm about to produce?
- Distinctive: line 30
If you're unsure, ask. One question beats one useless artifact.
- Very specific: line 54
Must return 1 or more. Zero = go back and add it.
- Distinctive: line 60
If the artifact will ever be viewed on a phone (answer: yes, always):
- Distinctive: line 70
Test in browser DevTools at widths: 375px (iPhone SE/15 portrait), 430px (iPhone Pro Max portrait), 768px (iPad portrait), 1280px (desktop).
- Very specific: line 100
If filename="index.html" but you deployed deck.html — the SPA rewrite caught your file.
- Very specific: line 102
If Age: 339104 or similar huge number — CDN is serving stale cache.
- Very specific: line 108
When you hand the user a URL right after deploying, append ?v=<timestamp>:
- Distinctive: line 120
If the artifact is visual and will be shared externally (decks, landing pages, paper previews):
- Distinctive: line 122
If I can launch a headless browser: render at 390×844 (iPhone) and 1280×720 (desktop), confirm nothing is cut off at either.
- Distinctive: line 123
If I can't: explicitly tell the user I haven't done a real mobile render test, and ask them to screenshot if it looks wrong.
- Distinctive: line 129
After all six steps pass, I can say "shipped" / "live" / "done" with the URL.
- Distinctive: line 131
If any step fails or is skipped, use language that invites QA:
- Distinctive: line 167
If I skip this checklist and Will catches a bug, I owe him an apology.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
ship-web — verify before shipping web artifacts
When invoked: You are about to claim (or have just claimed) that a web artifact is shipped/live/done. This skill is the gate. Do NOT skip steps.
Context: On 2026-04-20, Claude shipped a VibeSwap pitch deck to Vercel and declared it "live" three times in a row, each time missing something Will had to catch:
- First ship:
.pptx— Will couldn't open it (no PowerPoint). - Second ship: Pushed to git master — Vercel git-integration was disabled, actual deploy never ran.
- Third ship: Added mobile CSS — but forgot the viewport meta tag, so mobile Safari ignored the
@mediarules.
This skill prevents all three. Run every step before claiming "done."
Step 1 — Format-fit check (before writing anything)
Ask yourself: does the user have software to open the artifact I'm about to produce?
- For visual/layout artifacts: default to self-contained HTML unless the user explicitly asks for
.pptx/.pdf/.docx. Will has no PowerPoint. HTML +Ctrl+P → Save as PDFcovers both use cases. - For documents:
.mdor.html— never.docxunless explicitly requested. - If you're unsure, ask. One question beats one useless artifact.
Step 2 — HTML boilerplate (MUST be in every HTML file I produce)
Non-negotiable head tags:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<meta name="theme-color" content="#000000">
<title>...</title>Why the viewport meta is critical: without it, mobile Safari renders at a ~980px virtual viewport and scales the page down. Any @media (max-width: 900px) breakpoint I write will NEVER fire. Mobile CSS becomes dead code. This is the single #1 mobile-responsive blocker. It is not optional. It is not something to remember. It is part of the boilerplate.
Verification after writing:
grep -c 'name="viewport"' <file.html>Must return 1 or more. Zero = go back and add it.
Step 3 — Responsive CSS (every slide / section / page)
If the artifact will ever be viewed on a phone (answer: yes, always):
- Include a
@media (max-width: 900px)block that:- Collapses multi-column grids to single column
- Relaxes any forced
aspect-ratiothat would clip content - Sets
overflow: visibleor explicit height handling - Shrinks oversize hero typography (96px+ numbers → 48-56px)
- Moves
position: absolutefooters toposition: staticso they don't overlap content - Reduces padding (40-56px desktop → 20-28px mobile)
- Test in browser DevTools at widths: 375px (iPhone SE/15 portrait), 430px (iPhone Pro Max portrait), 768px (iPad portrait), 1280px (desktop). If DevTools isn't accessible in my flow, open the file locally and inspect structure mentally at each breakpoint.
Step 4 — Deploy verification (if shipping to Vercel / any host)
Pre-ship:
# Verify which host the domain points to (Vercel may not be the source of truth)
curl -sI "https://<domain>/" | grep -i 'server\|x-vercel'
# Verify Vercel deploy pipeline is actually live (not disabled git integration)
cd <frontend-dir> && vercel ls --yes 2>&1 | head -3
# If last deploy timestamp > 1 day old AND there have been git pushes, integration is OFF.
# Use: vercel --prod --yes to deploy manually.Post-ship — MANDATORY live probe:
curl -sI "https://<url>" | head -10Read the headers:
Content-Disposition: inline; filename="<expected-file>"← must match what you deployedContent-Length: <bytes>← should match local file sizeAge: 0or small ← confirms fresh CDN serve
If filename="index.html" but you deployed deck.html — the SPA rewrite caught your file. File isn't actually on the deploy. Go fix.
If Age: 339104 or similar huge number — CDN is serving stale cache. Either deploy actually failed, or cache invalidation is slow. Wait 60s and re-probe; if still stale, the deploy is broken.
Step 5 — Cache-bust URL for the user
When you hand the user a URL right after deploying, append ?v=<timestamp>:
https://frontend-jade-five-87.vercel.app/deck.html?v=2This forces their browser to re-fetch, bypassing any local cache that might show them the old version. On mobile especially, iOS Safari aggressively caches pages — even with Cache-Control: no-cache headers — if the tab was already open.
Step 6 — Mobile screenshot sanity check
If the artifact is visual and will be shared externally (decks, landing pages, paper previews):
- If I can launch a headless browser: render at 390×844 (iPhone) and 1280×720 (desktop), confirm nothing is cut off at either.
- If I can't: explicitly tell the user I haven't done a real mobile render test, and ask them to screenshot if it looks wrong. Don't fake the verification.
Step 7 — Honest ship claim
After all six steps pass, I can say "shipped" / "live" / "done" with the URL.
If any step fails or is skipped, use language that invites QA:
- "Draft at
<url>— please check on mobile, I haven't done a render test yet" - "Deployed but not verified — try the URL and let me know if it's cut off anywhere"
Don't claim done when you mean draft. That's the lie this whole skill exists to prevent.
Project-specific notes
VibeSwap frontend (Vercel)
- Manual deploy only — see
memory/project_vercel-manual-deploy.md - CLI command from
frontend/:vercel --prod --yes - Takes ~60-90s (upload ~30s + build ~30s)
- Production alias:
https://frontend-jade-five-87.vercel.app - Git push to master does NOT auto-deploy. Must run CLI.
Related memories (load when relevant)
memory/feedback_ship-time-verification-surface.md— the rule this skill enforcesmemory/feedback_html-over-pptx.md— default format choicememory/project_vercel-manual-deploy.md— deploy gotcha
Short form (for when I'm in a hurry)
[ ] viewport meta tag present
[ ] responsive CSS covers 375px / 768px / 1280px
[ ] deploy actually ran (vercel ls check)
[ ] curl -sI the live URL — filename matches, Age=0
[ ] give user a ?v=N cache-bust URL
[ ] if I haven't mobile-tested, say "draft" not "shipped"If I skip this checklist and Will catches a bug, I owe him an apology. If I check it and ship clean, it's one interaction not four.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

