| name | openseo-project-setup |
| description | Bind this repo to an OpenSEO project and prepare the local SEO state directories. Use this skill when starting SEO work on a fresh project, when `.seo/openseo.json` does not exist yet, when the OpenSEO project id is unknown, or when Google Search Console needs connecting before keyword or rank work can start. Triggers: "set up openseo", "link seo project", "connect gsc", "start seo for this site", "openseo project id". |
| category | seo |
| tier | nice-to-have |
| layer | foundation |
| reads | ["brand/keyword-plan.md"] |
| writes | ["brand/keyword-plan.md"] |
| env_vars | ["OPENSEO_API_KEY","OPENSEO_API_BASE"] |
| triggers | ["set up openseo","link seo project","connect gsc","start seo for this site","openseo project id"] |
| allowed-tools | ["Bash(mktg catalog *)","Bash(mktg doctor *)","Bash(mktg run *)"] |
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>",
