akili-specs 2.14.0 → 2.15.0

package/.claude/commands/akili-seo.md

@@ -137,6 +137,7 @@ Produce `docs/specs/$SPEC_PATH/seo-setup-report.md` documenting:
 - Record every finding with its structure: **Issue / Impact / Evidence / Fix / Priority**.
 - Respect its schema-detection limitation: static fetches (`curl`, `web_fetch`) cannot see JS-injected JSON-LD. Validate structured data via `url_inspection_inspect.richResultsResult` or a rendering tool, never via static HTML alone.
 - Apply its International SEO checklist (hreflang reciprocity, self-reference, `x-default`, cross-locale canonicals, locale sitemaps) whenever the site serves multiple languages or regions.
+- Apply its **GEO** section (Step 2.8) for generative-engine visibility. GEO is a layer on top of ranking, never a substitute — run the priority order first. When citing a magnitude, carry the skill's source tier: the KDD 2024 figures are peer-reviewed; AI Overview and crawler-behaviour figures are industry analyses and must not be presented as measured fact.
 
 Use `systematic-debugging` when results are inconsistent with site reality.
 
@@ -210,6 +211,24 @@ For the pages sampled in Step 2.5, apply the on-page checklist from the `seo-aud
 
 Record each failure as a finding using the skill's Issue / Impact / Evidence / Fix / Priority structure.
 
+#### Step 2.8 — GEO audit (generative-engine visibility)
+
+For the same sampled pages, apply the `seo-audit` skill's **GEO** section (evidence and sources in its
+`references/geo.md`). Highest-yield checks first — the measured gains come from evidence, not markup:
+
+- **Evidence density:** claims carry verifiable statistics with named sources; credible quotations where the topic supports them; outbound citations to reliable sources.
+- **Self-containment test:** for each passage the page wants cited, confirm it still makes sense lifted out with no surrounding context. Flag anaphora that depends on the previous paragraph ("this approach", "as mentioned above"). No on-page check above catches this.
+- **Definitional sentences:** each term the page wants to own has a *"X is a Y that does Z."* sentence at first use.
+- **Entity resolution:** the page states in one sentence what the subject is and who made it; `Person`/`Organization` node with `sameAs`.
+- **Freshness:** `dateModified` exposed and truthful; no stale visible version numbers or dates.
+- **AI crawler directives:** `robots.txt` separates training agents (`GPTBot`, `ClaudeBot`, `Google-Extended`) from retrieval agents (`OAI-SearchBot`, `Claude-SearchBot`, `PerplexityBot`). A blanket AI-bot block removes the site from AI answers too — confirm the owner's intent before calling either state correct.
+- **Unverifiable claims:** flag numeric or superlative claims in `<title>`, meta description, or JSON-LD that no source supports.
+
+**Do not raise:** a missing `llms.txt` (no measured visibility effect — see the skill), or any finding
+that asserts engagement metrics such as bounce rate affect rankings.
+
+Record each failure in the same Issue / Impact / Evidence / Fix / Priority format.
+
 ---
 
 ### Phase 3: Write `seo-audit-report.md`
@@ -227,8 +246,9 @@ Required sections:
 7. Render Audit
 8. Internal Linking Findings
 9. On-Page SEO Findings — Step 2.7 results, each in the `seo-audit` Issue / Impact / Evidence / Fix / Priority format.
-10. Remediation Plan — prioritized (High / Medium / Low) actionable items, each scoped enough that an implementer can execute it without further discovery.
-11. Re-audit Schedule — when to run `/akili-seo <domain>` again.
+10. GEO Findings — Step 2.8 results, same format. State the source tier next to any magnitude cited, and keep GEO items ranked below blocking classic-SEO fixes in the remediation plan (GEO layers on ranking, it does not substitute for it).
+11. Remediation Plan — prioritized (High / Medium / Low) actionable items, each scoped enough that an implementer can execute it without further discovery.
+12. Re-audit Schedule — when to run `/akili-seo <domain>` again.
 
 The report title must be `# SEO Audit Report — <domain>`.
 
@@ -268,6 +288,8 @@ After the command completes, verify:
 - [ ] Every URL in the sitemap is either audited or explicitly excluded with a reason.
 - [ ] Every structured-data warning is reproduced with the exact bad value and the exact fix.
 - [ ] On-page findings from Step 2.7 use the `seo-audit` Issue / Impact / Evidence / Fix / Priority format.
+- [ ] GEO findings from Step 2.8 are present, carry their source tier where a magnitude is cited, and rank below blocking classic-SEO fixes in the remediation plan.
+- [ ] No finding claims engagement metrics (bounce rate, time on page) affect rankings, and none flags a missing `llms.txt`.
 - [ ] The implementation prompt is self-contained and would not require this conversation to execute.
 
 ---

package/.claude/skills/seo-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: seo-audit
-description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. In AKILI-SPECS projects, /akili-seo loads this skill in its audit phase.
+description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Also covers generative-engine visibility (GEO/AEO): "AI Overviews," "AI search," "not showing up in ChatGPT," "get cited by AI," "GEO," "answer engine optimization," "llms.txt," "AI crawlers," "GPTBot," or "ClaudeBot." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. In AKILI-SPECS projects, /akili-seo loads this skill in its audit phase.
 license: MIT
 metadata:
   author: Corey Haines (coreyhaines31)
