agentleFS
socai-iosocai-io/socai/.claude/skills/socai-site-deployment/SKILL.md

socai-site-deployment

Skill257 starsChanged 50 days agoApache-2.0View on GitHub

Deploy, configure, troubleshoot, and verify the socai marketing/download website on Vercel. Use for socai.io deployments, Vercel project settings, domain/redirect checks, Git preview setup, /download and /github redirect validation, and deployment runbooks for the site/ Astro app.

  • Installs packages

The file

Show its rules and text

We split this skill into the rules it gives an agent

16 rules. About 0 are common, 10 are distinctive, and 6 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.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this skill whenever the task involves the socai website deployment, Vercel configuration, socai.io, www.socai.io, /download, /github, …

    line 8
  2. Very specific:

    Use the socai-d83824c8 scope for all Vercel project/domain commands.

    line 38
  3. Distinctive:

    Do not deploy from the wrong Vercel team or a personal project.

    line 39
  4. Very specific:

    Do not commit site/.vercel/, site/dist/, site/.astro/, or site/node_modules/.

    line 40
  5. Distinctive:

    Do not enable analytics unless the user explicitly approves it.

    line 41
  6. Distinctive:

    Do not edit app release assets while doing website deployment work.

    line 42
  7. Distinctive:

    Keep issue work on a dedicated branch and open/update a PR for repo changes.

    line 43
  8. Distinctive:

    If you temporarily change Vercel project settings for a manual deploy, restore them before finishing.

    line 44
  9. Distinctive:

    Before deploying or opening a PR for deployment-related code/config:

    line 48
  10. Distinctive:

    Verify production URLs with the commands below.

    line 87
  11. Distinctive:

    After the deploy, confirm the root directory was restored:

    line 128
  12. Very specific:

    Do not leave the project with Root Directory .

    line 134
  13. Distinctive:

    Use HEAD checks first:

    line 138
  14. Very specific:

    Use -L only when you want to follow the chain:

    line 160
  15. Very specific:

    Ensure the latest production deployment includes the host redirect in site/vercel.json, then redeploy.

    line 205
  16. Distinctive:

    When reporting a deployment task, include:

    line 217

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

socai site deployment

Use this skill whenever the task involves the socai website deployment, Vercel configuration, socai.io, www.socai.io, /download, /github, or PR preview deployments.

This skill is the source-of-truth deployment runbook. ../../../docs/website-deployment.md intentionally stays brief and points back here to avoid duplicate instructions drifting.

Project context

  • Website source: site/
  • Framework: Astro static site
  • Vercel team/scope: socai-d83824c8 (socai)
  • Vercel project: socai-site
  • Production domain: https://socai.io
  • Documentation route: https://socai.io/docs/ (Starlight pages built with the Astro site)
  • Canonical host: socai.io
  • www behavior: https://www.socai.io/* should 308/redirect to https://socai.io/*
  • Download route: https://socai.io/download redirects to the latest universal macOS DMG on the socai OSS release mirror
  • GitHub route: https://socai.io/github redirects to https://github.com/socai-io/socai

Expected Vercel project settings:

SettingValue
Framework presetAstro
Root directorysite
Install commandpnpm install
Build commandpnpm build
Output directorydist
Node.js version24.x

Safety rules

  • Use the socai-d83824c8 scope for all Vercel project/domain commands.
  • Do not deploy from the wrong Vercel team or a personal project.
  • Do not commit site/.vercel/, site/dist/, site/.astro/, or site/node_modules/.
  • Do not enable analytics unless the user explicitly approves it.
  • Do not edit app release assets while doing website deployment work.
  • Keep issue work on a dedicated branch and open/update a PR for repo changes.
  • If you temporarily change Vercel project settings for a manual deploy, restore them before finishing.

Local validation

Before deploying or opening a PR for deployment-related code/config:

cd site
pnpm install
pnpm build

Validate JSON/XML config when touched:

python3 -m json.tool site/vercel.json >/dev/null
python3 -m json.tool site/public/site.webmanifest >/dev/null
python3 - <<'PY'
import xml.etree.ElementTree as ET
ET.parse('site/dist/sitemap-index.xml')
ET.parse('site/dist/sitemap-0.xml')
PY

Inspect Vercel state

vercel whoami
vercel teams ls
vercel projects ls --scope socai-d83824c8
vercel project inspect socai-site --scope socai-d83824c8 --yes
vercel domains inspect socai.io --scope socai-d83824c8
vercel domains inspect www.socai.io --scope socai-d83824c8

