Skip to main content
Skills are reusable workflows an AI coding agent can invoke by name. boxd ships five of them: one for everyday CLI usage and four for “wire-it-up-once” automation (golden VM, deploy on push, per-PR previews, agent-driven fix). The agent reads a short instruction file, runs the steps, and asks you to confirm before making any changes. You get the skills two ways, depending on where your agent runs:
  • On your laptop — they ship with the boxd CLI; install once and they drive a remote golden over the API.
  • Inside a boxd VM — they’re baked into every VM image, already at ~/.claude/skills/ with nothing to install, and they drive the in-VM CLI. See Inside a VM.
Currently only Claude Code is supported. The skills install at ~/.claude/skills/ and use Claude Code’s skill format. If you’d like the same workflows packaged for another agent (Codex, Cursor, OpenCode, …), reach out and we’ll prioritize.

​
What you get

SkillSlash commandWhat it does
boxd-cli(used implicitly)Teaches the agent how to drive the external boxd CLI: create/fork/destroy machines, run commands inside them, manage proxies, mint API keys. Loaded automatically whenever the agent is asked about boxd.
boxd-setup-golden/boxd-setup-goldenProvisions a long-running “golden” boxd VM with your app installed and running. The golden becomes the fork source for per-issue agents, ephemeral previews, or any workflow that needs a warm copy of your app.
boxd-setup-preview/boxd-setup-previewOn-demand preview environments — and the shared listener the next two layer on. Comment /boxd-preview on a PR or issue and a listener on the golden forks it, syncs the fork to the right branch (hot-reloading when it can, rebuilding only when the diff needs it), and posts the *.boxd.sh URL back. Stack-agnostic — the deploy semantics live in one config file on the golden, so the same runtime serves a docker-compose monorepo or a Vite + cargo app.
boxd-setup-deploy/boxd-setup-deployDeploy-on-push, added as the sixth hook on the boxd-setup-preview listener. Every push to your default branch re-syncs the golden and redeploys it (hot-reload, or rebuild only when the diff needs it) — reusing the same listener, HMAC secret, and deploy.sh engine as previews, so they coexist on one golden. Requires boxd-setup-preview; no GHA runner, no BOXD_API_KEY.
boxd-setup-fix/boxd-setup-fixThe full agent loop, also layered on boxd-setup-preview. /boxd-fix, /boxd-preview --fix, or the boxd-fix label forks the golden, runs Claude inside the fork, then opens a PR (issue) or pushes to the existing PR branch (PR); the fork is destroyed on PR close. Reuses the preview platform’s fork/deploy machinery — it adds only the fix webhooks; Claude auth comes from the golden’s inherited login (no token to paste).

​
Install

This is the laptop path. Inside a boxd VM the skills already ship in the image — there’s nothing to install. Skip to Inside a VM.
On your laptop, all five skills ship with the boxd CLI. The same installer drops both the binary and the skills: 
curl -fsSL https://boxd.sh/downloads/cli/install.sh | sh
What lands on disk:
  • boxd-cli skill → ~/.claude/skills/boxd-cli/SKILL.md
  • boxd-setup-{golden,deploy,preview,fix} skills → ~/.claude/skills/boxd-setup-*/ (each with its own SKILL.md plus an assets/ directory of templates the agent renders during setup)
Re-run the installer any time to upgrade — it pulls the latest version of all five skills along with the CLI binary. The binary upgrade is idempotent, so this works even if only the skills changed.

​
Using a setup skill

Open your agent inside the repo you want to wire up, then invoke the slash command: 
/boxd-setup-golden
/boxd-setup-deploy
/boxd-setup-preview
/boxd-setup-fix
Each skill probes the repo’s existing state — secrets, labels, VMs, webhooks — confirms a one-line plan with you, and only then makes changes. Skills are safe to re-run: state that already exists is detected and skipped rather than overwritten.

​
What boxd-setup-preview produces

After the skill runs, commenting on a PR or issue forks the golden and posts a live *.boxd.sh URL: 
/boxd-preview  on a PR      ──► fork golden ──► sync to the PR branch ──► comment the URL
/boxd-preview  on an issue  ──► fork golden as-is (no git work) ──► comment the URL
/boxd-preview branch=<ref>  ──► fork golden ──► sync to <ref> ──► comment the URL
                                                       │
                                            PR close ──► fork destroyed
The fork syncs only what changed: source-only edits hot-reload (no rebuild), dependency/schema changes rebuild, compose/env changes recreate — picked from the diff against what the golden last served. The commands for each tier live in one config file (/etc/boxd-platform.conf) the skill fills in by detecting your stack; nothing is committed to your repo.
WhatHow
Golden VMA running golden (run /boxd-setup-golden first if you don’t have one)
Listenerwebhook(8) on the golden, exposed at hooks.<golden>.boxd.sh, verifying HMAC on every request
GitHub webhooks2 registered automatically: the /boxd-preview comment trigger and the PR-close teardown
Deploy configThe skill detects your stack (compose / npm / cargo / …), confirms the up/reload/rebuild commands with you, and writes them to the golden

