# Install the Roxels `/run-roxels` skill for Claude Code

Paste this whole file into Claude Code (or tell it: *"follow https://app.roxels.ai/skills/run-roxels/install.md"*). Claude will set everything up, asking you a few questions along the way.

> **Claude — you are installing a Claude Code skill for the user. Do the steps below in order. Where a step says ASK, ask the user and wait for their answer before continuing. Never invent an API key. Confirm before touching `~/.claude/settings.json` (step 5).**

---

## Step 1 — Create the skill folder

```bash
mkdir -p ~/.claude/skills/run-roxels
```

## Step 2 — Download the skill files

Download each of these into `~/.claude/skills/run-roxels/`, keeping the exact filenames (note `env.example` is saved as `.env.example`):

```bash
cd ~/.claude/skills/run-roxels
for f in SKILL.md run_interview.py README.md prelaunch-hook.sh; do
  curl -fsSL "https://app.roxels.ai/skills/run-roxels/$f" -o "$f"
done
curl -fsSL "https://app.roxels.ai/skills/run-roxels/env.example" -o .env.example
chmod +x prelaunch-hook.sh
```

The script is Python standard-library only — no virtualenv, no dependencies.

## Step 3 — ASK the user two preferences (optional)

The API key is **not** asked here — on first run the skill opens a browser to sign in / sign up and connect the user's Roxels account automatically, then writes the key itself. Just capture their preferences:

1. **Language** *(optional)* — "Which language should the agent speak on calls — English (`en`), Portuguese (`pt`), or Spanish (`es`)? (Skip to let each template decide.)"
2. **Approval mode** *(optional)* — "After a call, should I show you the prompt for review before running it (the default, recommended), or execute it directly?"

## Step 4 — Write the config file (only if they chose a non-default)

If the user picked a language and/or "execute directly", write `~/.claude/skills/run-roxels/.env` with just those keys (skip the file entirely if they took both defaults — the login flow creates it):

```
ROXELS_LANGUAGE=<en|pt|es>            # only if they picked one
ROXELS_REQUIRE_APPROVAL=false         # only if they chose "execute directly"; omit for the default (approval on)
```

`ROXELS_API_KEY` is added automatically by the first-run browser login. This `.env` is gitignored and never leaves their machine.

## Step 5 — ASK before enabling instant launch (optional but recommended)

Ask: *"Want the conversation room to open the instant you type `/run-roxels` — before I even start thinking? It adds a small `UserPromptSubmit` hook to your Claude Code settings that pre-launches the script. It stays out of the way for every other prompt."*

**If yes:** read `~/.claude/settings.json` first (create `{}` if missing), then **merge** this hook in without clobbering any existing hooks or settings:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "bash ~/.claude/skills/run-roxels/prelaunch-hook.sh" }
        ]
      }
    ]
  }
}
```

Then tell the user the hook only loads on startup, so they must **restart Claude Code once** for it to take effect.

**If no:** skip it — the skill works fine without the hook (the room still opens in ~2s; the hook just removes the model-thinking delay before that).

## Step 6 — Done

Tell the user:
- Restart Claude Code once so the skill (and the hook, if added) load.
- From then on, type `/run-roxels` to start a conversation: talk (and share your screen) to dictate what you want; when you hang up, the agent's composed prompt comes back — for your review by default, or executed directly if you chose that.
- To change language or approval mode later, edit `~/.claude/skills/run-roxels/.env` (or just ask Claude to change it).