Seo Geo Aeo

SEO / GEO / AEO

The whole game: one body of work, two consumers, three surfaces. Classic search ranks pages; generative and answer engines cite passages. Both reward the same substrate — crawlable, well-structured, genuinely authoritative content — so you do not run three programs. You run one, and you measure three surfaces: organic rank (SEO), citations inside AI answers (GEO), and answer-box / featured presence (AEO).

Two rules keep this honest:

• Evidence-ranked, not vibes. The moves are quantified (see the ladder). Lead

with what is measured; the field is full of confident tactics that do nothing.

• Measure the surface, do not assume it. Every number the skill reports is

tagged measured (a tool produced it) or estimated (it was reasoned from the page). Never present an estimate as a fact. This is the discipline that makes multi-tool data trustworthy and progress-tracking real.

The credibility edge is calibration: Google's own guidance (2026) says AI search is still search and that structured data and llms.txt are not required; Ahrefs' server logs show 97% of llms.txt files are never fetched. A skill that oversells those tactics is worse than useless. See "Honesty rails."

Modes

Invoked as /stone-giant:seo-geo-aeo , or triggered automatically when the user asks about SEO / GEO / AEO / AI-search visibility. `` is a URL, a sitemap URL, or a local site/repo path.

| Mode | Does | Writes | | --- | --- | --- | | assess | Audit current state across 7 scored dimensions | a dated scorecard | | playbook | Turn the scorecard's gaps into a prioritized, evidence-weighted plan | a playbook | | track | Diff a fresh assessment against the last scorecard + open playbook items | updates history + playbook status | | competitors | Discover the target's real SEO/GEO rivals (filtered, ranked), ready to feed compare | a dated competitor list | | compare | Score the target and one or more competitor URLs on the same 7 dimensions, side by side | a dated comparison | | refresh | Update the skill's own knowledge of the fast-moving GEO/AEO landscape | edits reference.md / connectors/* | | help | Print the usage block below and stop | — |

