SEO Growth Workspace
Contribute within authority. The active workspace contract and current task scope decide whether a run may modify this skill or open an upstream PR. When authorized, fix the canonical source through its normal release flow; otherwise leave the skill untouched and record concrete, non-duplicate friction in the .seo/log.md handoff when that write is already in scope. Invoking this skill never implies product-development scope.
Run a durable SEO operating workspace for a product or local-business website. The goal is not generic advice; it is evidence, prioritization, implementation, verification, and continuity. Use this skill as a mode router: load only the reference the selected mode or ticket needs.
Design rules (the constitution): (1) Prose states intent, invariants, and completion criteria — scripts/loop-state.mjs owns state formats, legal transitions, and crash intermediates. (2) One file per loadable concern; no ownership disclaimers. (3) Fail-closed is reserved for the four outcome-protecting invariants: no silent dry exits; no certificate under drift or stale coverage; no Done without evidence; no publish past integrity gates — everything else degrades gracefully. (4) Field-discovered ambiguity is resolved by judgment and logged (or becomes a fixture), not legislated; a new normative clause requires judgment failing twice on the same point with bad SEO consequences.
Ground Rules
- Speak the user's language; keep code identifiers in English. Match the target site's language, market, and brand voice for public content.
- Use the target repo's package manager, deploy path, auth workflow, and UI validation tool. Bundled scripts are dependency-free (
node, 18+).
- Delegate online research legwork through the runtime's research skill when one exists; each mode's evidence contract still governs what gets captured.
- Never print secrets from env files, dashboards, OAuth, or admin surfaces.
- One current focus ticket; no task lists outside
.seo/backlog.md; evidence in audit.md, decisions in strategy.md, handoffs in log.md, dated reports in reports/.
- Prefer matrix-shaped audit outputs. Produce actual copy, schema, calendar rows, scripts, code, or admin changes where the mode calls for it.
Workspace
.seo/
README.md context.md backlog.md log.md strategy.md audit.md taxonomy.md
backlinks/ (summary.md, work-log.md, optional asset-rights.md)
reports/ scripts/ pseo/ loops/ reconciliation.json
Two install modes, stamped in .seo/config.json: standalone (repo-local .seo/, one site) and hub (an orchestrator repo managing many sites, one full workspace per site under .seo/sites/<slug>/). Path terms used everywhere: HUB_ROOT (hub's .seo/, routing state only), SITE_WORKSPACE (the one workspace a run operates), TARGET_REPO (the repo whose site is changed), SKILL_DIR (this installed folder). Workspace prose like .seo/backlog.md means SITE_WORKSPACE/backlog.md. Doctor first before bootstrap or migration — lifecycle, target resolution, registry, migration, adapters, and admin preflight all live in references/workspace.md.
Modes
Pick the narrowest mode; default to operate. A full first run loads references/first-run.md, starts with bootstrap, then continues in operate. In hub mode, resolve the target site first.
| Mode |
Use when |
Exit criteria |
operate |
Continuing SEO work without a narrower request |
State read, next work chosen, one terminal recorded with evidence and handoff (references/operating.md) |
bootstrap |
Starting or auditing an SEO workspace |
.seo/ exists, business context exists, first audit/backlog populated |
technical-seo-fix |
Robots, sitemap, canonicals, metadata, schema, redirects, analytics, CWV, hreflang, AI-crawler access, indexability |
Change deployed or documented blocked, then live verified |
content-ops |
Keywords, calendars, briefs, articles, utility pages, internal links, content engines |
Content state visible, publish path verified or blocked, next rows documented |
pseo-planning |
pSEO page types, data, publish gates |
.seo/pseo/plan.md and data/specs exist; publish decision explicit |
local-seo |
GBP/local-map intent, service areas, citations, reviews |
Competitor/GBP matrix and prioritized local plan produced |
monthly-report |
Reporting performance, deciding next month |
One-page report with wins, problems, deltas, single next action |
diagnose |
Traffic or rankings dropped |
Drop characterized with evidence (branded split, SERP-feature/AI-Overviews, core update, technical regression) and next action filed |
References
Protocol: operating.md (the loop: selection, tickets, terminals, wake/sleep, cadences, obligations, ships, frontier, unattended runs, upgrade pass) · policy.md (fixed stages, cadences, gate families, measurement timing) · workspace.md (install lifecycle, hub, registry, migration, adapters, admin preflight) · first-run.md (site classifier, phase ladder, business context).
Domain, loaded per ticket: technical-seo.md · international-seo.md · search-console.md · content-ops.md (incl. community-source pages) · content-refresh.md · utility-tool-pages.md · internal-linking.md · schema-rich-results.md · pseo-gates.md · local-seo-gbp.md · backlinks-entity.md (incl. image rights) · commercial-integrity.md (incl. affiliate/promo) · ecommerce-seo.md · competitor-profiling.md · data-tools.md · ahrefs.md (bootstrap/adoption preflight, monthly External Crawl, provider access, and Ahrefs evidence) · ai-search-visibility.md · conversion.md (CTA audits + PostHog outcome bridge) · monthly-reporting.md · content-engine-webhooks.md · pages.md (page evidence + launch gates).
Templates (templates/): monthly-report, local-seo-gbp, pseo-plan, content-plan, taxonomy. Other report shapes are inlined in their owning references.
Scripts
All dependency-free; run from SKILL_DIR with explicit SITE_WORKSPACE paths; --help on each documents its contract.
loop-state.mjs — the loop-state protocol, compiled: single writer/validator for loops/ state and the reconciliation stamp. verify (read-only; --repair fixes policy mirrors), occurrence/obligation lifecycles with idempotent crash retries, ship record, sleep certify|heartbeat (fail-closed exit codes for drift, in-flight state, stale coverage, armed autopublish), stamp check|write|report-path.cadence-status.mjs — cold reader: due occurrences/obligations, in-flight rows, earliest next-due, advisory stamp block.seo-doctor.mjs — read-only workspace diagnosis; emits the reviewed plan bootstrap consumes.bootstrap-seo-workspace.mjs — consumes a reviewed plan: create/adopt/verify/repair; stamps new workspaces reconciled at birth.gsc-oauth.mjs / gsc-fetch.mjs / gsc-opportunities.mjs — Search Console auth, exports, and opportunity tables.monthly-report.mjs — one-page monthly report from exported data.portfolio-status.mjs — ranked cross-site "which site deserves the next SEO hour" table.link-graph-analyzer.mjs / rendered-link-export.mjs — internal-link graph analysis.
Core Workflow
- State assumptions, install mode, resolved target workspace, live URL, market, language, success criteria.
- Classify site type and phase with
references/first-run.md when the request is broad, first-run, or ambiguous.
- Choose the mode and load only its reference. For
operate, load references/operating.md, then the narrow reference the chosen ticket needs.
- Create or update
context.md (references/first-run.md); in no-write runs use existing context and record drift.
- Capture admin/auth evidence (
references/workspace.md) before changing production or authenticated surfaces; load its adapter section when the repo has a content engine or CMS.
- When a ticket creates or materially revises a public SEO page, apply
references/pages.md — Done requires PASS evidence on every mandatory launch gate and a logged discovery-submission decision.
- Execute the mode's workflow, verify live results (at least one mobile viewport for UI/CTA work), and update
.seo/ files only where facts changed.
When adjacent marketing skills are installed, use them as lenses, never dependencies (bridge table: references/first-run.md). If none are installed, these references are sufficient.
1---2name: seo-growth-workspace3description: Use when starting, auditing, or operating SEO or organic growth for a product or local-business website — technical SEO, Search Console, keyword/content ops, schema, pSEO, local SEO/GBP, backlinks, AI-search visibility, conversion, and monthly reporting. Triggers: "set up SEO", "audit my site", "my traffic dropped", "why am I not ranking", "Search Console opportunities", "monthly SEO report", "how do we show up in ChatGPT/AI search". Creates a durable .seo workspace, captures business context, audits live/code/admin evidence, prioritizes a backlog, implements one high-leverage action, verifies reality, and logs handoff notes. Installs in a single site repo (standalone) or in an orchestrator/agent-profile repo managing many sites (hub). For standalone copywriting, paid channels, or email, use a dedicated skill.4license: MIT5---67# SEO Growth Workspace89> **Contribute within authority.** The active workspace contract and current task scope decide whether a run may modify this skill or open an upstream PR. When authorized, fix the canonical source through its normal release flow; otherwise leave the skill untouched and record concrete, non-duplicate friction in the `.seo/log.md` handoff when that write is already in scope. Invoking this skill never implies product-development scope.1011Run a durable SEO operating workspace for a product or local-business website. The goal is not generic advice; it is evidence, prioritization, implementation, verification, and continuity. Use this skill as a mode router: load only the reference the selected mode or ticket needs.1213**Design rules (the constitution):** (1) Prose states intent, invariants, and completion criteria — `scripts/loop-state.mjs` owns state formats, legal transitions, and crash intermediates. (2) One file per loadable concern; no ownership disclaimers. (3) Fail-closed is reserved for the four outcome-protecting invariants: no silent dry exits; no certificate under drift or stale coverage; no Done without evidence; no publish past integrity gates — everything else degrades gracefully. (4) Field-discovered ambiguity is resolved by judgment and logged (or becomes a fixture), not legislated; a new normative clause requires judgment failing twice on the same point with bad SEO consequences.1415## Ground Rules1617- Speak the user's language; keep code identifiers in English. Match the target site's language, market, and brand voice for public content.18- Use the target repo's package manager, deploy path, auth workflow, and UI validation tool. Bundled scripts are dependency-free (`node`, 18+).19- Delegate online research legwork through the runtime's research skill when one exists; each mode's evidence contract still governs what gets captured.20- Never print secrets from env files, dashboards, OAuth, or admin surfaces.21- One current focus ticket; no task lists outside `.seo/backlog.md`; evidence in `audit.md`, decisions in `strategy.md`, handoffs in `log.md`, dated reports in `reports/`.22- Prefer matrix-shaped audit outputs. Produce actual copy, schema, calendar rows, scripts, code, or admin changes where the mode calls for it.2324## Workspace2526```text27.seo/28 README.md context.md backlog.md log.md strategy.md audit.md taxonomy.md29 backlinks/ (summary.md, work-log.md, optional asset-rights.md)30 reports/ scripts/ pseo/ loops/ reconciliation.json31```3233Two install modes, stamped in `.seo/config.json`: **standalone** (repo-local `.seo/`, one site) and **hub** (an orchestrator repo managing many sites, one full workspace per site under `.seo/sites/<slug>/`). Path terms used everywhere: **HUB_ROOT** (hub's `.seo/`, routing state only), **SITE_WORKSPACE** (the one workspace a run operates), **TARGET_REPO** (the repo whose site is changed), **SKILL_DIR** (this installed folder). Workspace prose like `.seo/backlog.md` means `SITE_WORKSPACE/backlog.md`. **Doctor first** before bootstrap or migration — lifecycle, target resolution, registry, migration, adapters, and admin preflight all live in `references/workspace.md`.3435## Modes3637Pick the narrowest mode; default to `operate`. A full first run loads `references/first-run.md`, starts with `bootstrap`, then continues in `operate`. In hub mode, resolve the target site first.3839| Mode | Use when | Exit criteria |40| --- | --- | --- |41| `operate` | Continuing SEO work without a narrower request | State read, next work chosen, one terminal recorded with evidence and handoff (`references/operating.md`) |42| `bootstrap` | Starting or auditing an SEO workspace | `.seo/` exists, business context exists, first audit/backlog populated |43| `technical-seo-fix` | Robots, sitemap, canonicals, metadata, schema, redirects, analytics, CWV, hreflang, AI-crawler access, indexability | Change deployed or documented blocked, then live verified |44| `content-ops` | Keywords, calendars, briefs, articles, utility pages, internal links, content engines | Content state visible, publish path verified or blocked, next rows documented |45| `pseo-planning` | pSEO page types, data, publish gates | `.seo/pseo/plan.md` and data/specs exist; publish decision explicit |46| `local-seo` | GBP/local-map intent, service areas, citations, reviews | Competitor/GBP matrix and prioritized local plan produced |47| `monthly-report` | Reporting performance, deciding next month | One-page report with wins, problems, deltas, single next action |48| `diagnose` | Traffic or rankings dropped | Drop characterized with evidence (branded split, SERP-feature/AI-Overviews, core update, technical regression) and next action filed |4950## References5152Protocol: `operating.md` (the loop: selection, tickets, terminals, wake/sleep, cadences, obligations, ships, frontier, unattended runs, upgrade pass) · `policy.md` (fixed stages, cadences, gate families, measurement timing) · `workspace.md` (install lifecycle, hub, registry, migration, adapters, admin preflight) · `first-run.md` (site classifier, phase ladder, business context).5354Domain, loaded per ticket: `technical-seo.md` · `international-seo.md` · `search-console.md` · `content-ops.md` (incl. community-source pages) · `content-refresh.md` · `utility-tool-pages.md` · `internal-linking.md` · `schema-rich-results.md` · `pseo-gates.md` · `local-seo-gbp.md` · `backlinks-entity.md` (incl. image rights) · `commercial-integrity.md` (incl. affiliate/promo) · `ecommerce-seo.md` · `competitor-profiling.md` · `data-tools.md` · `ahrefs.md` (bootstrap/adoption preflight, monthly External Crawl, provider access, and Ahrefs evidence) · `ai-search-visibility.md` · `conversion.md` (CTA audits + PostHog outcome bridge) · `monthly-reporting.md` · `content-engine-webhooks.md` · `pages.md` (page evidence + launch gates).5556Templates (`templates/`): monthly-report, local-seo-gbp, pseo-plan, content-plan, taxonomy. Other report shapes are inlined in their owning references.5758## Scripts5960All dependency-free; run from SKILL_DIR with explicit SITE_WORKSPACE paths; `--help` on each documents its contract.6162- `loop-state.mjs` — **the loop-state protocol, compiled**: single writer/validator for `loops/` state and the reconciliation stamp. `verify` (read-only; `--repair` fixes policy mirrors), `occurrence`/`obligation` lifecycles with idempotent crash retries, `ship record`, `sleep certify|heartbeat` (fail-closed exit codes for drift, in-flight state, stale coverage, armed autopublish), `stamp check|write|report-path`.63- `cadence-status.mjs` — cold reader: due occurrences/obligations, in-flight rows, earliest next-due, advisory stamp block.64- `seo-doctor.mjs` — read-only workspace diagnosis; emits the reviewed plan bootstrap consumes.65- `bootstrap-seo-workspace.mjs` — consumes a reviewed plan: create/adopt/verify/repair; stamps new workspaces reconciled at birth.66- `gsc-oauth.mjs` / `gsc-fetch.mjs` / `gsc-opportunities.mjs` — Search Console auth, exports, and opportunity tables.67- `monthly-report.mjs` — one-page monthly report from exported data.68- `portfolio-status.mjs` — ranked cross-site "which site deserves the next SEO hour" table.69- `link-graph-analyzer.mjs` / `rendered-link-export.mjs` — internal-link graph analysis.7071## Core Workflow72731. State assumptions, install mode, resolved target workspace, live URL, market, language, success criteria.742. Classify site type and phase with `references/first-run.md` when the request is broad, first-run, or ambiguous.753. Choose the mode and load only its reference. For `operate`, load `references/operating.md`, then the narrow reference the chosen ticket needs.764. Create or update `context.md` (`references/first-run.md`); in no-write runs use existing context and record drift.775. Capture admin/auth evidence (`references/workspace.md`) before changing production or authenticated surfaces; load its adapter section when the repo has a content engine or CMS.786. When a ticket creates or materially revises a public SEO page, apply `references/pages.md` — Done requires PASS evidence on every mandatory launch gate and a logged discovery-submission decision.797. Execute the mode's workflow, verify live results (at least one mobile viewport for UI/CTA work), and update `.seo/` files only where facts changed.8081When adjacent marketing skills are installed, use them as lenses, never dependencies (bridge table: `references/first-run.md`). If none are installed, these references are sufficient.
jorgemenadev