|
| 1 | +--- |
| 2 | +name: setup |
| 3 | +description: Sets up the competitive-intelligence-agent from scratch — clones the repo (or works from an existing clone), installs dependencies, configures .env credentials, authenticates GitHub and Google, and replaces codebase placeholders with the user's real values. Use when asked to "set up this agent", "run the setup skill", "deploy this agent", "configure this repo", or when a user has just cloned the repo and wants it working. |
| 4 | +--- |
| 5 | + |
| 6 | +# Setup Skill |
| 7 | + |
| 8 | +Use this skill to take a user from nothing (or a fresh clone) to a fully working PM / competitive-intelligence agent. Work through the phases in order, but skip anything that is already done — every step is idempotent. The user may only want a subset of integrations; ask early and only configure what they need, since each integration is independent. |
| 9 | + |
| 10 | +## Phase 0: Locate or clone the repo |
| 11 | + |
| 12 | +Check whether you are already inside the repo (look for `.warp/skills` and `AGENTS.md` in the current directory or a parent). If not: |
| 13 | + |
| 14 | +```bash |
| 15 | +git clone https://github.com/warpdotdev/competitive-intelligence-agent-oss.git |
| 16 | +cd competitive-intelligence-agent-oss |
| 17 | +``` |
| 18 | + |
| 19 | +If a clone already exists somewhere the user points you at, `cd` into it instead of re-cloning. Run all later commands from the repo root. |
| 20 | + |
| 21 | +## Phase 1: Check prerequisites |
| 22 | + |
| 23 | +Verify and report; offer install instructions for anything missing: |
| 24 | + |
| 25 | +- **Python 3.11+** — `python3 --version` |
| 26 | +- **GitHub CLI** — `gh --version` (needed for `analyze_customer_feedback` and report PRs) |
| 27 | +- **Warp** — the user is presumably already running the agent in Warp |
| 28 | + |
| 29 | +## Phase 2: Ask which integrations the user wants |
| 30 | + |
| 31 | +Not every skill needs every credential. Ask the user which capabilities they care about, then only configure the corresponding integrations: |
| 32 | + |
| 33 | +- **Google Workspace** (Docs, Drive, Gmail, BigQuery) → `analyze_customer_feedback`, `read/write/summarize_google_docs`, `write_prd` |
| 34 | +- **Metabase** → NPS/churn queries in `analyze_customer_feedback`, usage pulls in `answer_pricing` |
| 35 | +- **Grain** → `votc_insights` |
| 36 | +- **Notion** → `weekly_wynk`, `write_notion` |
| 37 | +- **Slack** → `post_to_slack`, `weekly_wynk` |
| 38 | +- **Warp Oz API key** → `fix_p0_issues` (spawning cloud coding agents) |
| 39 | +- **Octolens MCP** → `weekly_sentiment_analysis` |
| 40 | +- **GitHub** → issue fetching in `analyze_customer_feedback` |
| 41 | + |
| 42 | +Skills whose integrations are skipped will simply be unavailable until configured later — that's fine, say so. |
| 43 | + |
| 44 | +## Phase 3: Install Python dependencies |
| 45 | + |
| 46 | +Prefer a virtualenv — on modern macOS/Homebrew Python, bare `pip3 install` fails with an `externally-managed-environment` error: |
| 47 | + |
| 48 | +```bash |
| 49 | +python3 -m venv .venv |
| 50 | +source .venv/bin/activate |
| 51 | +pip install -r requirements.txt |
| 52 | +``` |
| 53 | + |
| 54 | +The other skills invoke scripts with `python3`, so the venv must be active in the session where skills run. Tell the user to activate it (or ask if they prefer a global/user install where their environment allows it). `.venv` should be gitignored — add it if missing. |
| 55 | + |
| 56 | +## Phase 4: Create and fill .env |
| 57 | + |
| 58 | +```bash |
| 59 | +cp -n .env.example .env |
| 60 | +``` |
| 61 | + |
| 62 | +`.env` is gitignored; never overwrite an existing one without asking. Walk the user through each variable relevant to their chosen integrations (see the comments in `.env.example` for what each is used for): |
| 63 | + |
| 64 | +- `GOOGLE_OAUTH_TOKEN` — filled in Phase 6 |
| 65 | +- `METABASE_API_KEY` |
| 66 | +- `GRAIN_TOKEN` |
| 67 | +- `NOTION_API_KEY` |
| 68 | +- `SLACK_WEBHOOK_URL` |
| 69 | +- `WARP_API_KEY` |
| 70 | +- `FEEDBACK_EMAIL` — the Gmail address feedback emails arrive at |
| 71 | +- Pricing rate variables (`SEAT_PRICE`, `USAGE_UNIT_PRICE`, etc.) — only if they want `answer_pricing`; these can also be passed as CLI flags later |
| 72 | + |
| 73 | +**Handling secrets:** never ask the user to paste secret values into the chat, and never echo them. Ask the user to edit `.env` directly (offer to open it), then confirm which variables are set by checking for non-empty values without printing them: |
| 74 | + |
| 75 | +```bash |
| 76 | +awk -F= '/^[A-Z_]+=/ {sub(/[ \t]*#.*$/,""); v=substr($0, index($0,"=")+1); gsub(/[ \t]/,"",v); print $1 "=" (v=="" ? "<empty>" : "<set>")}' .env |
| 77 | +``` |
| 78 | + |
| 79 | +Note: `SLACK_WEBHOOK_URL` and `FEEDBACK_EMAIL` ship with example values, so `<set>` for those may still mean unconfigured — confirm the user replaced `YOUR/WEBHOOK/URL` and `your-company.com`. |
| 80 | + |
| 81 | +## Phase 5: Authenticate GitHub CLI |
| 82 | + |
| 83 | +```bash |
| 84 | +gh auth status || gh auth login |
| 85 | +``` |
| 86 | + |
| 87 | +## Phase 6: Google OAuth (only if Google integrations are wanted) |
| 88 | + |
| 89 | +1. Tell the user to do this in Google Cloud Console (you cannot do it for them): |
| 90 | + - Create/select a project; enable the **Google Docs, Google Drive, Gmail, and BigQuery** APIs. |
| 91 | + - Create an **OAuth 2.0 Client ID** of type **Desktop app**. |
| 92 | + - Download the client JSON and save it as `credentials.json` in the repo root (it is gitignored). |
| 93 | +2. Then generate the token (opens a browser, writes `token.json`): |
| 94 | + |
| 95 | +```bash |
| 96 | +python3 generate_readonly_token.py |
| 97 | +``` |
| 98 | + |
| 99 | +3. For local use, scripts read `token.json` via `GOOGLE_OAUTH_TOKEN`. Tell the user to set `GOOGLE_OAUTH_TOKEN` in `.env` to the contents of `token.json` (they can do this themselves; do not print the token). For remote/cloud runs, it goes in the environment's secrets instead. |
| 100 | + |
| 101 | +## Phase 7: Replace codebase placeholders |
| 102 | + |
| 103 | +The repo ships with obvious placeholders. Ask the user for the real values relevant to their chosen integrations, then find-and-replace across the codebase (`grep -rl '<placeholder>' .` to find affected files). **Do not replace inside `README.md` or this skill (`.warp/skills/setup/`)** — those mention the placeholders as documentation and must keep them: |
| 104 | + |
| 105 | +- `YOUR_ORG/YOUR_REPO` — their GitHub org/repo (GitHub feedback, P0 fixes, WYNK) |
| 106 | +- `YOUR_PRODUCT_CHANGELOG_URL` — public changelog URL (`summarize_changelogs`) |
| 107 | +- `YOUR_PRODUCT_DOCS_URL` — public docs URL (`feature_research`) |
| 108 | +- `your-gcp-project-id` — Google Cloud project ID (Metabase clients, `set_oauth_token.sh`) |
| 109 | +- `https://your-metabase-instance.metabaseapp.com` — Metabase URL (both `metabase_client.py` files) |
| 110 | +- `METABASE_DATABASE_ID = 0` — Metabase database ID, an integer (both `metabase_client.py` files) |
| 111 | +- `your_nps_survey_responses_table` — BigQuery NPS table (`fetch_nps_data.py`) |
| 112 | +- `your_subscriptions_table` — subscriptions/churn table (`fetch_churn_data.py`) |
| 113 | +- `your_usage_events_table` — usage table + its column names (`answer_pricing/scripts/fetch_usage.py`) |
| 114 | +- `YOUR_WORKSPACE_SLUG`, `YOUR_NOTION_PARENT_PAGE_ID`, `YOUR_CONTINUOUS_PLANNING_PAGE_ID`, `YOUR_NOTION_DATA_SOURCE_ID` — Notion workspace details (`weekly_wynk/SKILL.md`) |
| 115 | +- `YOUR_OZ_ENVIRONMENT_ID` — Warp Oz cloud environment ID (`fix_p0_issues/SKILL.md`) |
| 116 | +- `your-app-client`, `your-app-server` — paths to their application repos (`fix_p0_issues`, `analyze_git_history`) |
| 117 | + |
| 118 | +Leave untouched: `YOUR_GOOGLE_DOC_ID` and `YOUR_GOOGLE_DRIVE_FOLDER_ID` — these are illustrative runtime arguments, not values to hardcode. Also leave placeholders for integrations the user skipped. |
| 119 | + |
| 120 | +If they want `answer_pricing`, also remind them to describe their pricing model in `knowledge/platform_credits.md`. |
| 121 | + |
| 122 | +## Phase 8: Verify |
| 123 | + |
| 124 | +Run lightweight checks for the configured integrations and report a checklist of what works and what's still pending: |
| 125 | + |
| 126 | +- Python imports: `python3 -c "import googleapiclient, google.cloud.bigquery, requests"` |
| 127 | +- GitHub: `gh auth status` |
| 128 | +- Google token exists: `test -f token.json` |
| 129 | +- `.env` variables set (using the non-revealing awk check from Phase 4) |
| 130 | +- Remaining placeholders: `grep -rn "YOUR_ORG/YOUR_REPO\|your-gcp-project-id\|your-metabase-instance" .warp --exclude-dir=setup` — expected to be empty for configured integrations |
| 131 | + |
| 132 | +Finish with a short summary: which skills are ready to use, which are unconfigured, and one or two example prompts to try (e.g. "Analyze customer feedback for the last 7 days"). |
0 commit comments