assess | playbook | track | competitors | compare operate on a target site and are plan-only — they audit, plan, and track; they never edit the site (or the competitors'). Applying playbook items is a separate, explicit step the user drives. refresh operates on the skill itself (see "Staying current").

The competitive loop is a pipeline: competitors (discover) → compare (score head-to-head) → playbook (turn beatable gaps into items).

Routing: on help (or --help/-h), print the usage block and stop. With no mode and no target, print the usage block, then offer to run assess. With a bare target and no mode: no prior scorecard → assess; one present → offer track.

Target resolution (all modes). assess takes an explicit `. playbook and track operate on existing docs/seo/ state and resolve the target in this order: **explicit argument → the target in the latest docs/seo/ scorecard under the cwd git root → ask.** This is how playbook/track know which repo's docs/seo/ to read when the cwd is the *code* repo but the audited site is elsewhere; never guess — if no scorecard and no argument, ask. **competitors** takes the target the same way and needs no other argument. **compare needs a target plus at least one competitor**; resolve competitors in this order: **explicit URL arguments → the latest docs/seo/competitors-.md → run competitors on the fly → ask.** That is the pipe: competitors writes the list, compare` consumes it.

Usage (help)

/stone-giant:seo-geo-aeo — audit & improve search + AI-answer visibility (SEO/GEO/AEO)

  /stone-giant:seo-geo-aeo assess    Score current state → docs/seo/scorecard-.md
  /stone-giant:seo-geo-aeo playbook            Prioritized, evidence-tiered plan from the latest
                                   scorecard (plan-only — never edits your site)
  /stone-giant:seo-geo-aeo track               Diff a fresh assessment vs the last scorecard;
                                   update playbook status + docs/seo/history.md
  /stone-giant:seo-geo-aeo competitors 
                                   Discover real rivals (filtered, ranked) →
                                   docs/seo/competitors-.md (feeds compare)
  /stone-giant:seo-geo-aeo compare  [competitor…]
                                   Score the target and competitor URLs on the same
                                   7 dimensions → docs/seo/comparison-.md
                                   (competitors default to the latest discovery list)
  /stone-giant:seo-geo-aeo refresh             Web-sweep the volatile GEO/AEO landscape and
                                   update the skill's own reference/connectors
  /stone-giant:seo-geo-aeo help                Show this help

Data sources: Google Search Console, GA4, Lighthouse, on-page parse, schema,
DataForSEO (pay-per-use — no subscription needed), Semrush, Ahrefs — read via
API → MCP → pasted screenshot (degrades gracefully). Every metric is tagged
measured vs estimated. Progress lives in docs/seo/.

Establish provenance first — ask before assuming

Step 0 — ask, do not assume. Before scoring, tell the user which sources would sharpen the assessment and ask which they can provide credentials for. A source is "unavailable" only after the user has been asked and declined or omitted it — never because a key did not happen to be in the environment already. Silently downgrading a source the user could have supplied is a bug, not graceful degradation. Present the list (GSC, GA4, PageSpeed, DataForSEO, Semrush, Ahrefs, AI-visibility), note any already configured (see "Credentials & setup"), and ask about the rest.

• **DataForSEO is the pay-per-use default for competitor, backlink, and

AI-citation data** — it needs no Semrush/Ahrefs subscription (just a prepaid wallet, cents per call), so for users without those seats it is the recommended way to feed dimensions 4 and 6. Offer it first to subscription-less users; it does not replace Semrush/Ahrefs for those who already have them (use whichever key exists — see connectors/dataforseo.md for the two endpoints that need a $100/mo activation vs the pay-per-use core).

• Set expectations on paid tools: Semrush/Ahrefs are wired to API/MCP only;

without a key the user can still paste a screenshot/export, but there is no silent fallback to scraping them. On-page signals and crawl data are always free (local parse — no key).

Then, for each dimension, determine how its data will arrive, in this preference order — and degrade gracefully, never block:

1. API (ideal) — structured, dated, repeatable. The connector file names the

endpoint + scope + its env var.

1. MCP — if a server for that tool is already connected, call it.
2. Paste / screenshot / CSV export — the connector file knows what each

tool's key screen looks like and where the numbers sit, so a pasted image or export is parseable. This keeps every source usable with zero paid access.

1. Reason from the page — last resort; the value is tagged estimated.

Record provenance per metric: {value, source, method: api|mcp|parse|fetch|screenshot|manual|estimated, date}. method records how the value was obtained, not whether it's trustworthy: api = external structured API or equivalent tool (GSC/GA4/PageSpeed/Lighthouse/ DataForSEO/Semrush/Ahrefs); mcp = a connected MCP server; parse = a local parse of fetched page content (on-page HTML, JSON-LD); fetch = a plain HTTP fetch of a file's presence/content (llms.txt, robots.txt); screenshot = pasted image / CSV export; manual = hand-recorded (e.g. the AI-citation protocol); estimated = reasoned from the page. **Everything except estimated is measured — that's the trust axis track honors; the rest of method is transport. track only ever diffs same-source** series — it will not compare a Semrush estimated position against a GSC measured one.

Report grand totals, not summed top-N. When a source exposes a property/grand total (GSC clicks & impressions, GA4 sessions), query that, not the sum of a top-N breakdown — a top-10 query sum silently omits the long tail and undercounts (a real GSC run: top-10 sum = 19 impressions vs the true total of 938). Pull breakdowns separately, with a high row limit, only when you need them.

Credentials & setup (.env)

Credentials are read from exact, documented environment variables — set them once in the target project's .env (git-ignored) or your shell; .env.example in this skill lists every name. Standard names:

| Source | Variable(s) | | --- | --- | | Google Search Console | GSC_PROPERTY, and GSC_ACCESS_TOKEN or GSC_SERVICE_ACCOUNT_JSON (path) | | Google Analytics 4 | GA4_PROPERTY_ID, and GA4_ACCESS_TOKEN or GA4_SERVICE_ACCOUNT_JSON (path) | | PageSpeed Insights | PAGESPEED_API_KEY (lifts the small anonymous quota — see lighthouse connector) | | DataForSEO | DATAFORSEO_LOGIN + DATAFORSEO_PASSWORD — one account ≈ SERP + keyword volume + competitor backlinks + LLM-mention/AI-Overview citations. Core is pay-per-use; Backlinks API and LLM Mentions are optional add-ons that each need a $100/mo activation — gate on it, fall back if absent (see the connector) | | Semrush | SEMRUSH_API_KEY | | Ahrefs | AHREFS_API_TOKEN | | AI-visibility (optional) | OTTERLY_API_KEY |

Security (non-negotiable). Credentials live in env vars and their values must never enter the session. Reference each var by name and let the shell expand it inside the request command (curl -u "$SEMRUSH_API_KEY:", --header "Authorization: Bearer $AHREFS_API_TOKEN"), so the secret goes from the environment straight to the tool and never appears in any command's output or context. Do not printenv/echo/cat a value to inspect it — not even to "check" it. To confirm a var is present, test existence only and print a boolean: [ -n "${VAR:-}" ] && echo set || echo unset. Never list, dump, or grep the environment to discover keys, and never cat/grep a .env to fish for them — that surfaces unrelated secrets. If a var isn't in the shell, try running the request from a login shell (zsh -lc '...') so it inherits the user's exported env; if still unset, ask the user — do not go looking. Never write a key's value into a scorecard.

Connector specifics live in connectors/.md (loaded on demand): Google Search Console, GA4, Lighthouse/PageSpeed, on-page parse, and schema validation are documented to full API+MCP+screenshot depth; DataForSEO, Semrush, Ahrefs, and AI-visibility tools to API/MCP depth. On-page and schema are free local parses (no key). connectors/_template.md is the shape for adding a new one.

Phase 1 — Site discovery (before scoring)

Never score a single landing page and call it a site audit. A finding like "missing About page" or "no FAQ content" is only credible after a crawl proves the page genuinely isn't there. So assess discovers the site first, then scores over the page map:

1. Fetch the target URL, then /robots.txt and /sitemap.xml (or the sitemap

named in robots.txt). Respect robots directives.

1. Build a page map from nav, footer, and sitemap links (same-host only).
2. Pick the scope:

• assess quick — homepage + up to ~6 highest-signal pages (services,

pricing, about, a flagship blog post). The 30-second smoke test.

• assess full (default) — all content pages; skip only legal, login, and

thank-you/utility pages.

1. **Never mark a content type "missing" unless it's absent across the whole

crawl.** Tie dim-2/3/4 findings to specific crawled URLs.

1. Record every visited page in the scorecard's pages_audited table (url, type,

note) — this is what makes a "missing X" finding defensible and lets track diff coverage between runs.