@@ -8,7 +8,7 @@ metadata:
   adapted-by: "Juan Carlos Cadavid — jcadavid.com"
   adapted-for: "AKILI-SPECS"
   binding: core
-  version: 2.0.0
+  version: 2.1.0
 ---
 
 # SEO Audit
@@ -61,6 +61,11 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
 4. **Content Quality** (does it deserve to rank?)
 5. **Authority & Links** (does it have credibility?)
 
+**GEO is a layer, not a sixth priority.** Generative-engine visibility (AI Overviews, ChatGPT,
+Perplexity) is applied *on top of* pages that already rank or can — roughly three quarters of AI
+Overview citations come from pages already in the top 10. Never trade a fix from the list above for a
+GEO fix. Run the priority order first, then apply the [GEO section](#generative-engine-optimization-geo).
+
 ---
 
 ## Technical SEO Audit
@@ -71,6 +76,13 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
 - Check for unintentional blocks
 - Verify important pages allowed
 - Check sitemap reference
+- **`Disallow` is not `noindex`.** A disallowed URL can still be indexed (from external links) and will show as "Indexed, though blocked by robots.txt". To remove a page from the index you must let Google crawl it and serve `noindex` — blocking it prevents Google from ever seeing the directive. A `noindex` line inside `robots.txt` is unsupported and ignored.
+
+**AI crawler directives** (see [GEO reference](references/geo.md) for the full agent table)
+- Distinguish **training** agents (`GPTBot`, `ClaudeBot`, `Google-Extended`) from **retrieval** agents (`OAI-SearchBot`, `Claude-SearchBot`, `PerplexityBot`) and user-triggered fetchers (`ChatGPT-User`, `Claude-User`, `Perplexity-User`)
+- **High-impact finding:** a blanket AI-bot block removes the site from AI answers as well as from training corpora. Confirm the client's intent before treating either state as correct
+- `Google-Extended` is a robots.txt token only — it never appears in logs, and blocking it does not affect `Googlebot`, Search, or AI Overviews
+- Where the requirement is genuine prevention rather than preference, note that robots.txt is advisory and escalate to WAF/bot management
 
 **XML Sitemap**
 - Exists and accessible
@@ -338,6 +350,30 @@ Three equivalent placement methods: HTML `<link>` in `<head>`, HTTP `Link` heade
 - No keyword cannibalization
 - Logical topical clusters
 
+### Structured Data
+
+Read the **Schema Markup Detection Limitation** above before auditing this — a static fetch cannot
+see JS-injected JSON-LD, and reporting "no schema found" from `curl` output is a false finding.
+
+**Check for:**
+- Correct type for the page's purpose (`Article`/`TechArticle`, `Product`, `FAQPage`, `HowTo`, `BreadcrumbList`, `Organization`, `Person`, `SoftwareApplication`, `LocalBusiness`)
+- Validates without errors in the Rich Results Test
+- Markup matches **visible** page content — invisible or contradictory markup is a spam-policy violation, not an optimization
+- `dateModified` present and truthful on content that changes
+- Entity nodes (`Organization` / `Person`) carry `sameAs` links to authoritative profiles
+- `@id` used consistently so nodes can reference each other instead of being duplicated
+- One coherent graph per page rather than several disconnected islands
+
+**Common issues:**
+- Required properties missing, so the type is ineligible for rich results
+- `FAQPage` markup on content that is not a genuine Q&A
+- Schema describing content the user cannot see
+- Stale `dateModified` auto-set to build time on unchanged pages
+- Duplicate `Organization` nodes on every page with no shared `@id`
+
+Structured data also has a measurable association with citation in generative answers — see the
+[GEO section](#generative-engine-optimization-geo).
+
 ---
 
 ## Content Quality Assessment
@@ -373,12 +409,86 @@ Three equivalent placement methods: HTML `<link>` in `<head>`, HTTP `Link` heade
 - Better than top-ranking competitors
 - Updated and current
 
-### User Engagement Signals
+### User Engagement Signals — diagnostic only, not ranking factors
+
+**Google does not use analytics engagement metrics as ranking factors.** John Mueller: *"We don't use
+bounce rate in search rankings."* Gary Illyes: *"we don't use analytics/bounce rate in search
+ranking."* Google has denied this for roughly a decade.
+
+Never write a finding that says "improve bounce rate to improve rankings" — it is a causal claim
+Google has explicitly denied, and it damages the credibility of the correct findings next to it.
+
+Use these metrics the other way round: as **diagnostics that localize a content problem**, whose fix
+is the content itself.
+
+| Metric | Read it as |
+|---|---|
+| High exit rate on a ranking page | Possible intent mismatch — the page ranks for a query it does not answer |
+| Very low time on page for long-form content | Content may be unscannable, or the answer is buried |
+| Pages per session | Internal linking and topical-cluster coverage signal |
+| Return visits | Brand and content-quality signal (correlates with, does not cause, ranking) |
+
+- Sources and exact quotes: [SEJ: Is bounce rate a Google ranking factor?](https://www.searchenginejournal.com/ranking-factors/bounce-rate/)
+
+---
+
+## Generative Engine Optimization (GEO)
+
+Visibility inside AI-generated answers — Google AI Overviews / AI Mode, ChatGPT, Claude, Perplexity —
+rather than in a ranked list of links. See the [GEO reference](references/geo.md) for the measured
+evidence, source tiers, and the full AI-crawler agent table.
+
+**GEO layers on top of ranking; it does not replace it.** Roughly three quarters of AI Overview
+citations come from pages already in the top 10. Audit the priority order first.
+
+### What measurably works
+
+Peer-reviewed measurement (GEO-bench, KDD 2024: ~10,000 queries across nine datasets) found the
+largest visibility gains come from **evidence, not markup**:
+
+| Finding to raise | Measured effect |
+|---|---|
+| Claims lack **verifiable statistics** with named sources | ~30–40% gain when added |
+| No **credible quotations** where the topic supports them | ~30–40% |
+| No **outbound citations** to reliable sources | ~30–40% |
+| Poor fluency / readability | ~15–30% |
+| Keyword stuffing present | Negligible or **negative** — treat as a defect, not a tactic |
+
+Gains are largest for content that is visible but not dominant (up to +115.1% at position 5), which
+is most audit subjects.
+
+### The self-containment test
+
+Generative engines extract **passages**, not pages. For each passage the page wants cited, ask:
+*does this paragraph still make sense lifted out with no surrounding context?*
+
+Anaphora that depends on the previous paragraph ("this approach", "as mentioned above", "the former")
+breaks extraction. This is the most common GEO defect on otherwise well-optimized pages, and **no
+classic on-page check catches it**.
+
+Also require: a **definitional sentence** (*"X is a Y that does Z."*) at first use of every term the
+page wants to own, and a Q&A block with the question as the heading and the direct answer in the
+first sentence.
+
+### Checks
+
+- [ ] Verifiable statistics, quotations, and outbound citations present
+- [ ] Target passages pass the self-containment test
+- [ ] Definitional sentence at first use of each ownable term
+- [ ] Entity resolvable in one sentence (what it is, who made it); `Person`/`Organization` + `sameAs`
+- [ ] `dateModified` exposed; no stale visible version numbers or dates (fresh content is cited far more often)
+- [ ] JSON-LD present and valid (see Structured Data above)
+- [ ] robots.txt separates training agents from retrieval agents, matching the client's stated intent
+- [ ] No unverifiable numeric or superlative claims in `<title>`, meta description, or JSON-LD
+
+### Do not raise these
 
-- Time on page
-- Bounce rate in context
-- Pages per session
-- Return visits
+- **Missing `llms.txt`.** Adoption is ~8.7% of the top 1,000 domains, ~40% of existing files are
+  empty plugin stubs, no major AI crawler has committed to consuming it, crawler logs show the
+  retrieval agents skip it, and in one citation model removing the variable *improved* accuracy. It
+  has a legitimate use as business-to-agent context for IDE agents and MCP servers — recommend it on
+  developer-experience grounds or not at all, never as a visibility tactic.
+- **"Improve bounce rate to rank better."** See User Engagement Signals above.
 
 ---
 
@@ -459,6 +569,7 @@ Same format as above
 
 - [AI Writing Detection](references/ai-writing-detection.md): Common AI writing patterns to avoid (em dashes, overused phrases, filler words)
 - [International SEO](references/international-seo.md): Evidence and sources for hreflang, canonical + i18n, sitemaps, URL structure, and content quality across locales
+- [GEO](references/geo.md): Evidence and sources for generative-engine visibility — the KDD 2024 measurement of what works, passage-level extraction, freshness, structured-data correlation, the AI-crawler agent table (training vs retrieval), and why `llms.txt` is not a visibility tactic
 
 ---
 
@@ -503,4 +614,5 @@ Adaptation rules:
 
 - Findings land in the AKILI report artifacts (`/akili-seo` output), using the Issue / Impact / Evidence / Fix / Priority shape.
 - Fixes that exceed the trivial gate are routed through `/akili-propose` — never applied silently during the audit.
-- Sibling skills mentioned by upstream versions of this skill (programmatic-seo, schema, ai-seo, cro, analytics) are **not packaged** with AKILI-SPECS; when a finding needs them, note the gap in the report instead of loading them.
+- GEO findings use the same Issue / Impact / Evidence / Fix / Priority shape. Label the source tier when citing a magnitude: the KDD 2024 figures are peer-reviewed, the AI Overview and crawler-behaviour figures are industry analyses. Never present an `[INDUSTRY]` number to a client as measured fact.
+- Sibling skills mentioned by upstream versions of this skill (programmatic-seo, cro, analytics) are **not packaged** with AKILI-SPECS; when a finding needs them, note the gap in the report instead of loading them. The upstream `schema` and `ai-seo` gaps are now covered in-skill by the **Structured Data** and **GEO** sections.

package/.claude/skills/seo-audit/evals/evals.json

@@ -123,12 +123,27 @@
     {
       "id": 8,
       "prompt": "I want to add FAQ schema to my product pages. Can you help me set that up?",
-      "expected_output": "Should recognize this is a schema markup implementation task, not an SEO audit. Should defer to or cross-reference the schema skill, which specifically handles structured data implementation including FAQ schema. May briefly mention that FAQ schema can enable rich results, but should make clear that schema is the right skill for implementation.",
+      "expected_output": "Should recognize this is a structured-data implementation task, not a full SEO audit, and apply the Structured Data section directly (AKILI-SPECS does not package a separate schema skill). Should require that FAQPage markup describe genuine, visible Q&A content on the page, and warn that markup not matching visible content is a spam-policy violation rather than an optimization. Should note the detection limitation for verification (Rich Results Test or a rendering tool, never curl/web_fetch). May mention that FAQ content is also the densest citable surface for generative engines.",
       "assertions": [
-        "Recognizes this as schema markup implementation",
-        "References or defers to schema skill",
-        "Does not attempt a full SEO audit",
-        "May briefly mention FAQ schema benefits"
+        "Recognizes this as structured-data implementation",
+        "Applies the Structured Data section rather than deferring to an unpackaged schema skill",
+        "Requires markup to match visible page content",
+        "Notes the JS-injection detection limitation for verification",
+        "Does not attempt a full SEO audit"
+      ],
+      "files": []
+    },
+    {
+      "id": 9,
+      "prompt": "We rank on page one for our main keywords but we never show up in Google AI Overviews or ChatGPT. What should we fix?",
+      "expected_output": "Should apply the GEO section. Should lead with the evidence-density findings, which carry the largest measured gains (verifiable statistics with named sources, credible quotations, outbound citations to reliable sources), and cite the KDD 2024 GEO study as the source with its magnitudes labelled as peer-reviewed. Should apply the self-containment test to target passages and flag anaphora that depends on surrounding context. Should check definitional sentences, entity resolution, freshness / dateModified, and structured data. Should audit robots.txt for a blanket AI-bot block that also excludes the retrieval agents (OAI-SearchBot, Claude-SearchBot, PerplexityBot) as distinct from the training agents. Should NOT recommend creating llms.txt as a visibility tactic. Should NOT claim engagement metrics affect rankings. Should note GEO layers on ranking rather than replacing it.",
+      "assertions": [
+        "Prioritizes evidence density (statistics, quotations, citations) as the highest-yield fix",
+        "Applies the self-containment test to passages",
+        "Distinguishes AI training agents from retrieval agents in robots.txt",
+        "Does not recommend llms.txt as a visibility tactic",
+        "Labels industry figures separately from peer-reviewed figures",
+        "States that GEO layers on top of ranking"
       ],
       "files": []
     }

package/.claude/skills/seo-audit/references/geo.md

@@ -0,0 +1,203 @@
+# Generative Engine Optimization (GEO): Evidence & Sources
+
+Visibility inside AI-generated answers (Google AI Overviews / AI Mode, ChatGPT, Claude, Perplexity)
+rather than in a ranked list of links.
+
+**Source tiers used below.** `[PRIMARY]` = peer-reviewed research or first-party vendor
+documentation. `[INDUSTRY]` = vendor or agency analysis of observed data; directionally useful,
+methodology usually undisclosed, treat magnitudes as indicative not exact. Do not present
+`[INDUSTRY]` figures to a client as measured fact.
+
+---
+
+## GEO is not a replacement for SEO
+
+`[INDUSTRY]` 76% of Google AI Overview citations come from pages already ranking in the top 10 —
+classic ranking is the qualifying condition, not an alternative to it. A meaningful long tail exists
+(46.5% of cited URLs rank outside the top 50), so ranking is strongly predictive but not required.
+
+**Audit consequence:** never trade a classic SEO fix for a GEO fix. Run the standard audit priority
+order first; GEO is an additional layer applied to pages that already rank or can.
+
+- [CXL: Where Google AI Overviews cite from — 100-page study](https://cxl.com/blog/google-ai-overview-citation-sources/)
+
+---
+
+## What measurably improves generative visibility
+
+`[PRIMARY]` The GEO study (Aggarwal, Murahari, Rajpurohit, Kalyan, Narasimhan, Deshpande — KDD
+2024) built GEO-bench: ~10,000 queries across nine datasets, against a two-stage pipeline (Google
+Search retrieves top-5 sources, then an LLM synthesizes a cited answer). It tested nine content
+modifications and measured visibility change.
+
+| Modification | Measured effect |
+|---|---|
+| Adding **verifiable statistics** | ~30–40% gain (position-adjusted word count) |
+| Adding **credible quotations** | ~30–40% gain |
+| **Citing reliable sources** | ~30–40% gain |
+| Improving **fluency / readability** | ~15–30% gain |
+| **Keyword stuffing** | negligible or **negative** |
+
+Aggregate reported improvement across successful methods: **22–41%**.
+
+**The Equalizer Effect.** `[PRIMARY]` Gains are largest for lower-ranked sources — up to **+115.1%**
+visibility for content at position 5. GEO disproportionately benefits sites that are visible but not
+dominant, which is precisely the audit population that most needs it.
+
+**Audit consequence:** the three highest-yield GEO findings are all citation-and-evidence findings,
+not markup findings. A page making unsourced claims is a GEO defect even when its technical SEO is
+clean.
+
+- [arXiv: GEO — Generative Engine Optimization (2311.09735)](https://arxiv.org/pdf/2311.09735)
+- [dblp: KDD 2024 record](https://dblp.dagstuhl.de/rec/conf/kdd/AggarwalMRKND24.html)
+- [Princeton: publication record](https://collaborate.princeton.edu/en/publications/geo-generative-engine-optimization/)
+- [Blck Alpaca: methodology and critique of the Princeton GEO study](https://blckalpaca.at/en/knowledge-base/seo-geo/geo-generative-engine-optimization/the-princeton-geo-study-methodology-results-and-critique)
+
+---
+
+## Extraction happens at passage level, not page level
+
+`[INDUSTRY]` Generative engines lift **short, self-contained passages**. Paragraphs that answer one
+specific question are far more likely to be extracted than long blocks where the answer is diluted
+across sentences. Content types cited most: direct answers to specific questions, comparison tables,
+statistics attributed to named sources, and step-by-step instructions.
+
+**Audit consequence — the self-containment test.** For each target passage, ask: *does this
+paragraph still make sense lifted out of the page with no surrounding context?* Anaphora that
+depends on the previous paragraph ("this approach", "as mentioned above", "the former") breaks
+extraction. This is the single most common GEO defect on otherwise well-optimized pages, and it is
+invisible to every classic on-page check.
+
+**Definitional-sentence pattern.** For each term the page wants to own, include one sentence of the
+form *"X is a Y that does Z."* at first use. That sentence is what gets quoted verbatim.
+
+- [Contently: how to get cited in Google AI Overviews (2026)](https://contently.com/2026/02/25/how-to-get-cited-google-ai-overviews/)
+- [CXL: Where Google AI Overviews cite from](https://cxl.com/blog/google-ai-overview-citation-sources/)
+
+---
+
+## Freshness is weighted heavily
+
+`[INDUSTRY]` Content under three months old is reported as ~3x more likely to be cited in AI
+Overviews.
+
+**Audit consequence:** stale version numbers, undated articles, and missing `dateModified` are GEO
+findings, not just hygiene. For tooling and documentation pages specifically, a visible version
+number that lags the shipped release is a direct credibility signal against the page. Prefer reading
+such values from a live source at build time over hardcoding them.
+
+- [Heroic Rankings: Google AI Overview statistics 2026](https://heroicrankings.com/seo/managed/google-ai-overview-statistics-2026/)
+
+---
+
+## Structured data correlates with citation
+
+`[INDUSTRY]` Reported: 65% of pages cited by Google AI Mode carry structured data markup; 71% of
+pages cited by ChatGPT do. Figures span all schema types (`Article`, `Organization`, `Product`,
+`Review`, `FAQPage`, `HowTo`).
+
+**Read this as correlation, not proven causation** — pages with schema also tend to be better
+maintained overall. It is still a cheap, low-risk intervention with a plausible mechanism
+(machine-readable facts survive extraction better than prose).
+
+Highest-value types for GEO:
+
+| Type | Use for |
+|---|---|
+| `FAQPage` | Q&A blocks — the densest citable surface on most pages |
+| `HowTo` | Step-by-step procedures |
+| `TechArticle` / `Article` | Carries `dateModified`, feeding the freshness signal |
+| `SoftwareApplication` | Tools and packages — carries `softwareVersion` |
+| `Person` / `Organization` with `sameAs` | Entity resolution and author authority |
+
+**Entity disambiguation.** State plainly, in one sentence, what the subject *is* and who made it.
+Ambiguous brand names must be resolvable without inference. Bind the page to a `Person` or
+`Organization` node with `sameAs` links to authoritative profiles.
+
+- [Contently: 2026 AI Overview tactics](https://contently.com/2026/02/25/how-to-get-cited-google-ai-overviews/)
+- [Digital Applied: content strategy for AI Overviews, post-I/O 2026](https://www.digitalapplied.com/blog/content-strategy-ai-overviews-post-io-guide-2026)
+
+---
+
+## AI crawler access control
+
+`[PRIMARY]` The agents split by **purpose**, and that split is the whole point of auditing them:
+
+| Vendor | Training | Search / retrieval | User-triggered |
+|---|---|---|---|
+| OpenAI | `GPTBot` | `OAI-SearchBot` | `ChatGPT-User` |
+| Anthropic | `ClaudeBot` | `Claude-SearchBot` | `Claude-User` |
+| Perplexity | — | `PerplexityBot` | `Perplexity-User` |
+| Google | `Google-Extended` | (Googlebot) | — |
+
+**The consequential audit finding:** a site that blanket-blocks AI bots to avoid training also
+blocks the retrieval agents, and therefore removes itself from AI answers entirely. If the goal is
+visibility without feeding training, allow the search and user agents and disallow only the training
+agents.
+
+**`Google-Extended` is a robots.txt token, not a user agent.** It never appears in server logs.
+`Disallow: /` under `Google-Extended` opts out of Gemini training while leaving `Googlebot` — and
+therefore Search and AI Overviews — unaffected. Auditing for it in logs will always produce a false
+negative.
+
+**robots.txt is a request, not enforcement.** `[INDUSTRY]` Cloudflare reported (2025-08-04)
+observing Perplexity using undeclared crawlers that rotate user-agent, IP, and ASN to bypass
+no-crawl directives. When a client's requirement is actually *prevention* rather than *preference*,
+robots.txt is the wrong control — escalate to WAF/bot-management, and say so in the finding.
+
+- [Anagram: AI crawlers explained — GPTBot, ClaudeBot, PerplexityBot (2026)](https://www.anagram.ai/blog/ai-crawlers-explained-gptbot-claudebot-perplexitybot-and-how-to-let-them-in-2026)
+- [AuditAE: AI crawlers list 2026 — ClaudeBot, GPTBot, OAI-SearchBot](https://auditae.app/blog/ai-crawlers-explained)
+- [Witscode: robots.txt strategy 2026 — managing AI crawlers](https://witscode.com/blogs/robots-txt-strategy-2026-managing-ai-crawlers)
+
+---
+
+## llms.txt: do not recommend it for AI search visibility
+
+`[INDUSTRY]` The evidence is consistently negative, and this contradicts widespread advice:
+
+- Adoption is ~8.7% of the top 1,000 domains (June 2026); ~10% in other samples.
+- **39.6% of existing files are empty plugin stubs.**
+- No major AI crawler has committed to consuming the format.
+- Crawler-log analyses find GPTBot, ClaudeBot, PerplexityBot, OAI-SearchBot and Google-Extended
+  **overwhelmingly skip `/llms.txt`** and crawl HTML directly.
+- In one citation-frequency model, **removing the llms.txt variable improved prediction accuracy** —
+  it contributed noise, not signal.
+
+**Audit consequence:** do not raise "missing llms.txt" as a finding, and do not recommend building
+one as a GEO tactic. If a client already has one, leave it. The format does have a real use —
+**business-to-agent context for IDE agents and MCP servers** — which is a developer-experience
+decision, not a search-visibility one. Recommend it on those grounds or not at all.
+
+- [Rankability: llms.txt adoption data — 8.7% of the top 1,000 (June 2026)](https://www.rankability.com/data/llms-txt-adoption/)
+- [aeo.press: the state of llms.txt in 2026](https://www.aeo.press/ai/the-state-of-llms-txt-in-2026)
+- [OrganiKPI: llms.txt adoption and impact](https://organikpi.com/blog/distribution/llms-txt-adoption-impact/)
+
+---
+
+## What does not work
+
+| Tactic | Status |
+|---|---|
+| Keyword stuffing | `[PRIMARY]` Negligible or **negative** effect on generative visibility |
+| Unverifiable superlatives and performance claims | Dropped during extraction; adjacent verifiable claims lose credibility by association |
+| `llms.txt` as a visibility play | `[INDUSTRY]` No measured effect; see above |
+| Blanket-blocking all AI user agents | Removes the site from AI answers along with training corpora |
+| Prose-only pages with no extractable passages | Structurally unciteable regardless of quality |
+
+---
+
+## Audit checklist
+
+- [ ] Page already ranks (or can) for its target query — GEO layers on top of ranking, never replaces it
+- [ ] Claims carry **verifiable statistics** with named sources (highest measured yield)
+- [ ] **Credible quotations** present where the topic supports them
+- [ ] **Outbound citations** to reliable sources present
+- [ ] Every target passage passes the **self-containment test**
+- [ ] Each ownable term has a **definitional sentence** at first use
+- [ ] Q&A block present, question as heading, direct answer in the first sentence
+- [ ] Entity resolvable in one sentence (what it is, who made it)
+- [ ] `dateModified` exposed; visible version/date values not stale
+- [ ] JSON-LD present and valid — `FAQPage` / `HowTo` / `Article` as applicable, plus `Person`/`Organization` with `sameAs`
+- [ ] robots.txt distinguishes **training** agents from **retrieval** agents, and the split matches the client's stated intent
+- [ ] No unverifiable numeric claims in `<title>`, meta description, or JSON-LD
+- [ ] **Not** flagged: missing `llms.txt`

package/CHANGELOG.md

@@ -10,6 +10,20 @@ The format is inspired by Keep a Changelog and the repository follows semantic v
 
 - No unreleased changes yet.
 
+## [2.15.0] - 2026-07-26
+
+### Added
+
+- **GEO (Generative Engine Optimization) in `seo-audit` — visibility inside AI answers, grounded in measured evidence.** New `## Generative Engine Optimization (GEO)` section plus a `references/geo.md` evidence file following the same claims-plus-sources convention as `international-seo.md`. The headline finding, from the peer-reviewed GEO study (Aggarwal et al., **KDD 2024**, GEO-bench: ~10,000 queries across nine datasets), is that **the largest gains come from evidence, not markup**: adding verifiable statistics, credible quotations, and outbound citations each yields ~30–40%, fluency/readability ~15–30%, and **keyword stuffing is negligible or negative**. Gains are largest for content that ranks but does not dominate (up to **+115.1%** at position 5 — the "Equalizer Effect"), which is most audit subjects. Also documented: **passage-level extraction** and the resulting **self-containment test** (a paragraph must survive being lifted out of the page — anaphora like "this approach" breaks extraction, and no classic on-page check catches it), definitional sentences, entity resolution, freshness weighting, and the structured-data citation correlation (65% of AI-Mode-cited pages, 71% of ChatGPT-cited pages) explicitly labelled as correlation, not causation. Every claim carries a `[PRIMARY]` / `[INDUSTRY]` **source tier**, and findings must carry that tier forward so an industry estimate is never presented to a client as measured fact. Wired into `/akili-seo` as **Step 2.8** with a matching report section and verification-checklist rows.
+- **AI-crawler directive auditing.** The `Robots.txt` checks now separate **training** agents (`GPTBot`, `ClaudeBot`, `Google-Extended`) from **retrieval** agents (`OAI-SearchBot`, `Claude-SearchBot`, `PerplexityBot`) and user-triggered fetchers. The consequential finding: **a blanket AI-bot block removes the site from AI answers as well as from training corpora** — a state many sites are in by accident. Records that `Google-Extended` is a robots.txt token that never appears in logs (so auditing for it there always yields a false negative) and that blocking it does not affect `Googlebot` or AI Overviews, and that robots.txt is advisory — where the requirement is genuine prevention, escalate to WAF/bot management.
+- **Structured Data audit section** — a real gap: the skill previously explained *how to detect* schema (the JS-injection limitation) but had no checklist for auditing it. Adds per-purpose type selection, validation, the visible-content match requirement (invisible or contradictory markup is a spam-policy violation, not an optimization), truthful `dateModified`, `sameAs` entity nodes, and consistent `@id` graph wiring. Closes the upstream `schema` sibling-skill gap in-skill.
+
+### Changed
+
+- **Engagement metrics rewritten from ranking factors to diagnostics — correcting a myth the skill propagated.** The `User Engagement Signals` section listed time on page, bounce rate, pages per session, and return visits as things to audit, implying they are ranking factors. Google has denied this for roughly a decade (Mueller: *"We don't use bounce rate in search rankings"*; Illyes: *"we don't use analytics/bounce rate in search ranking"*). The section now states that plainly, **bans findings of the form "improve bounce rate to improve rankings"** as a causal claim Google has explicitly denied that damages the credibility of correct findings beside it, and reframes each metric as a diagnostic that localizes a content problem whose fix is the content.
+- **`Disallow` is not `noindex`.** New robots.txt check for one of the most consequential confusions in technical SEO: a disallowed URL can still be indexed from external links and surfaces as "Indexed, though blocked by robots.txt"; removing a page from the index requires *allowing* the crawl and serving `noindex`, and a `noindex` line inside `robots.txt` is unsupported and ignored.
+- **`llms.txt` is explicitly ruled out as a visibility tactic, against prevailing advice.** Evidence: ~8.7% adoption of the top 1,000 domains (June 2026), ~40% of existing files are empty plugin stubs, no major AI crawler has committed to consuming the format, crawler-log analyses show the retrieval agents skip it and crawl HTML directly, and in one citation-frequency model **removing the variable improved prediction accuracy** — it contributed noise. Both the skill and `/akili-seo` now list "missing `llms.txt`" as a finding that must **not** be raised, while noting the format's legitimate use as business-to-agent context for IDE agents and MCP servers — a developer-experience call, not a search one.
+- **`seo-audit` priority order gains an explicit GEO boundary.** GEO is a layer applied on top of ranking, not a sixth priority: roughly three quarters of AI Overview citations come from pages already in the top 10, so a GEO fix never displaces a classic-SEO fix, and GEO items rank below blocking classic findings in the remediation plan. Skill version 2.0.0 → 2.1.0; trigger keywords extended (AI Overviews, AI search, GEO, answer engine optimization, `llms.txt`, GPTBot, ClaudeBot); upstream `schema`/`ai-seo` sibling-gap note updated now that both are covered in-skill.
 ## [2.14.0] - 2026-07-25
 
 ### Added

package/docs/skills/README.md

@@ -30,7 +30,7 @@ The skill set is **curated, not accumulated**: every skill declares its original
 | [`nestjs-expert`](nestjs-expert.md) | stack | Daniel Avila (MIT) | NestJS modules, DI, guards, interceptors, testing, TypeORM/Mongoose | Skill Map; constitution/specify stack lists; persona examples |
 | [`product-manager-toolkit`](product-manager-toolkit.md) | core | Alireza Rezvani (MIT) | Product discovery, PRDs, prioritization, interview analysis (AKILI-adapted: canonical PRD structure, RICE for scope-chunk ordering) | `/akili-constitution` Steps 2–3, `/akili-propose`, `/akili-specify` scope chunking |
 | [`react-doctor`](react-doctor.md) | stack | Million.dev | React diagnostics after changes | Skill Map; `/akili-test`, `/akili-validate`, `/akili-execute` React work |
-| [`seo-audit`](seo-audit.md) | core | Corey Haines (MIT) | Technical, on-page, and international SEO audits with a standard finding format | `/akili-seo` audit phase (required) |
+| [`seo-audit`](seo-audit.md) | core | Corey Haines (MIT) | Technical, on-page, structured-data, international, and generative-engine (GEO) audits with a standard finding format | `/akili-seo` audit phase (required) |
 | [`shadcn-ui`](shadcn-ui.md) | stack | community (origin unverified) | shadcn/ui components, forms, themes, Tailwind integration | Skill Map; constitution/specify stack lists; persona examples |
 | [`software-architect`](software-architect.md) | core | Juan Carlos Cadavid — jcadavid.com (MIT) | Senior-architect Decision Spine: NFRs as measurable quality-attribute scenarios, tactics, robust-vs-lite tier sizing, architecture styles (hexagonal/clean/microservices), GoF pattern selection, C4 views + ADRs, agentic AI patterns | `/akili-constitution` Step 5 (required) and Step 6 tier handoff; `/akili-specify` Phase 2 for architecturally significant features |
 | [`stitch-design`](stitch-design.md) | conditional | Google — google-labs-code | Stitch prompt enhancement and design generation workflows (fallback UI chain with `frontend-design`) | UI steps of `/akili-constitution`, `/akili-propose`, `/akili-specify` |

package/docs/skills/seo-audit.md

@@ -2,28 +2,40 @@
 
 ## Purpose
 
-Provides an expert SEO audit framework: crawlability and indexation, technical foundations (Core Web Vitals, mobile, HTTPS), on-page optimization (titles, metas, headings, images, internal linking), international SEO (hreflang, locale canonicals, locale sitemaps), content quality (E-E-A-T), and a standard finding format.
+Provides an expert SEO audit framework: crawlability and indexation, technical foundations (Core Web Vitals, mobile, HTTPS), on-page optimization (titles, metas, headings, images, internal linking), structured data, international SEO (hreflang, locale canonicals, locale sitemaps), content quality (E-E-A-T), **generative-engine visibility (GEO)**, and a standard finding format.
 
 AKILI-adapted: findings use the Issue/Impact/Evidence/Fix/Priority shape inside `/akili-seo` artifacts, non-trivial fixes escalate to `/akili-propose`, and dangling references to unpackaged sibling skills were removed. Binding: `core`.
 
+AKILI-original additions (not in the upstream skill): the **GEO** section and `references/geo.md`; the **Structured Data** audit section; AI-crawler directive auditing; the `Disallow` ≠ `noindex` correction; and the rewrite of engagement metrics from ranking factors to diagnostics.
+
 ## Use When
 
 - Auditing, reviewing, or diagnosing SEO issues on a site.
 - Rankings or organic traffic dropped and the cause is unknown.
 - Reviewing meta tags, structured data, page speed, or indexing issues.
+- The site is absent from AI answers (AI Overviews, ChatGPT, Perplexity), or AI-crawler access needs a decision.
 - Running the audit phase of `/akili-seo`.
 
 ## Core Rules
 
 - Findings follow the **Issue / Impact / Evidence / Fix / Priority** structure.
 - Findings are weighted by priority order: crawlability → technical → on-page → content quality → authority.
+- **GEO is a layer, not a sixth priority** — ~3/4 of AI Overview citations come from pages already in the top 10, so a GEO fix never displaces a classic-SEO fix.
+- **Source tiers are carried into findings.** Peer-reviewed magnitudes (KDD 2024 GEO study) and industry analyses are labelled differently; an industry figure is never presented to a client as measured fact.
 - Static fetches (`curl`, `web_fetch`) cannot detect JS-injected JSON-LD; structured data must be validated with a rendering tool or Search Console URL inspection.
+- **Two findings are explicitly banned:** "missing `llms.txt`" (no measured visibility effect) and any claim that engagement metrics such as bounce rate affect rankings (Google has denied this for a decade).
 
 ## Best Paired Commands
 
 - `/akili-seo` for the audit phase (index coverage, structured data, render, on-page checks).
 - `/akili-validate` when a spec includes SEO acceptance criteria.
 
+## References (progressive disclosure)
+
+- `references/geo.md` — generative-engine visibility: the KDD 2024 measurement of what works, passage-level extraction, freshness, structured-data correlation, the AI-crawler agent table (training vs retrieval), and the negative evidence on `llms.txt`. Claims carry `[PRIMARY]` / `[INDUSTRY]` source tiers.
+- `references/international-seo.md` — hreflang, canonical + i18n, locale sitemaps, URL structure, cross-locale content quality.
+- `references/ai-writing-detection.md` — AI writing patterns to avoid.
+
 ## Source
 
 - `../../.claude/skills/seo-audit/SKILL.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akili-specs",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "Portable AKILI-SPECS methodology commands and skills for AI-assisted development.",
   "homepage": "https://github.com/JuankCadavid/akili-specs#readme",
   "repository": {