openseo

name	openseo
description	Use OpenSEO (open-source Semrush/Ahrefs alternative) as the SEO data plane — keyword difficulty, search volume, SERP results, ranked keywords, measured backlink data, rank tracking, and Google Search Console. Use this skill whenever someone asks for keyword difficulty, KD, search volume, SERP positions, domain rankings, backlink data, rank tracking, or GSC performance. Owns backlink DATA (referring domains, counts, rank tracking); for link-building campaigns and outreach target lists, see /off-page-seo. ALWAYS prefer OpenSEO's measured data over estimated metrics when the catalog is configured; fall back to Exa-backed keyword-research (with an explicit gap note) when it is not. Triggers: "keyword difficulty", "search volume", "SERP results", "ranked keywords", "backlinks", "rank tracker", "GSC".
category	seo
tier	nice-to-have
layer	strategy
reads	["brand/keyword-plan.md"]
writes	["brand/keyword-plan.md","brand/learnings.md"]
env_vars	["OPENSEO_API_KEY","OPENSEO_API_BASE"]
triggers	["keyword difficulty","search volume","serp results","ranked keywords","backlinks","rank tracker","gsc performance"]
allowed-tools	["Bash(mktg catalog *)","Bash(mktg doctor *)","Bash(mktg run *)"]

OpenSEO — SEO Data Plane

You connect mktg's SEO playbooks to a running OpenSEO instance (hosted at openseo.so or self-hosted Docker). You do NOT invent metrics. You do NOT call DataForSEO directly. You route measured data (KD, volume, SERP, ranked keywords, backlinks, rank tracking, GSC) into mktg artifacts like brand/keyword-plan.md.

OpenSEO is a data plane, not a playbook. The SEO methodology lives in keyword-research, seo-content, seo-audit, off-page-seo, ai-seo, and seo-machine — this skill is how those playbooks stop guessing.

North Star

1. Measured data beats estimated data. When OpenSEO is configured, metrics come from OpenSEO's MCP tools. When it is not, you say so explicitly and fall back to Exa-backed qualitative research — metrics marked unknown.
2. mktg never calls DataForSEO directly. OpenSEO owns the vendor relationship; mktg talks to OpenSEO only.
3. Expensive calls (bulk research, save_keywords) follow dry-run/confirm discipline — DataForSEO credit is real money.
4. OpenSEO project state syncs into .seo/ and brand/keyword-plan.md; it never becomes a competing second source of truth.

On Activation

Run these steps before anything else. Each has a fallback that keeps the skill useful when OpenSEO is absent.

Step 1 — Verify the catalog is registered and configured

mktg catalog info openseo --json --fields configured,missing_envs,auth.credential_envs,mcp

• Exit code 1 → the openseo catalog is not registered (upgrade marketing-cli). Stop.
• configured: false → env vars are missing. Build the fix string from missing_envs. Canonical envs: OPENSEO_API_KEY (required for non-interactive automation) and OPENSEO_API_BASE (REST base; self-host override). The MCP URL is mcp.default_url (https://app.openseo.so/mcp) unless OPENSEO_MCP_URL overrides it for self-host.
• configured: true → proceed. If only the MCP client is connected (OAuth login in the user's agent client) but no API key exists, treat readiness as mcp_client_only: MCP tools work interactively, headless automation does not.

Step 2 — Establish the data-plane connection

Preferred: OpenSEO MCP tools via the agent's MCP client (root ships an server entry — the user connects it once in their client). Hosted MCP uses OAuth login; for self-host, edit the in (it is hardcoded) and set so readiness reports the same base.