> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Reusable agent workflows — install once with the boxd CLI on your laptop, or pre-baked inside every boxd VM. Invoke by name from any repo.

Skills are reusable workflows an AI coding agent can invoke by name. boxd ships six of them: one for everyday CLI usage, four for "wire-it-up-once" automation (golden VM, deploy on push, per-PR previews, agent-driven fix), and one that installs the [Hermes](https://github.com/NousResearch/hermes-agent) agent on a VM. 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](/reference/external-cli#install); [install once](#install) 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](#inside-a-vm).

<Note color="#E05A6D">
  Currently only [Claude Code](https://claude.ai/code) is supported. The skills install at `~/.claude/skills/` and use Claude Code's [skill format](https://docs.claude.com/en/docs/claude-code/skills). If you'd like the same workflows packaged for another agent (Codex, Cursor, OpenCode, …), [reach out](mailto:contact@boxd.sh) and we'll prioritize.
</Note>

## What you get

| Skill                  | Slash command         | What 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-golden`  | Provisions 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-preview` | On-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-deploy`  | Deploy-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-fix`     | The 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).                           |
| **boxd-setup-hermes**  | `/boxd-setup-hermes`  | The odd one out — it installs a **third-party agent** rather than wiring boxd into your repo. Runs the [Hermes](https://github.com/NousResearch/hermes-agent) (Nous Research) official installer on a boxd VM — a self-improving CLI agent with a built-in messaging gateway — then hands off the interactive `hermes setup` + `hermes` to you.                                                                                                                      |

## Install

<Note>
  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](#inside-a-vm).
</Note>

On your **laptop**, all six skills ship with the [`boxd` CLI](/reference/external-cli#install). The same installer drops both the binary and the skills:

```bash theme={"theme":"github-dark"}
curl -fsSL https://boxd.sh/downloads/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)
* `boxd-setup-hermes` skill → `~/.claude/skills/boxd-setup-hermes/SKILL.md` (just the instruction file — it drives Hermes' own installer, no templates)

Re-run the installer any time to upgrade — it pulls the latest version of all six 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:

```text theme={"theme":"github-dark"}
/boxd-setup-golden
/boxd-setup-deploy
/boxd-setup-preview
/boxd-setup-fix
/boxd-setup-hermes
```

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:

```text theme={"theme":"github-dark"}
/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.

| What            | How                                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Golden VM       | A running golden (run `/boxd-setup-golden` first if you don't have one)                                                                   |
| Listener        | `webhook(8)` on the golden, exposed at `hooks.<golden>.boxd.sh`, verifying HMAC on every request                                          |
| GitHub webhooks | 2 registered automatically: the `/boxd-preview` comment trigger and the PR-close teardown                                                 |
| Deploy config   | The 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:

```text theme={"theme":"github-dark"}
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:

| What             | How                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 auth      | **Automatic — 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 webhooks  | 3 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` label | Created 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:

```text theme={"theme":"github-dark"}
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.

## What `boxd-setup-hermes` produces

`boxd-setup-hermes` is the odd one out — instead of wiring boxd into a repo, it installs a **third-party agent** on a VM. [Hermes](https://github.com/NousResearch/hermes-agent) (Nous Research) is a self-improving CLI agent with a built-in messaging gateway (Telegram/Discord/Slack/WhatsApp/Signal). The skill runs Hermes' official installer on the box — Python, Node, ripgrep, ffmpeg, Playwright Chromium, and a `hermes` wrapper on PATH — then hands the interactive parts back to you:

```text theme={"theme":"github-dark"}
hermes setup     # pick an LLM provider, paste an API key
hermes           # start the agent
```

The **laptop** version creates or reuses a VM and installs Hermes over `boxd machine exec`, then gives you the `ssh <vm>.boxd` command for the interactive `hermes setup` + `hermes`. The **in-VM** version installs Hermes right on the box you're already on. Either way the skill stops at the interactive handoff — it never configures a provider or stores an API key for you.

<Note color="#E05A6D">
  Hermes is an independent project by Nous Research, not part of boxd. The skill just automates installing it on a boxd VM; optionally it can expose Hermes' always-on messaging gateway on the machine's public URL.
</Note>

## Manual install (if you prefer)

If you don't want to run the CLI installer, fetch just the skills:

```bash theme={"theme":"github-dark"}
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 six 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](/agents/claude-code)). 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),
* `boxd-setup-hermes`, which installs the [Hermes agent](https://github.com/NousResearch/hermes-agent) right on the box (no pre-baked platform needed — it just runs Hermes' official installer), 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 machine 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.

<Note color="#E05A6D">
  Today the in-VM skills cover golden, preview, deploy, fix, and hermes. They target Claude Code (the agent pre-installed on every VM).
</Note>