/open-geo

name: open-geo
description: Use this skill when measuring or rechecking a brand's visibility in AI answers, citations, source lists, or competitor rankings; when resuming an interrupted GEO run; or when another workflow needs captured answers and a portable measurement artifact. Use it even if the user says only “am I recommended?”, “who gets cited instead?”, or “run these questions”. Capture rendered answers through an available engine playbook, persist validated data, and export JSON; add PDF/dashboard only when requested. Accept a query CSV or a semantic-core handoff. Question research requires the separate opt-in harvest flow; this skill does not audit or edit the target website.

Purpose

Open GEO

One run = one question set, target, and engine. Return a portable `open-geo.run-artifact.v1` JSON file, with optional PDF/dashboard. `pipeline/INTERFACES.md` defines the contracts; `pipeline/schema.py` validates captures.

Invocation and defaults

/open-geo <questions.csv> <engine> <domain-or-URL-prefix> --brand "<name>"
          [--n-worker N] [--output data|dashboard|pdf|both]
          [--artifact-out <path.json>] [--period today|all]
          [--lang en|ru|zh|ar] [--repeat R]

These are skill arguments, not a shell command. Defaults: one worker, `data`, `reports/run-<id>.json`, `all`, `en`, one capture. `--lang` controls the exported presentation and user summary, not query language or captured sentiment. `--repeat R` costs R independent captures; never infer it from “check again”.

Read only what this run needs

| When | Read | |---|---| | Runtime is not resolved, dependencies are missing, or caller paths differ | [runtime.md](./references/runtime.md) | | Before creating/resuming a run or processing captures | [run.md](./references/run.md) — exact CLI sequence, counts, failure policy | | Before capture/finalization, or when a result looks suspicious | [gotchas.md](./references/gotchas.md) — observed failures and corrections | | User requests question research instead of supplying a CSV/core | [harvest.md](./references/harvest.md) — grounded research and review gate | | PDF, dashboard, combined-engine report, or repeats requested | [deliverables.md](./references/deliverables.md) | | Explaining a metric or its denominator | [metrics.md](./references/metrics.md) | | Editing/testing this skill | [validation.md](./references/validation.md) — replay evidence and acceptance checks |

STEP R — resolve the runtime and paths

Prefer the current repo containing `pipeline/INTERFACES.md`, then caller-supplied `OPEN_GEO_ROOT`, then a writable installed package, then the managed runtime. Bootstrap instructions are in `runtime.md`; perform setup rather than asking the user to launch services. Use the runtime's `.venv/bin/python` from its root.

**Before changing directories**, resolve the input CSV/core and explicit artifact path against the caller's original directory. Resolve one absolute database path (normally `data/aeo.db` under that root, or the caller's explicit isolated DB) and pass it to every CLI.

STEP A — resolve the measurement

Reuse arguments and free-text context. Ask only for missing brand, target, engine, and question input; concurrency defaults to 1. List engines from actual playbooks under `engines/`, excluding `README.md` and `FAST_PATH.md`. A missing playbook is a blocker, not permission to invent capture steps.

Accept a supplied `query,lens` CSV directly. For a `core.json` handoff, read `questions_csv`, `brand`, `domain`, and `totals.coverage` (INTERFACES §8); keep the coverage for the final summary. Missing or empty input blocks run creation.

Host primitives

Ask with the host's question tool (`AskUserQuestion` on Claude), or in conversation. Spawn with its native agent tool (Claude `Agent`, Grok `spawn_subagent`, equivalent on other hosts). Read the host-native worker contract at the pointer below. Without delegation, perform the same capture contract sequentially; do not substitute an API or headless scrape for the rendered browser surface.

STEP A.5 — questions, only if requested

Use `harvest.md` only when the user opts into generating/researching questions. It produces a reviewed CSV and provenance; a supplied CSV/core bypasses this step. Do not replace the user's questions with a newly invented set.

STEP 1 — validate, then create or resume

Follow `run.md`: validate CSV **before** writing a run, retain file order, count unique `(query,lens)` pairs. Reject malformed rows rather than silently dropping them. Check for a compatible unfinished run; an explicit resume request or fully specified invocation resumes it automatically. If the set differs, create a separate run and identify the unfinished one. Capture only the `--pending` rows.

For `--repeat R > 1`, read `deliverables.md` before creating runs; repeats share a group, but never share captured rows.

STEPS 2–3 — capture pending rows

Read the **whole** `engines/<engine>.md` and the host-native `../../agents/capture-worker.md`. Probe the host's visible-browser connection and playbook-required clean context before creating a new run. A missing connection, login wall, or unsupported clean context blocks live capture.

Default to sequential capture. If concurrency is requested and the host/browser supports isolation, split pending rows into `min(N, pending count)` ordered chunks. One worker owns each chunk and its tabs; account limits still apply across workers. Give each worker:

• Full engine playbook, exact `(query,lens)` rows, target including its path, brand,

engine, and pointers to INTERFACES §1 and `pipeline/schema.py`.

• A unique absolute output path inside this invocation's temporary directory

(`mktemp -d`), plus chunk index. Never reuse a global `/tmp/open_geo_cap_1.json`.

Workers persist a validated array after **each query**, then return its path, JSON, and captured/missing keys. They never receive the DB/run ID or ingest commands. The orchestrator o