| name | gaia-preview |
| description | Use this skill whenever the user wants to see how their branch will look on the live Gaia website before merging — "preview this branch", "show me what this looks like", "deploy a preview", "trigger a design preview", "can I see the site with these changes", "preview the skill profile", "check how this renders on the site", "spin up a preview deployment". This skill dispatches a Cloudflare Worker preview deployment for the current branch via GitHub Actions — no local build tooling required. Ideal for containerized environments, design reviews, and confirming that newly curated skills or profile pages render correctly before a PR is merged to main. The preview does NOT regenerate docs; it deploys `docs/` from the branch as-is. If your change depends on regenerated Class S artifacts, run `gaia dev docs` and commit those first — the preview then reflects them.
|
Skill: gaia-preview
Dispatches a Cloudflare Worker preview deployment for the current branch. The deploy uses the branch's docs/ folder as-is — no gaia dev docs step runs on the runner — so what you see is exactly what production would serve if this branch merged.
When to use
- You've made design, layout, or content changes and want to see them live before opening a PR.
- You're working in a container or remote environment where
localhost is unavailable.
- You want to verify a newly curated skill or contributor profile renders correctly on the site.
- You've edited
docs/ files and want a sanity check before merging.
Steps
-
Push your work. Commit and push all local changes to the current branch. The workflow runs against what's on the remote, so anything uncommitted won't appear in the preview.
-
Dispatch the preview workflow. Run:
gh workflow run cf-pr-preview.yml \
--ref "$(git rev-parse --abbrev-ref HEAD)" \
-f branch="$(git rev-parse --abbrev-ref HEAD)"
The --ref selects which copy of the workflow file runs; -f branch=… is the actual branch that gets deployed. In practice these are the same value (the current branch), but the workflow's branch input is a required parameter and must be passed explicitly — omitting it makes the workflow default to main.
-
Report the run + preview URL. After dispatching:
gh run list --workflow=cf-pr-preview.yml --limit 1
Give the user the run URL from that output. The preview itself is at a stable workers.dev URL determined by wrangler.toml's name field and the account subdomain — for this project:
https://gaia-skill-tree.marco-tngsn.workers.dev/
Each successful deploy overwrites the previous one at that URL, so there's only ever one branch previewable at a time. The workers.dev URL is NOT posted as a workflow output; it's constant, and you report it directly. The deploy usually completes in under a minute (48s on the last measured run) — wait for gh run view <id> --json conclusion -q .conclusion to return success before pointing the user at the URL.
Notes
- Do not use
sync-artifacts.yml -f deploy=true. That workflow is gated on github.ref_name == default_branch and silently returns skipped in ~3 seconds on any non-main branch. It's the production release workflow, not the branch-preview workflow.
- The single-slot preview URL is a real constraint. If two people dispatch previews on different branches close together, whichever finished second is what the URL serves. Coordinate before overwriting a coworker's preview.
- The preview will NOT reflect uncommitted regen output. If your branch touches
registry/nodes/ or registry/named/ and you haven't committed the Class S artifacts (docs/graph/* — regenerated by gaia dev docs), the preview will render the stale docs. Commit the regen first.
