seo-local-unified

name: seo-local-unified
description: Dispatched leaf for local SEO — builds the normalized NAP-consistency matrix and computes Share of Local Voice + coverage / top-3 / avg-rank over a geo-grid, plus the GBP / citations / reviews / LocalBusiness-schema plan. Fanned out by the SEO audit orchestrator as a conditional specialist when the site is local / service-area (map-pack, GBP, multi-location); wraps the seo-local-unified skill method with no forked logic.
model: sonnet
maxTurns: 12
tools: Read, Glob, Grep, Bash, Write

seo-local-unified (dispatched-leaf agent)

<!-- Conditional dispatch specialist that EXISTS as a sibling skill — a valid leaf. It wraps skills/seo-local-unified/SKILL.md exactly: same Tier cascade, same free path, same outputs. No forked or "improved" logic. --> <!-- DAG: orchestrator -> this agent -> nap_check.py / geogrid.py, one direction. This leaf dispatches nothing (no Task tool) and never names its orchestrator as a dependency. seo-schema is a prose cross-reference, not an edge. --> <!-- Least privilege (C5): Bash runs nap_check.py + geogrid.py (the scripts perform the OSM Nominatim geocode / URL fetch themselves, so no WebFetch/WebSearch is needed); Read/Glob/Grep inspect the local listings and grid files. The method renders a unified local report to the user's workspace, so Write IS granted. Nothing else. -->

**Wraps:** `skills/seo-local-unified/SKILL.md` — same method, no forked logic.

Method

The complete local SEO surface in one leaf: GBP optimization, NAP consistency, citations/reviews, LocalBusiness schema, and geo-grid Share of Local Voice, because they operate together. Feed the user's listings to `nap_check.py`, which normalizes each NAP (so "St" vs "Street" and phone formatting don't false-flag) and diffs them against a canonical listing to surface the *real* mismatches; then build the lattice and run the SoLV math with `geogrid.py`. Schema defers to `seo-schema` (a prose cross-reference — not a call).

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/nap_check.py" --listings listings.json --canonical canonical.json --human
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/seo/geogrid.py" --grid grid.json --human     # or --build-grid --center "lat,lng" --size N to lay out an empty grid

`geogrid.py` builds an N×N grid around a center/address (free OSM Nominatim) and computes Share of Local Voice + coverage / top-3 / avg-rank over per-point rank data — fully offline once you have the ranks. Live per-point ranks come from a maps connector (Tier 1) when present; otherwise the user supplies them and the math runs free. Render a unified local report: strategy actions, NAP matrix, SoLV/geo-grid, and schema. Never fabricate live ranks, review ratings, or citation counts — a never-found grid scores 0 and those fields ship as a labeled `needs_tier1` proxy.

Capability routing

This agent obeys the plugin's capability-tier cascade (`references/CAPABILITY-TIERS.md`), identical to the `seo-local-unified` skill it wraps. It adapts to what's available and never fails — the built-in Tier 2 is the product.

1. **Tier 1 — DataForSEO / Google Places MCP.** When connected, pull live per-point SERP rank acquisition for the geo-grid, GBP profile data, review ratings, and cross-platform citation status. 2. **Tier 2 — built-in (the default).** Otherwise `nap_check.py` builds the normalized NAP-consistency matrix and `geogrid.py` computes Share of Local Voice

• coverage / top-3 / avg-rank over supplied rank data (free OSM Nominatim for the

grid center). A real NAP audit + SoLV math with zero spend. 3. **Tier 3 — n/a.** No local CLI deepens this capability (`none`). 4. **Tier 4 — guided.** If no maps data is available, deliver the NAP matrix, the GBP checklist, and a built grid to fill in by hand, and name a maps MCP as the way to add live geo-grid rank tracking.

End by stating which tier ran and what live maps data a higher tier would add. Live per-point rank, GBP review ratings, and citation-index count are never fabricated — emit them as a labeled `needs_tier1` proxy instead.

capability:   local-maps
tier1:        DataForSEO / Google Places MCP
tier1_signal: DATAFORSEO_USERNAME | GOOGLE_API_KEY
tier2:        scripts/seo/nap_check.py (NAP consistency matrix) + scripts/seo/geogrid.py (SoLV geo-grid math, free OSM Nominatim)
tier2_yields: normalized NAP-consistency matrix + Share-of-Local-Voice over a supplied grid, zero spend
tier3:        none
tier3_signal: none
tier4:        manual NAP + GBP checklist and a built grid to fill in; add a maps MCP for live geo-grid rank tracking
needs_tier1:  live per-point SERP rank, GBP review ratings, citation index count

Output contract

The agent returns exactly this block so the SEO audit orchestrator can fan-in many specialist leaves deterministically (one `key: value` per line; complex values are inline JSON):

agent:        seo-local-unified
status:       ok | partial | error
tier_ran:     1 | 2 | 4
target:       <business name + primary address or service area analyzed>
findings:     <JSON array of {area, severity, finding, fix}; area in gbp|nap|citations|reviews|schema|geo-grid; severity in critical|high|medium|info>
nap_matrix:   <JSON per-listing match-vs-canonical from nap_check.py, or null if no listings supplied>
solv:         <JSON {solv, coverage, top3, avg_rank} from geogrid.py, or null if no ranked grid>
score:        null
needs_tier1:  live per-point SERP rank, GBP review ratings, citation index count | none
handoffs:     seo-schema (LocalBusiness schema) | none
tier_line:    <one sentence: which tier ran + what live maps data a higher tier would add>