​
What boxd-setup-fix produces

boxd-setup-fix layers on top of the preview platform — run /boxd-setup-preview first. It adds the agent loop, triggered three ways: 
issue/PR labeled boxd-fix  ┐
/boxd-fix comment          ├──► fork golden ──► claude runs in the fork ──► PR opened (issue) /
/boxd-preview --fix        ┘                                               push to PR branch (PR)
                                                                                  │
                                                                       reviewer merges or closes
                                                                                  │
                                                                        fork destroyed via the
                                                                        shared teardown webhook
Live updates land on the issue/PR as a comment that updates while the agent works (📖 reading LoginPage.vue → ✏️ editing → 🌐 loading the preview → 📸 capturing the screenshot). The PR opens with a before/after visual diff and a clickable preview URL on *.boxd.sh. Required pieces the skill walks you through:
WhatHow
Preview platform/boxd-setup-preview on the golden (and /boxd-setup-golden for the golden itself). Fix reuses its fork/sync/deploy/teardown wholesale.
Claude authAutomatic — no token to paste. Every boxd VM ships logged into Claude, and a fork inherits that login, so Claude runs in the fork authenticated (billed against that account’s Pro/Max/Team/Enterprise subscription). Optional: to run fixes under a different identity, claude setup-token and paste the token onto the golden at /etc/boxd-fix/claude.token (takes precedence).
GitHub webhooks3 fix webhooks registered against the repo (fix, fix-label, fix-pr-label), reusing the preview platform’s HMAC secret. The PR-close teardown is the preview platform’s shared hook.
boxd-fix labelCreated automatically.
The PR is opened (or commits are pushed) by your user account using a gh token persisted on the golden during /boxd-setup-golden — no GitHub-Actions org-level “Allow Actions to create PRs” toggle needed.

​
What boxd-setup-deploy produces

Deploy is the sixth hook on the boxd-setup-preview listener — so setup just makes the hook live and registers one push webhook. It installs no second service, picks no new port, and commits nothing to your repo. On every push to the default branch: 
push ──► hooks.<golden>.boxd.sh/hooks/deploy ──► golden-sync.sh
         git fetch + reset to <default-branch> ──► deploy.sh
deploy.sh is the same engine the preview forks use — it diffs what changed against what the golden last deployed and picks the cheapest correct action: hot-reload (source-only), rebuild (deps/schema), or recreate (compose/.env). The commands for each tier are the ones you gave /boxd-setup-preview (they live in /etc/boxd-platform.conf on the golden) — there’s no separate deploy config. The HMAC secret stays on the golden and in GitHub’s webhook config; nothing is added to your repo.

​
Manual install (if you prefer)

If you don’t want to run the CLI installer, fetch just the skills: 
mkdir -p ~/.claude/skills/boxd-cli
curl -fsSL https://boxd.sh/downloads/cli/skill.md -o ~/.claude/skills/boxd-cli/SKILL.md
curl -fsSL https://boxd.sh/downloads/cli/skills.tar.gz | tar -xz -C ~/.claude/skills
Restart Claude Code (or run /skills to refresh) and the five skills appear with autocomplete on /boxd-setup-….

​
Inside a VM

The setup skills above run on your laptop and drive a remote golden over the API. The same workflows also ship baked into every boxd VM image, for an agent working inside a VM (e.g. Claude Code on a boxd VM). They appear automatically at ~/.claude/skills/ — no install — and come in two kinds:
  • the in-VM counterparts of boxd-setup-{golden,preview,deploy,fix} (covered below), and
  • an everyday boxd skill — the in-VM counterpart of the laptop’s boxd-cli skill — that teaches the agent to drive the in-VM CLI (fork this VM, manage proxies, run commands in sibling VMs). It loads automatically whenever the agent works with boxd.
They’re much leaner, because inside the VM the agent already has root and the platform is preconfigured:
  • The current VM is the golden. boxd-setup-golden just installs and runs your app right there — no boxd new, no boxd exec.
  • The preview/fix/deploy platform is pre-baked at /opt/boxd-platform (the webhook(8) binary and systemd units ship dormant in the image). So boxd-setup-preview / -deploy / -fix skip all the staging, fetching, and installing — they fill in your repo’s config, run one local command, and register the GitHub webhooks.
The runtime is identical to the laptop skills (same listener, same deploy.sh, same hooks.<vm>.boxd.sh webhooks) — only the setup path differs (local, as the boxd user, vs. over the API). New platform versions reach in-VM agents on the next image release.
Today the in-VM skills cover golden, preview, deploy, and fix. They target Claude Code (the agent pre-installed on every VM).