Confirm project settings show root directory site, framework Astro, build command pnpm build, output dist, install pnpm install.

Preferred production deployment

Preferred path after Git integration is enabled:

  1. Merge website changes to main.
  2. Let Vercel build the socai-site project from root directory site.
  3. Verify production URLs with the commands below.

PR previews also require Git integration to be connected in the Vercel dashboard.

Emergency/manual CLI production deployment

Because the Vercel project is configured with root directory site, a direct local deploy from site/ can fail with site/site root-directory errors. If Git integration is not available and a CLI deploy is required, use this temporary-root workaround and restore root directory afterward.

set -euo pipefail

cat > /tmp/vercel-root-null.json <<'EOF'
{
  "rootDirectory": null
}
EOF
cat > /tmp/vercel-root-site.json <<'EOF'
{
  "rootDirectory": "site"
}
EOF

restore_root() {
  vercel api /v10/projects/socai-site \
    --scope socai-d83824c8 \
    -X PATCH \
    --input /tmp/vercel-root-site.json \
    --silent || true
}
trap restore_root EXIT

vercel api /v10/projects/socai-site \
  --scope socai-d83824c8 \
  -X PATCH \
  --input /tmp/vercel-root-null.json \
  --silent

cd site
vercel deploy --prod --scope socai-d83824c8 --project socai-site --yes

After the deploy, confirm the root directory was restored:

vercel project inspect socai-site --scope socai-d83824c8 --yes

Do not leave the project with Root Directory . or null; Git previews depend on site.

URL verification

Use HEAD checks first:

curl -I https://socai.io/
curl -I https://socai.io/docs/
curl -I https://socai.io/docs/quickstart/
curl -I https://www.socai.io/
curl -I https://socai.io/sitemap.xml
curl -I https://socai.io/sitemap-index.xml
curl -I https://socai.io/download
curl -I https://socai.io/github

Expected first-hop behavior:

  • https://socai.io/ returns 200.
  • https://socai.io/docs/ returns 200, and a nested page such as /docs/quickstart/ returns 200.
  • https://www.socai.io/ returns 308 with location: https://socai.io/.
  • https://socai.io/sitemap.xml permanently redirects to /sitemap-index.xml, which returns 200.
  • https://socai.io/download returns a Vercel redirect (307) to the latest universal macOS DMG on the configured OSS release mirror.
  • https://socai.io/github returns a Vercel redirect (307) to https://github.com/socai-io/socai.

Use -L only when you want to follow the chain:

curl -I -L --max-time 30 -o /dev/null -w 'code=%{http_code}\nfinal=%{url_effective}\n' https://socai.io/download

Git preview setup

Try:

cd site
vercel link --yes --scope socai-d83824c8 --project socai-site
vercel git connect https://github.com/socai-io/socai --scope socai-d83824c8

If Vercel returns:

Failed to link socai-io/socai. You need to add a Login Connection to your GitHub account first.

then a Vercel/GitHub account owner must connect the GitHub login/integration in the Vercel dashboard, then connect socai-site to socai-io/socai with root directory site.

Troubleshooting

Website changes skipped after a multi-commit push

The ignored build step in site/vercel.json must compare HEAD against VERCEL_GIT_PREVIOUS_SHA (the last successful deployment for this project and branch), not HEAD^. The final commit in a push can change only Rust code while earlier commits change the website. If the previous deployment SHA is missing or unavailable in the shallow clone, build rather than skip. Exit 0 skips a build; exit 1 proceeds.

Root Directory "site" does not exist

This usually happens when running local CLI deploy from site/ while the remote project also has root directory site. Use the emergency/manual CLI deployment workaround above, or prefer Git deployments.

Too many files uploaded

Deploying from the repo root can include Rust/Python build artifacts and exceed Vercel's file count. Do not deploy the repo root directly unless you have a tested ignore/archive strategy. Prefer Git deployments or the emergency/manual deploy from site/ with temporary root reset.

www.socai.io serves 200 instead of redirecting

Ensure the latest production deployment includes the host redirect in site/vercel.json, then redeploy. Verify with:

curl -I https://www.socai.io/

GitHub latest release metadata is unavailable

The website should still show generic non-stale copy (latest release) and /download should still redirect to GitHub's latest release asset.

Reporting back

When reporting a deployment task, include:

  • Branch/PR if repo files changed
  • Vercel project settings confirmed
  • Deployment URL and production domain
  • Commands run
  • Verification output summary for /, /docs/, /docs/quickstart/, www, /download, and /github
  • Any remaining manual blockers, especially Git integration / PR previews

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.