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:

   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.