# Setup

> First-run setup for this repo. Clones the repo if needed (or finds an existing checkout), checks prerequisites, creates `.env` from `.env.example`, walks the user through configuring credentials for the skill groups they want, installs optional dependencies, and verifies readiness. Use when the user says "run the setup skill", "set up this agent", "set up Buzz", "get started", "configure this repo", or is clearly setting up the project for the first time.

- Skill: `warpdotdev/setup` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add warpdotdev/setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/warpdotdev/setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML, DevOps & Infra, Marketing & Growth
- Author: warpdotdev (https://skillmd.com/u/warpdotdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/warpdotdev/setup

---


# Setup

Interactive first-run setup. Goal: get the user from a fresh clone to working
skills with the least configuration possible. Only configure what they need —
every credential is optional.

## Principles

- **Never print, echo, or log secret values.** When the user needs to add a
  token, tell them which `.env` line to edit and let them paste it themselves
  (or write it via an editor step they approve). Do not cat `.env`.
- **Don't block on optional pieces.** Skills degrade gracefully; a user who
  only wants GitHub metrics should not be asked for Slack tokens.
- **Idempotent.** Safe to re-run at any time; it should report current state
  and only fill gaps.

## Workflow

### Step 0: Locate or clone the repo

All later steps run from the repo root. Determine where that is:

1. **Already inside the repo?** If the current directory (or an ancestor)
   contains both `.env.example` and `.agents/skills/setup/SKILL.md`, use that
   as the repo root — do not clone again.
2. **Repo already cloned nearby?** If a likely checkout exists (e.g.
   `./social-monitoring-agent-oss`), confirm with the user and `cd` into it.
3. **Not cloned yet?** Ask the user where to put it (default: current
   directory), then:
   ```bash
   git clone https://github.com/warpdotdev/social-monitoring-agent-oss.git
   cd social-monitoring-agent-oss
   ```

If `git` is missing, help the user install it first.

### Step 1: Verify prerequisites

Check and report (do not install anything yet):

```bash
python3 --version        # required — most scripts are stdlib-only
node --version           # optional — only for the Typefully CLI (needs 18+)
gh auth status           # optional — easiest GitHub auth for metrics skills
oz whoami                # optional — only for Oz scheduled agents / reward-triage skills
```

If `python3` is missing, stop and help the user install it first.

If `oz` is missing and the user wants Oz cloud/scheduled runs: if the
[Warp app](https://docs.warp.dev/getting-started/installation-and-setup) is
already installed, the CLI ships with it. Otherwise, prefer the standalone Oz
CLI — there is no need to install the full Warp app just for the CLI. See
[Installing the CLI](https://docs.warp.dev/reference/cli#installing-the-cli);
on macOS: `brew tap warpdotdev/warp && brew install --cask oz`. If `oz whoami`
reports not authenticated, run `oz login` (or export `WARP_API_KEY` in
CI/headless environments).

### Step 2: Create `.env`

If `.env` does not exist:

```bash
cp .env.example .env
```

`.env` is git-ignored and auto-loaded by the scripts. Never overwrite an
existing `.env`.

### Step 3: Ask what they want to use

Ask the user which capabilities they care about (multi-select), then only
configure those groups:

1. **GitHub metrics & contributor analysis** — `gh` CLI auth or a GitHub
   token, plus `GITHUB_REPO_OWNER` / `GITHUB_REPO_NAME`
2. **Slack monitoring, triage & reports** — a Slack app bot token
   (`BUZZ_SLACK_TOKEN`), channel IDs, `SLACK_WORKSPACE`
3. **Reading X/Twitter posts** — `X_API_KEY`
4. **Social scheduling via Typefully** — `TYPEFULLY_API_KEY` + Node 18+
5. **Charts in analytics reports** — Python venv with `requirements.txt`
6. **Everything else** (Luma, Google Sheets, Swag, data warehouse) — point
   them at the relevant `.env.example` sections and each skill's `SKILL.md`

For each chosen group, walk through the matching `.env.example` section:
explain where to get the credential (the comments in `.env.example` include
URLs) and which lines in `.env` to fill in. The user edits secrets themselves.

Also remind them: skill docs use placeholders like `<BRAND>`, `your-org`, and
`@your-brand` (see the Conventions section of the README) — they should set
the matching `.env` values rather than editing skill files.

### Step 4: Optional installs

Only for what the user chose:

```bash
# Charts (reaction-analytics and other chart-generating skills)
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# optimize-gif tooling (macOS)
brew install gifsicle ffmpeg gifski
```

### Step 5: Verify

Run the readiness check and show the user the report:

```bash
python3 .agents/skills/setup/scripts/check_setup.py
```

The script is read-only. It compares `.env` against `.env.example` (a value
still equal to its placeholder counts as unconfigured), probes optional CLIs,
and prints which skill groups are ready. If a group the user wanted is not
ready, loop back to Step 3 for the missing values.

### Step 6: Wrap up

Tell the user:

- Which skills are ready now, and one example prompt to try (e.g. "give me
  repo metrics" or "draft a reply to this tweet: <url>").
- That scheduled skills (daily/weekly reports) need a scheduler — cron, CI,
  or Oz scheduled agents.
- That they can re-run setup anytime by asking to "run the setup skill".

## Failure handling

- Clone fails (network, auth) → report the git error; do not retry blindly.
- `.env.example` missing → the clone is incomplete; suggest re-cloning.
- `check_setup.py` errors → report the error; do not guess at readiness.
- User declines to add a credential → mark that group as skipped and move on.