Setup

poc-bot Setup Skill

Goal: finish with a cloned repo, a filled-in .env, and verified read-only access to HubSpot, Metabase, and Slack — so the poc-analysis and poc-not-customer-usage skills work on the next run.

Security rules for this entire skill:

• Never echo, print, or log token values. Reference them only as $VAR after they are in the environment, and let the user paste secrets directly into .env themselves whenever possible.
• Never commit .env (it is gitignored — keep it that way).

Step 0: Locate or clone the repo

Check whether you are already inside a poc-agent-oss checkout (the directory containing .agents/skills/poc-analysis/SKILL.md and .env.example). Search the current directory and its parents. If found, cd to the repo root and continue.

If not found, clone it and enter it:

git clone https://github.com/warpdotdev/poc-agent-oss.git
cd poc-agent-oss

Also confirm python3 --version is 3.8+. There are no other dependencies — every script uses the Python standard library only.

If the user wants to run poc-bot as an Oz cloud or scheduled agent (skip for purely local runs), also verify the Oz CLI:

oz whoami

• Command not found → 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.
• Not authenticated → run oz login (interactive), or for CI/headless environments export WARP_API_KEY.

Step 1: Create .env

[ -f .env ] || cp .env.example .env

An existing .env is never overwritten (and unlike cp -n, this exits 0 on all platforms when the file already exists). If .env already exists, read it and only work on the required values that are still blank or still hold .env.example placeholders (e.g. https://metabase.example.com) — this makes the skill safe to re-run to finish a partial setup.

When writing values, quote anything containing spaces (LABEL="two words") — unquoted spaces break the source .env load step.

Step 2: Determine scope and collect values

Ask the user which skill(s) they plan to run — this decides which variables are required:

• Both skills: HUBSPOT_ACCESS_TOKEN, METABASE_BASE_URL, METABASE_API_KEY, METABASE_DASHBOARD_ID, METABASE_PARAM_DATE_RANGE_ID, METABASE_PARAM_TEAM_ID_ID, POC_BOT_SLACK_TOKEN, SLACK_CHANNEL
• poc-analysis only: add HUBSPOT_POC_PIPELINE_ID, HUBSPOT_POC_STAGE_ID
• poc-not-customer-usage only: add METABASE_DB_ID, METABASE_PRIMARY_METRIC_DASHCARD_ID, METABASE_PRIMARY_METRIC_CARD_ID

.env.example is fully annotated (required vs. optional, and which skill uses what) — treat it as the source of truth for every variable and its default.

Ask the user for the credentials first (HubSpot private app token, Metabase URL + API key, Slack bot token with chat:write). Have them edit .env directly for the secrets. The IDs can then be discovered for them in Step 3.

Step 3: Discover the IDs

First load the credentials into the environment — run Step 4's source command now, and again after any later .env edit. Then you can look up every ID the user doesn't know, instead of making them hunt through UIs. Use read-only GET requests and never print the tokens:

HubSpot pipeline + stage IDs (poc-analysis):

curl -s "https://api.hubapi.com/crm/v3/pipelines/deals" \
  -H "Authorization: Bearer $HUBSPOT_ACCESS_TOKEN"

Present the pipelines and their stages by label; let the user pick the POC pipeline and the "Pilot Kicked Off" (or equivalent) stage.

Metabase dashboard parameter, dashcard, and card IDs (both skills):

curl -s "$METABASE_BASE_URL/api/dashboard/$METABASE_DASHBOARD_ID" \
  -H "x-api-key: $METABASE_API_KEY"

• parameters[] → the id of the date-range parameter (METABASE_PARAM_DATE_RANGE_ID) and the team-id parameter (METABASE_PARAM_TEAM_ID_ID)
• dashcards[] → each tile's id (dashcard_id) and card_id; for poc-not-customer-usage, ask which tile is the primary metric and set METABASE_PRIMARY_METRIC_DASHCARD_ID / METABASE_PRIMARY_METRIC_CARD_ID

Metabase database ID (poc-not-customer-usage):

curl -s "$METABASE_BASE_URL/api/database" -H "x-api-key: $METABASE_API_KEY"

The dashboard ID itself is visible in the dashboard URL: https://metabase.example.com/dashboard/<ID>-....

Write each confirmed ID into .env (IDs are not secrets, so editing them in is fine).

Step 4: Load the environment

The scripts read from the process environment — there is no dotenv auto-loader:

set -a && source .env && set +a

Re-run this after every .env edit. Remind the user they will need it in any new shell.

Step 5: Verify (read-only)

Run these checks; none of them write or post anything:

1. HubSpot: the pipelines request from Step 3 returns HTTP 200 and, for poc-analysis, contains the chosen HUBSPOT_POC_PIPELINE_ID / HUBSPOT_POC_STAGE_ID.
2. Metabase: the dashboard request from Step 3 returns HTTP 200 and its parameters array contains both configured parameter IDs.
3. Slack:

   curl -s https://slack.com/api/auth.test -H "Authorization: Bearer $POC_BOT_SLACK_TOKEN"
   

   Expect "ok": true. Note that auth.test does not prove channel access — remind the user to /invite the bot to $SLACK_CHANNEL (default #poc-bot) or posting will fail with not_in_channel.

If a check fails, show the error (never the token), help fix the value in .env, reload (Step 4), and re-check.

Step 6: Deployment-specific configuration

The repo ships with generic labels and placeholder card wiring. Point the user at what to customize for their product (details in the README's "Adapting to your product" section):

• .agents/skills/poc-analysis/config/metabase_cards.json — which dashboard cards to query and their exact parameter_mappings targets (from the Step 3 dashboard response)
• .agents/skills/poc-analysis/config/methodology.md — primary metric definition, user tier criteria, summary framing
• .agents/skills/poc-analysis/references/metabase_config.md — their dashboard's column schemas
• .agents/skills/poc-not-customer-usage/config/data_sources.json — primary-metric parameter targets plus warehouse table/column names
• Optional display vars in .env: PRIMARY_METRIC_LABEL, PRIMARY_METRIC_EMOJI

This can be deferred — the environment verification above is the blocking part of setup.

Step 7: Report and hand off

Summarize: repo location, which variables were set (names only, never values), which verification checks passed, and anything deferred from Step 6. Then offer to run a pipeline skill (poc-analysis or poc-not-customer-usage) as the first real end-to-end test.