openseo-project-setup

OpenSEO Project Setup

Bind the current repo to an OpenSEO project so every other openseo-* skill has a stable project id, and prepare mktg's local SEO state contract. This is a one-time-per-repo handshake, not an audit and not research.

On Activation

Run these steps in order. Each has a fallback; never block on missing context.

Step 1 — Check catalog readiness

mktg catalog info openseo --json --fields configured,missing_envs,mcp

• Exit 1 → the openseo catalog is missing; upgrade marketing-cli. Stop.
• configured: false → name the missing envs from missing_envs. Hosted path: sign up at openseo.so, connect the MCP in the user's agent client (root .mcp.json ships the openseo server), and/or set OPENSEO_API_KEY for non-interactive automation. Without any connection, stop after writing the gap note — research skills will fall back to Exa with metrics unknown.

Step 2 — Read brand grounding

Read brand/keyword-plan.md and brand/positioning.md if they exist (tolerate missing). The domain, audience, and positioning facts go into the project record. If brand/ is all templates, note it and recommend /cmo foundation first — SEO inputs without positioning are guesses.

Step 3 — Resolve the OpenSEO project

Via the OpenSEO MCP tools: whoami (if available) then list_projects. Match the project to the user's domain. If the list is ambiguous, ask which project. If MCP is unavailable but OPENSEO_API_KEY is set, note that interactive MCP steps are deferred and record what is known.

Do NOT call research tools to test connectivity — whoami/list_projects are the only probes allowed here (they are free; research calls spend DataForSEO credit).

Step 4 — Write the binding + state directories

Create or update .seo/openseo.json:

{ "version": 1, "projectId": "<id>", "domain": "<domain>", "mcpUrl": "https://app.openseo.so/mcp", "linkedAt": "<iso>", "updatedAt": "<iso>" }

Create .seo/ with rank-snapshots/ if rank tracking is in scope. If brand/keyword-plan.md is a template, leave it alone — the first research run populates it; do not pre-fill with placeholders.

Step 5 — Google Search Console

GSC is the richest first-party signal (striking-distance terms, cannibalization).

• Hosted preferred: point the user at the OpenSEO project's Integrations page to connect GSC natively; later skills read it live via get_search_console_performance.
• Fallback (self-host / file preference): ask for CSV exports into .seo/gsc/ (queries-last-3-months.csv, pages-last-3-months.csv, 16-month variants when available).

Never claim GSC is connected unless get_search_console_performance confirms it — it returns a "not connected" message otherwise.

Step 6 — Recommend the next skill

Anti-Patterns

• Running research calls as a connectivity test — because every OpenSEO research call can spend DataForSEO credit, and a setup handshake has no business spending money. whoami and list_projects are free; use only those.
• Claiming GSC is connected without proof — because downstream skills (keyword research's striking-distance strategy) silently change behavior based on that claim; a false positive turns first-party data into invented data. Verify with get_search_console_performance or say "not connected."
• Pre-filling brand/keyword-plan.md with placeholder keywords — because template-detection (SHA-256) and mktg plan health read placeholder content as "populated," and every downstream skill then trusts fake keywords. Leave the template until real research lands.
• Forking state into a second project file — because two project ids drift and every skill has to guess which is canonical. .seo/openseo.json is the single binding; update it, never duplicate it.
• Asking the user 15 questions before writing anything — because setup should orient, not assign homework. Capture what is known, mark the rest unknown, and let research skills fill gaps on demand.

Progressive Enhancement

Adapted from every-app/open-seo .agents/skills/seo-project-setup (MIT). Upstream workflow by the OpenSEO maintainers; mktg state contract, brand grounding, and cost discipline added here.