The on-page pass (connectors/on-page.md) runs over this page map, so sitewide patterns (duplicate titles, missing meta descriptions) surface instead of hiding in a one-URL view.

Grade bands (A–F, applied per dimension)

Letter grades must mean the same thing across runs, or track diffs are noise. Anchor to observable thresholds where a metric exists; otherwise apply these bands:

| Grade | Score | Meaning | | --- | --- | --- | | A | 90–100 | Exemplary — measured-strong, no material gaps for this dimension | | B | 75–89 | Strong — minor, low-effort gaps only | | C | 60–74 | Adequate — several real gaps; partial coverage | | D | 40–59 | Weak — major gaps; the dimension is underbuilt | | F | 0–39 | Absent or actively harmful (signal missing, or e.g. AI bots blocked unintentionally, CWV poor) |

Anchor examples (prefer measured thresholds over vibes): dim 1 A = all Core Web Vitals "good" and no unintended crawl blocks; F = CWV poor or indexable pages noindex'd / wanted AI bots blocked. dim 6 A = brand cited across multiple engines on its core queries; F = zero citations anywhere with competitors owning them. When a dimension is scored from reasoning rather than a tool, the grade is tagged estimated alongside its band.

The 7 assess dimensions

Each is scored A–F (see "Grade bands") with located findings and per-metric provenance. The connector(s) that can feed real data are noted; absent them, score by reasoning and tag the result estimated.

> The inline Feeds: notes below are point-of-use pointers. The authoritative > source-of-truth for which connector feeds which dimension is each connector's own > feeds: header (connectors/.md); if the two ever disagree, the connector > wins, and a newly added connector declares its feeds: there first. This keeps the > mapping from drifting as connectors are added.

1. Crawlability, technical & on-page — robots.txt (including the major

AI-crawler user-agents — GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, … — are you blocking the ones you want indexed?), sitemap health, status codes, render/hydration, Core Web Vitals / page experience, and the classic on-page signals: title tags (present/unique/length), meta descriptions, canonical + robots meta, H1 singularity, Open Graph/Twitter cards, image alt text, internal-link/anchor quality, and URL structure. Feeds: Lighthouse/PageSpeed, GSC (coverage, CWV), on-page parse, Ahrefs Site Audit.

1. Content extractability — front-loaded answers, clean heading hierarchy,

question-shaped headings that mirror conversational queries, and lists/tables that chunk cleanly into a citable passage. This is the genuine core of "AEO." Score it as a procedural checklist of located findings: direct-answer paragraphs (40–60 words under a question heading), "X is…" definition patterns, list/table snippet eligibility, FAQ/HowTo eligibility (cross-ref dim 5 — weight as Tier 2/3, no schema hype), and a single clean H1 per page. Feeds: on-page parse.

1. Evidence density — direct quotations, concrete statistics, and inline

citations. The highest-leverage GEO levers (see the ladder); especially in fact-dense domains (health, law, finance).

1. Entity & authority — Organization/Author identity, sameAs links to

Wikipedia/LinkedIn/Crunchbase, topical authority, E-E-A-T signals, and freshness (dateModified). Look for E-E-A-T on the Phase-1 page map — About, Team/author bios, Contact, consistent NAP (name/address/phone), testimonials — rather than asserting it from the homepage alone. Off-page authority (backlink rank, referring-domain count, anchor health, competitor link gap)

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stonegiantstudio
• Source: stonegiantstudio/skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.