| name | optimize-seo |
| description | Audits and plans search visibility across six modes — technical SEO audit, AI/answer-engine optimization (AEO), programmatic SEO, competitor comparison pages, full SEO strategy, and app store optimization (ASO). Covers keyword research, on-page and technical fixes, link-building strategy, and structured data. Use to diagnose a traffic drop, plan search growth, or get found by AI search. Not for landing-page conversion brief work (use brief-landing-page) or writing the page copy (use write-copy). |
| argument-hint | [url or mode] |
| allowed-tools | Read Grep Glob Bash WebSearch WebFetch |
| metadata | {"version":"1.1.1","budget":"deep","estimated-cost":"$2-5"} |
SEO — Orchestrator
Communication — Horizontal. Covers the full SEO surface: technical foundations, AI/agent engine optimization, programmatic page generation, app store optimization, and competitor comparison content.
Core Question: "How do we get found — by both search engines and AI models?"
Why this skill exists, when NOT to use it, 10-item quality gate summary, six routes by mode: references/playbook.md [PLAYBOOK].
Philosophy
SEO mixes hard technical constraints (CWV thresholds, character limits, schema validation) with strategic judgment. Platform specs are constraints; strategic recommendations are defaults with deviation context. Specific > Vague > Comprehensive > Generic — every recommendation names exact page, exact change, expected impact.
Critical Gates
Before delivering, all must hold:
- Every recommendation names exact page, exact change, expected impact. No "consider" / "you might."
- AI SEO is additive, not alternative. No point optimizing for AI citations if crawlers can't reach content.
- Source recency. AI platform behavior shifts fast — verify no deprecated practices, outdated crawlers, stale metrics.
- Mode is diagnosis-driven, not a generic "do SEO" deliverable.
- Platform-native modes cite platform-intelligence. When mode is AI SEO, Programmatic, Competitor Pages, or ASO, recommendations affecting platform-native search surfaces (TikTok / YouTube / LinkedIn / X / Reels / App Store) cite the relevant §§ from
references/_shared/platform-intelligence/[platform].md (mapped per agent in references/platform-search.md). Generic "post on LinkedIn" is not sufficient — recommendation references §1/§2/§3/§4 of the platform-intelligence catalog by section.
Before Starting
Per references/_shared/before-starting-check.md [PROCEDURE] — load product context, check artifact staleness (>30 days → recommend re-run upstream).
| Artifact | Source | Required? |
|---|
icp-research.md | research-icp | Recommended — audience search behavior drives strategy |
campaign-plan.md | plan-campaign | Optional — pillars inform topic clusters |
product-context.md | research-icp | Optional — positioning context |
Pre-Dispatch
Canonical Pre-Dispatch: references/_shared/pre-dispatch-protocol.md [PROCEDURE].
Needed dimensions: mode (audit / ai / programmatic / competitor / aso), site or property, audience, geographic + language scope.
Full read-order + Cold/Warm Start prompts + write-back map + Chain Position + Skill Deference + IMC Coordination table: references/procedures/pre-dispatch.md [PROCEDURE].
Mode Resolution
Per references/_shared/mode-resolver.md [PROCEDURE] — auto-downgrade ≤3 sentences, no prior artifacts; --fast skips Layer 2 (no prioritization, no critic), runs single-agent. --fast does NOT skip Cold Start or Critical Gates 1-4.
Session execution profile (single-vs-multi): inherit per references/_shared/execution-policy.md.
Route-collapse default (multi-route deep override): a ≤3-sentence single-scope ask (one mode's keywords, no prior artifacts) auto-resolves to that mode's minimal Route (A/B/C/D/F) + critic — never Route E "Full SEO" — without needing --fast. Cross-mode asks, or an upward override ("full strategy", "thorough"), use the full multi-mode orchestration.
Agent Manifest
15 sub-agents across two layers (13 Layer 1 domain agents — crawl / foundations / content-quality / authority / ai-structure / ai-presence / programmatic-template / programmatic-quality / comparison-page / aso-keyword / aso-listing / aso-reviews / aso-competitive — + Layer 2 prioritization → critic). Full table with per-agent focus + per-route composition: references/agent-manifest.md [PROCEDURE].
Routing Logic — Mode-Based Dispatch
Diagnose first, then enter the right mode. Modes can run sequentially. Start with Technical Audit if never audited — no point optimizing for AI citations if crawlers can't reach content (Critical Gate 2).
| Situation | Mode | Route |
|---|
| Technical issues / traffic dropped / never audited | Technical Audit | Route A |
| Want citations from ChatGPT / Perplexity / AI search | AI SEO (AEO) | Route B |
| Structured data, want to generate pages at scale | Programmatic SEO | Route C |
| Rank for competitor comparison queries | Competitor Pages | Route D |
| Comprehensive SEO strategy | Full SEO (Technical + AI) | Route E |
| Distribute via app stores / listings (App Store, Play Store, G2, Capterra, Product Hunt) | ASO | Route F |
Per-route Layer 1 + Layer 2 composition: references/agent-manifest.md § "Per-route composition". Route E produces TWO artifacts (seo-audit.md + seo-ai.md). Full pre-writing object schema, 8-step Multi-Agent Dispatch flow, Single-Agent Fallback, prioritization mechanics (Quick Wins → Strategic Investments → Low-Hanging Fruit → Backlog; P1-P4 phasing; dependency mapping), critic gate mechanics (10-item rubric, binary PASS/FAIL, max 2 rewrite cycles, 11-row Rewrite Routing Table), --fast execution path: references/procedures/dispatch-mechanics.md [PROCEDURE].
Route B control surface. Bing backs ChatGPT/Perplexity/Copilot — confirm Bing readiness before AI-citation tactics for those products (references/platform-intelligence/bing-readiness.md), then score extractability (distinct from on-page) with references/geo-citation-readiness-checklist.md.
Route C selectors. Pick the archetype from the 12-playbook taxonomy (references/programmatic-template-playbooks.md + the design/defensibility rules in references/programmatic-seo.md); for a proprietary-data play, run the build-vs-pitch-direct classifier in references/linkable-asset-playbook.md.
Artifact Contract
Output path: docs/forsvn/artifacts/marketing/seo-[mode].md (mode ∈ {audit, ai, programmatic, competitor, aso}). On re-run, rename existing to seo-[mode].v[N].md and create new with incremented version.
Frontmatter (REQUIRED): skill: optimize-seo, mode, version (int), date, status.
Body sections (REQUIRED): Diagnosis / Findings / Priority Actions / Implementation Plan / Dependencies / Metrics to Track / Next Step.
Full template + finding format (Issue / Impact / Evidence / Fix / Priority) + per-mode metrics defaults: references/format-conventions.md [PROCEDURE].
Anti-Patterns
17 patterns (9 SEO-specific + 4 retrieval-layer + 4 cross-cutting marketing-stack) with detection rules, bad/good examples, and per-pattern agent ownership verified against critic-agent.md Rewrite Routing: references/anti-patterns.md [ANTI-PATTERN].
Most common in practice: "Consider improving" (gate 3 hedge-language), "Do SEO" without diagnosis (no mode chosen), Ignoring third-party presence for AI SEO (gate 8 — third-party drives ~6.5x more AI citations than owned), AI-SEO work before technical crawl/index fixes (#13 — retrieval-layer optimization on uncrawlable pages is wasted work).
Durable Rules (protected)
Completion Status
Every run ends with explicit status:
- DONE — selected mode executed end-to-end, recommendations specific and prioritized, critic PASS within 2 cycles
- DONE_WITH_CONCERNS — analysis delivered with data gaps (rank tracker unavailable, GSC not connected, low-confidence competitor data); recommendations annotated
- BLOCKED — site/property inaccessible (auth wall, robots block, no URL provided); cannot scan. State exactly what's blocked + what unblocks.
- NEEDS_CONTEXT — audience or product context missing for relevance scoring; recommend
research-icp or proceed with explicit scope reduction
Worked Example
End-to-end Route A walkthrough (Pre-Dispatch → parallel Layer 1 → merge → prioritization → critic PASS → deliver → FAIL handling → --fast variant): references/examples/seo-walkthrough.md [EXAMPLE].
References
- Playbook:
references/playbook.md [PLAYBOOK]
- Format:
references/format-conventions.md [PROCEDURE]
- Anti-patterns:
references/anti-patterns.md [ANTI-PATTERN]
- Procedures:
references/procedures/{pre-dispatch, dispatch-mechanics}.md + references/agent-manifest.md [PROCEDURE]
- Example:
references/examples/seo-walkthrough.md [EXAMPLE]
- Domain catalogs (loaded by agents at dispatch, not orchestrator):
references/{technical-audit, technical-crawler-checklist, ai-seo, retrieval-layer-seo, live-serp-remediation, programmatic-seo, programmatic-template-playbooks, geo-citation-readiness-checklist, linkable-asset-playbook, competitor-pages, schema-reference, aso, platform-search}.md. Shared: references/_shared/evidence-classes.md (canonical: skills/marketing/_shared/evidence-classes.md, shared with monitor-aeo).
- AI-search control surface:
references/platform-intelligence/bing-readiness.md (Route B). See also Route B/C hooks under Routing Logic.
- Platform intelligence (loaded by ai-presence-agent, programmatic-template-agent, comparison-page-agent, aso-keyword-agent, aso-listing-agent when their mode is active):
references/_shared/platform-intelligence/{tiktok, reels, shorts, linkedin, x, youtube}.md — canonical at top-level references/platform-intelligence/ (D13). Agent-to-section map in references/platform-search.md.
- Shared:
references/_shared/{before-starting-check, manifest-spec, mode-resolver, pre-dispatch-protocol}.md
- Agents: 15 sub-agents in
agents/ — see Agent Manifest above. critic-agent.md holds the canonical 10-item quality gate + 11-row Rewrite Routing Table.
