setup

name

setup

description

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.

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:

   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):

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 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; 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:

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:

# 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:

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: ").
• 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.