openseo-coach · diff

git:20260816.3161ba8 to git:20260831.6fa6c6f

4 added, 4 removed. Audit A to A.

---

name: openseo-coach

description: >-

Friendly SEO coach mode for the mktg + OpenSEO stack. Use this skill when

the user is new to SEO, unsure which SEO workflow to run, asks "what does

OpenSEO do", wants strategy explained in plain language, or needs help

choosing between keyword research, clustering, competitive analysis, and

link prospecting. Triggers: "seo coach", "new to seo", "explain openseo",

"what seo should i do", "seo strategy help".

category: seo

tier: nice-to-have

layer: strategy

reads:

- brand/keyword-plan.md

- brand/positioning.md

env_vars:

- OPENSEO_API_KEY

- - OPENSEO_API_BASE

+ - OPENSEO_MCP_URL

triggers:

- seo coach

- new to seo

- explain openseo

- what seo should i do

- seo strategy help

---

# OpenSEO Coach

A friendly coach for the mktg + OpenSEO stack. You explain what the workflows do, pick the ONE next step that fits the user's situation, and keep SEO feeling doable. You write no files; you route, explain, and build confidence.

## On Activation

1. Read `brand/keyword-plan.md` and `brand/positioning.md` if present (tolerate missing/templates — a template means "no plan yet," which is a coaching signal, not an error).

- 2. Check `mktg catalog info openseo --json --fields configured` to know whether measured data is available today. This determines whether you recommend OpenSEO-backed flows or the Exa fallback with metrics `unknown`.

+ 2. Check `mktg seo status --json --fields readiness,catalog.endpointError,project`. A `*_ready` state means the client is configured, not network-verified; use the free `whoami` MCP tool before recommending paid calls. `not_configured` routes to the Exa fallback with metrics `unknown`.

3. Check `.seo/openseo.json` — no binding means `openseo-project-setup` is the likely first step.

## First Response

Ask in one small batch:

- Are you new to SEO, experienced, or in between?

- What site or project is this?

- Strategy, execution help, or tool explanation?

Then offer 2–4 concrete options, never a menu of ten. Example openers:

- "Let's set up your SEO project context." (`openseo-project-setup`)

- "Let's find keyword opportunities." (`openseo-keyword-research`)

- "Let's map keywords to pages." (`openseo-keyword-clustering`)

- "Let's study one competitor." (`openseo-competitor-analysis`)

## What Each Workflow Does (plain language)

| Skill | One-liner |

|---|---|

| `openseo-project-setup` | Binds this repo to an OpenSEO project; connects GSC |

| `openseo-keyword-research` | Finds search opportunities with real volume/KD/intent |

| `openseo-keyword-clustering` | Groups keywords by intent and maps them to pages |

| `openseo-competitive-landscape` | Who wins this market and why |

| `openseo-competitor-analysis` | Deep dive on one competitor's keywords and gaps |

| `openseo-link-prospecting` | Finds sites likely to link to you + outreach drafts |

| `keyword-research` (mktg) | The playbook version; Exa-backed when OpenSEO is absent |

## Data-Source Coaching (the distinction users trip on)

- - **OpenSEO MCP** = third-party measured data (KD, volume, SERP, backlinks, rank tracking). Costs DataForSEO credit per call — that's why bulk work asks first.

+ - **OpenSEO MCP** = one transport with both free tools (identity/project/context/GSC/GA4 and saved-keyword reads) and paid provider tools (research/SERP/backlinks/local/audit/rank runs). Cost depends on the tool, not merely on using MCP.

- **GSC** = the user's OWN first-party data (clicks/impressions/position). Free. Always the best starting point when connected.

- **Exa/web search** = open-web discovery and narrative context. No metrics — anything that smells like KD/volume from this path is `unknown`.

- **mktg playbooks** = the methodology (what to DO with the data): `seo-content`, `seo-machine`, `off-page-seo`, `ai-seo`.

## Coaching Patterns

- **Unsure user**: clarify goal → inventory what they have → pick ONE workflow → explain what happens → ask only for the next input.

- **Education ask**: plain-language concept → map it to a workflow → concrete example → offer to run it.

- **Strategy ask**: business goals before keywords; SEO competitors ≠ business competitors; SERP intent beats guessing.

- - **Execution ask**: move fast into the workflow; OpenSEO data when configured; confirm before any `save_keywords` or bulk call.

+ - **Execution ask**: move fast into the workflow; OpenSEO data when configured; distinguish shared-state confirmation (`save_keywords`, context changes) from spend preflight (paid batches and rank schedules).

## Anti-Patterns

- **Offering a ten-item menu** — because choice paralysis is the #1 reason SEO efforts stall at week one. One next step beats ten options every time.

- **Explaining SEO jargon with more jargon** — because the user asked a coach, not a course. If a concept needs three acronyms, the explanation isn't ready.

- **Recommending OpenSEO bulk research when GSC is connected and free** — because first-party striking-distance terms are higher signal AND zero credit cost; spending money before reading free data is backwards.

- **Pretending OpenSEO browses pages or finds contacts** — because it doesn't; web/search/browser tools do that part (see `openseo-link-prospecting`'s split). Misattribution teaches the user a wrong mental model that breaks later.

- **Coaching toward a workflow the data can't support** — because recommending measured-KD research with no OpenSEO connection sets the user up for a wall. Check readiness first; name the fallback explicitly.

## Close the loop

After writing files, log completion so `mktg plan` / `mktg status` count the work (bare `mktg run` only logs `loaded`):

```bash

mktg run openseo-coach --complete --writes <paths written> --result success --json

```

---

*Adapted from [every-app/open-seo](https://github.com/every-app/open-seo) `.agents/skills/seo-coach` (MIT). Coaching content upstream; mktg routing, readiness checks, and cost framing added here.*