@stacksjs/defaults 0.75.108 → 0.75.110

package/ai/skills/stacks-marketing-ai-seo/evals/evals.json

@@ -0,0 +1,163 @@
+{
+  "skill_name": "stacks-marketing-ai-seo",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "How do I make sure our SaaS product shows up in AI search results? We're a project management tool and we keep getting left out of ChatGPT and Perplexity recommendations when people ask about project management software.",
+      "expected_output": "Should check for product-marketing.md first. Should apply the three pillars framework: Structure (make content extractable), Authority (make content citable), Presence (be where AI looks). Should run through the AI Visibility Audit checklist across platforms (Google AI Overviews, ChatGPT, Perplexity, etc.). Should check content extractability (clear definitions, structured comparisons, statistics). Should reference Princeton GEO research findings (citations improve visibility +40%, statistics +37%). Should check AI bot access in robots.txt. Should provide a prioritized action plan.",
+      "assertions": [
+        "Checks for product-marketing.md",
+        "Applies three pillars framework (Structure, Authority, Presence)",
+        "Runs AI Visibility Audit across platforms",
+        "Checks content extractability",
+        "References Princeton GEO research findings",
+        "Checks AI bot access in robots.txt",
+        "Provides prioritized action plan"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Should we block AI crawlers like GPTBot and PerplexityBot in our robots.txt? We're worried about content theft.",
+      "expected_output": "Should address the crawler-access question directly and separate controls by purpose. GPTBot and ClaudeBot are potential model-training crawlers; blocking them is a training opt-out and does not by itself block search citations. PerplexityBot, OAI-SearchBot, and Claude-SearchBot support automatic search discovery, so blocking them may reduce visibility. ChatGPT-User, Claude-User, and Perplexity-User support user-triggered retrieval and may have vendor-specific robots behavior. Google-Extended controls certain Gemini training and grounding uses and does not affect Google Search inclusion or ranking. Should provide a purpose-specific robots.txt example and recommend verifying current vendor documentation before implementation.",
+      "assertions": [
+        "Addresses the blocking tradeoff directly",
+        "Distinguishes search discovery from model-training controls",
+        "Lists specific AI bot user agents",
+        "Provides recommended robots.txt configuration",
+        "Gives nuanced recommendation based on business goals",
+        "Explains what each bot does"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "What kind of content gets cited most by AI systems? We want to create content specifically optimized for AI search.",
+      "expected_output": "Should reference the content types that get cited most, including comparisons (~33% of AI citations), definitive guides (~15%), and other high-citation content types. Should explain why these formats work (they provide the structured, extractable, authoritative information AI systems need). Should provide specific recommendations for creating AI-optimized content: clear definitions, structured data, original statistics, comparison tables, expert quotes. Should reference the Princeton GEO research on what increases citation probability.",
+      "assertions": [
+        "References specific content types with citation rates",
+        "Mentions comparisons as highest-cited format",
+        "Explains why these formats work for AI",
+        "Provides specific content creation recommendations",
+        "References Princeton GEO research",
+        "Mentions structured data, statistics, and clear definitions"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "we noticed our competitors are showing up in google AI overviews but we're not. what do we need to change?",
+      "expected_output": "Should trigger on casual phrasing. Should focus specifically on Google AI Overviews visibility. Should explain how AI Overviews selects sources (authoritative, well-structured, directly answers queries). Should run through the Structure pillar checklist: content extractability, heading hierarchy, answer-first format, structured data. Should check Authority signals: domain authority, citations, E-E-A-T. Should recommend specific content structure changes. Should suggest monitoring approach.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Focuses on Google AI Overviews specifically",
+        "Explains how AI Overviews selects sources",
+        "Checks Structure pillar (extractability, headings, answer-first)",
+        "Checks Authority signals",
+        "Recommends specific content structure changes",
+        "Suggests monitoring approach"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Can you audit our website for AI search readiness? We want to know how visible we are across ChatGPT, Perplexity, Google AI Overviews, and other AI platforms.",
+      "expected_output": "Should run the full AI Visibility Audit. Should check each platform in the landscape (Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, Copilot). Should evaluate all three pillars: Structure (content extractability, JSON-LD, clear definitions), Authority (citations, backlinks, E-E-A-T signals), Presence (AI bot access, platform-specific factors). Should provide findings organized by pillar. Should provide a prioritized action plan with specific fixes.",
+      "assertions": [
+        "Runs full AI Visibility Audit",
+        "Checks multiple AI platforms",
+        "Evaluates all three pillars (Structure, Authority, Presence)",
+        "Checks content extractability",
+        "Checks AI bot access",
+        "Provides findings organized by pillar",
+        "Provides prioritized action plan"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Our organic search traffic has dropped 30% this quarter. Can you do a full SEO audit to figure out what's going on?",
+      "expected_output": "Should recognize this is a traditional SEO audit request, not specifically an AI SEO task. Should defer to or cross-reference the seo-audit skill, which handles comprehensive traditional SEO audits including crawlability, technical foundations, on-page optimization, and content quality. May mention AI search as one factor to investigate but should make clear that seo-audit is the primary skill for this task.",
+      "assertions": [
+        "Recognizes this as a traditional SEO audit request",
+        "References or defers to seo-audit skill",
+        "Does not attempt a full traditional SEO audit using AI SEO patterns",
+        "May mention AI search as one factor to consider"
+      ],
+      "files": []
+    },
+    {
+      "id": 7,
+      "prompt": "We're a seed-stage data-quality startup (barely anyone knows us yet). Plan: publish 20 'best data quality tools' style listicles ranking ourselves #1 so ChatGPT and AI Overviews recommend us. Good idea?",
+      "expected_output": "Should apply references/citations-vs-recommendations.md rather than endorsing the plan as-is. Should explain the citation vs. recommendation distinction - self-promotional listicles from low-authority brands often earn citations while the AI answer recommends the competitors named in the guide instead (cites the study directionally: ~69% of self-promotional listicle citations - 224 of 323 - excluded the publisher from recommendations). Should present the visibility ladder (retrieved → cited → mentioned → recommended) and explain recommendation is governed by offsite consensus (reviews, forums, analysts, press). Should NOT say 'don't publish guides' - should reframe: publish a small number of genuinely useful guides for category framing, and rebalance investment toward reviews/communities/earned media. Should mention the attribution blind spot (AI-influenced visits mostly appear as branded search/direct; only a small share is visible AI traffic) and the measurement triad (prompt tracking, self-reported attribution, call recordings).",
+      "assertions": [
+        "Does not endorse 20 self-ranked listicles as a path to AI recommendations for a low-authority brand",
+        "Distinguishes citations from recommendations with the different governing criteria",
+        "References the visibility ladder (retrieved/cited/mentioned/recommended)",
+        "Warns the guides may surface competitors in AI answers (vote-for-competitors mechanism)",
+        "Recommends offsite consensus building (reviews, communities, analysts, or PR) as the recommendation lever",
+        "Does not tell the user to stop publishing buyer's guides entirely - reframes expectations toward citation and category framing",
+        "Mentions the attribution blind spot and at least two of: prompt tracking, self-reported attribution, call recordings"
+      ],
+      "files": []
+    },
+    {
+      "id": 8,
+      "prompt": "We publish YouTube tutorials for our category's biggest how-to queries but never get cited in AI answers, while a competitor's uglier videos show up in Google AI Overviews and ChatGPT constantly. The videos themselves are well produced. What are we missing?",
+      "expected_output": "Should load references/youtube-ai-citations.md and diagnose the text layer, not the footage: models don't watch the video, they read everything around it. Should check, in leverage order: transcript quality (key answers spoken as complete, liftable sentences; entities said out loud), captions (cleaned/uploaded, not messy auto-captions), question-shaped title matching the real query, chapters titled by sub-question, a keyword-rich description restating the key points as text, and a pinned comment carrying the summary. Should note engagement/thumbnail feeds YouTube ranking which feeds AI surfacing, and should not recommend re-shooting or higher production value as the fix.",
+      "assertions": [
+        "States that AI models read the text layer (transcript, captions, title, chapters, description, pinned comment) rather than watching the video",
+        "Recommends cleaning/uploading captions and speaking key answers as complete liftable statements with entities said aloud",
+        "Recommends question-shaped titles, chapters titled by sub-question, a structured description, and a pinned summary comment",
+        "Does not attribute the gap to production quality or recommend re-shooting as the primary fix"
+      ],
+      "files": []
+    },
+    {
+      "id": 9,
+      "prompt": "Our content is well-written and we have schema markup, but AI assistants never seem to use our site. Someone said our site might not be 'agent-ready.' We also put most of our AI-visibility effort into Reddit this year since that's where ChatGPT cites from. What should we do?",
+      "expected_output": "Should load references/agent-readiness.md and address both halves. (1) Agent readiness: recommend running a free scoring tool (bunx --bun is-agentic and/or Frase's Agent Readiness Checker) and walk the access/discovery/parseability triad - core content must be in the initial HTML without JavaScript execution, no bot challenge/firewall blocking intended search-discovery crawlers, purpose-specific robots.txt controls that separate discovery from model training, a clean sitemap, llms.txt (+llms-full.txt as bonus), structured data, and a Markdown representation via content negotiation (Accept: text/markdown at the same canonical URL) or a Link header. May mention WebMCP as the emerging agent-actionable layer, labeled emerging. (2) Reddit concentration: flag citation-source volatility - ChatGPT's Aug 2026 retrieval changes nearly wiped Reddit as a source (practitioner-reported), so single-surface concentration is fragile; recommend the portfolio approach across third-party surfaces plus owned-site fundamentals (which dominate Gemini citations), and verifying any citation-share stat against their own monitoring before betting budget.",
+      "assertions": [
+        "Recommends running an agent-readiness scoring tool (is-agentic or Frase checker) and structures the audit as access / discovery / parseability",
+        "Identifies JavaScript-only content rendering and bot/firewall blocking as first-order access failures",
+        "Covers the discovery/parseability file stack: robots.txt AI stance, sitemap, llms.txt or llms-full.txt, structured data, and a Markdown representation (content negotiation or Link header)",
+        "Flags the Reddit-only strategy as fragile, citing citation-source volatility (Aug 2026 ChatGPT retrieval change, labeled practitioner-reported) and recommends a portfolio plus owned-site fundamentals",
+        "Does not present citation-share statistics as stable facts; recommends verifying against the user's own citation monitoring"
+      ],
+      "files": []
+    },
+    {
+      "id": 10,
+      "prompt": "We're a B2B SaaS planning our 2026 content roadmap. The plan is 40 comparison pages ('us vs competitor') and 20 'best tools' listicles, mainly to win ChatGPT citations. Also, how do I know if it's working - I checked ChatGPT once last week and we weren't mentioned.",
+      "expected_output": "Should load references/format-volatility.md and push back on the rationale with the ChatGPT 5.6 shift (Aug 2026, Peec AI data): listicle citations fell ~50% and comparison-page citations ~32% post-5.6, with fan-out queries dropping 'best/vs/top/comparison' modifiers in favor of site: and 'official' searches - so 'win ChatGPT citations' no longer justifies scaled comparison/listicle production. Should NOT say comparison pages are dead: they still convert humans and still earn citations on Google AI Overviews, Gemini, and Perplexity - format strategy is per-platform. Should steer investment toward owned 'official' pages (product, docs, pricing, original research), which are rising as the citable class and dominate Gemini (~60% business sites). May suggest extracting ChatGPT's real fan-out queries via the DevTools method for coverage planning (while warning against mass-generating a page per query - scaled content abuse). On measurement: one ChatGPT check is an anecdote - AI answers are non-deterministic; run each query 3-5 times per platform, track mention rate with sample size (e.g. 'cited 3/5'), and compare rates over time. Numbers should be treated as dated snapshots to verify against own monitoring."
+    },
+    {
+      "id": 11,
+      "prompt": "We've been known as a mid-market HR platform for ten years. Next quarter we're repositioning as enterprise and rewriting the whole site at once. How do we make sure ChatGPT and Google's AI start recommending us for enterprise HR software?",
+      "expected_output": "Should warn that LLM brand associations move slowly: enterprise prompts are already tied to incumbents, and rewriting the whole site at once can lose mid-market answers before enterprise ones arrive. Should recommend recording a baseline for both old- and new-segment prompts, setting expectations for a dip, moving off-site signals first (G2/Capterra/Gartner profiles, reviews, analyst and press coverage) so they match the new About page, and staging the on-site rewrite. Should suggest extracting real fan-out queries to see which third-party domains (e.g. site: searches on Gartner/G2) matter for the category. Should label these as practitioner experience rather than proven data, and not recommend invented awards or self-owned review sites.",
+      "assertions": [
+        "Flags a possible visibility dip as practitioner experience, not a certainty",
+        "Recommends baselining old- and new-segment prompts",
+        "Prioritizes aligning third-party profiles with the new positioning",
+        "Suggests staging the on-site rewrite instead of switching all at once",
+        "Uses fan-out analysis to find which third-party sources matter",
+        "Doesn't recommend fake awards or self-owned review sites"
+      ],
+      "files": []
+    },
+    {
+      "id": 12,
+      "prompt": "I keep hearing LinkedIn articles get cited by ChatGPT. Should I republish all our blog posts as LinkedIn articles to get more AI citations?",
+      "expected_output": "Should not recommend blanket republishing. Should explain that which LinkedIn surface gets cited depends on the engine and shifted in 2026: ChatGPT now cites feed posts far more than Pulse articles, while Perplexity, Copilot, and Google's AI features still cite articles and company pages, and Gemini barely cites LinkedIn. Should warn that LinkedIn sets its own canonical, so full republishing competes with the blog; recommend publishing on the site first and posting adapted versions or summaries. Should suggest checking articles for crawler noindex, note that engagement and follower count barely predict citation while original, specific, technical content does, and recommend tracking citations per engine. Should label figures as dated vendor or platform data.",
+      "assertions": [
+        "Does not recommend republishing everything as-is",
+        "Explains the engine split (ChatGPT favors posts; others still cite articles; Gemini barely cites LinkedIn)",
+        "Warns about canonical/duplication and recommends site-first with adapted versions",
+        "Mentions checking for crawler noindex",
+        "Notes engagement and followers barely predict citation",
+        "Labels figures as dated and vendor/platform-reported"
+      ],
+      "files": []
+    }
+  ]
+}

package/ai/skills/stacks-marketing-ai-seo/references/agent-readiness.md

@@ -0,0 +1,66 @@
+# Agent Readiness - Can an Agent Reach, Navigate, and Parse Your Site
+
+AI visibility work splits into two layers: what your content says (the rest of this skill) and whether an agent can *get to it at all*. This reference covers the second layer - the access/discovery/parseability audit - plus the emerging shift from agent-*readable* to agent-*actionable* sites.
+
+Two free scoring tools shipped in August 2026 and turned this into a measurable discipline:
+
+| Tool | Run it | Method |
+|---|---|---|
+| **Is Agentic** (Vercel + Ora) | `bunx --bun is-agentic yourdomain.com` or [is-agentic.com](https://is-agentic.com) | 100+ checks; Essential checks carry most of the score; Recommended checks activate only when evidence shows you have that surface (API, MCP server, commerce); not-applicable checks are excluded, not failed; includes an observed agent journey showing where a real agent hit friction |
+| **Frase Agent Readiness Checker** | [frase.io/tools/agent-readiness](https://www.frase.io/tools/agent-readiness) | Access / Discovery / Parseability triad; 80+ = agents can reliably use the site, 60-79 = solid with gaps, <60 = real access problems |
+
+Run one before and after any agent-readiness work - the score is a shareable artifact and the failed checks are your worklist. (Both are vendor tools with a product behind them; the *checks* are the value, not the pitch.)
+
+## The three questions
+
+### 1. Access - can an agent get to the page and see real content
+
+- **Core content in the initial HTML response.** Most agents never execute JavaScript. If the content only exists after client-side rendering, it doesn't exist. This is the #1 essential check in both tools.
+- **No bot challenge or firewall block** on the intended discovery path. Blocking `OAI-SearchBot`, `PerplexityBot`, or `Claude-SearchBot` may reduce search visibility. Blocking model-development crawlers such as `GPTBot` or `ClaudeBot` can be an intentional training opt-out and is not, by itself, a visibility failure. Audit what your CDN/WAF actually does to each user agent - many sites block them by default without anyone deciding to.
+- **Correct HTTP behavior**: real status codes (no soft-404s), stable canonical URLs, recoverable errors.
+
+### 2. Discovery - do your files tell agents what's here
+
+- **robots.txt with an explicit AI-crawler stance** - name the relevant user agents and state a purpose-specific policy, rather than leaving it to be assumed (see the bot-access guidance in SKILL.md).
+- **A sitemap that loads and parses cleanly.**
+- **llms.txt at the domain root** (see Machine-Readable Files in SKILL.md).
+- **`llms-full.txt`** - the newer companion: your entire site content in one file, so an agent gets everything in a single request instead of crawling. Emerging, cheap to generate alongside llms.txt, and scored as bonus signal by both tools.
+- **robots.txt content-usage statements** - an emerging convention for declaring what AI may do with your content (train / cite / summarize), so the answer comes from you instead of being assumed.
+
+### 3. Parseability - once there, can the agent tell what the page is
+
+- **Valid, substantive structured data** (JSON-LD - see the `stacks-marketing-schema` skill).
+- **A Markdown representation of the page.** This is the newest technique in the stack, two implementations:
+  - **Content negotiation**: serve compact Markdown at the *same canonical URL* when the request asks for `Accept: text/markdown`, with a `Vary` header keeping the HTML and Markdown cache entries separate. (This is how Is Agentic serves its own reports - agents get Markdown, browsers get HTML, one URL.)
+  - **Link header**: an HTTP `Link` header on the HTML page pointing to a parallel Markdown version - discoverable without guessing URLs.
+- Clear document structure - one H1, headings that answer sub-questions, extractable answer blocks (the content-patterns reference).
+
+## Emerging: agent-actionable, not just agent-readable
+
+Reading is becoming table stakes. The next race is whether an agent can *act* on your site - fill the form, book the meeting, start the trial. **WebMCP** is the emerging standard here: a page declares its forms and CTAs as callable tools with input schemas, so an agent doesn't have to reverse-engineer your UI. Early days (label: emerging, not yet a ranking/citation signal), but the direction is clear - if agents are becoming buyers, the site that exposes "start trial" as a structured action wins the agent-mediated conversion that a pretty button loses.
+
+Practical today: make sure your highest-intent actions (signup, pricing, demo booking, contact) work without JavaScript-only flows, have labeled semantic form fields, and return machine-readable confirmation.
+
+**Ways to add WebMCP** (all early; confirm browser and assistant support before promising anything):
+- **Implement it yourself.** Follow the WebMCP draft to declare each action as a tool with an input schema, wired to the form or API the page already uses. Keep the tool list short (the 2-4 highest-intent actions) and reuse existing validation, spam protection, and permissions rather than building a parallel path.
+- **Use your platform's support, if it has any.** Some site platforms and agent workflows add WebMCP for you. Ploy ◆, for example, has a Ploybook that inspects the site, defines tool contracts, implements them against existing form logic, and validates them. It's a guided workflow, not a hosted MCP server. ◆ marks a [Verified Partner](https://github.com/coreyhaines31/marketingskills/blob/1efedbc5148b54b2f0f6c6c9fe0be62e151c7fff/tools/REGISTRY.md#verified-partners) of this repository (disclosure, not endorsement); name an alternative alongside it when you mention it.
+- **Have a coding agent do it** in the site's repo, with the same scoping: a few actions, existing logic, a test for each.
+
+Whichever path, test that each tool rejects bad input, that submissions land where the normal form's do (CRM, inbox, conversion tracking), and that nothing bypasses consent or rate limits.
+
+## Citation-source volatility (why you diversify)
+
+Third-party citation mixes are **not stable** - they shift overnight with model and retrieval updates, and August 2026 provided the case study: **ChatGPT's query fan-out changes nearly wiped Reddit as a citation source** within days (practitioner-reported by multiple AEO teams; one had been earning 24-hour citations from Reddit at 1M+ impressions/month before the change). Meanwhile the same practitioners report **business-owned websites dominate Gemini citations (~60%)**.
+
+LinkedIn moved in the same update: ChatGPT's LinkedIn citations fell ~36% in mid-August 2026, and its citations of Pulse articles fell ~86% from May to Oct while citations of feed posts rose. Perplexity and Copilot moved the other way. See [linkedin-ai-citations.md](linkedin-ai-citations.md).
+
+What this means for strategy:
+
+- **Never concentrate AI-visibility work in one third-party surface.** The Presence pillar's list (Wikipedia, Reddit, YouTube, podcasts, review sites, Quora) is a portfolio, not a menu to pick one from. A surface that's 2% of citations today can be 0% after one retrieval update - or vice versa.
+- **Owned-site fundamentals hedge the volatility.** Platform deals and retrieval changes reshuffle third-party sources; your own agent-readable site is the one surface no platform can drop you from - and on Gemini it's already the dominant citation class.
+- **Treat any citation-share statistic as dated.** The "Reddit = 1.8% of ChatGPT citations" class of stats (including the ones in this skill) are snapshots - check the date, and verify against your own citation monitoring (the DIY monitoring loop in SKILL.md) before betting budget on them.
+- **Speed is real**: fresh content on retrieved surfaces can be cited within ~24 hours. AI search rewards freshness faster than classic SEO ever did.
+
+---
+
+*Agent-readiness check taxonomy distilled from Vercel/Ora's Is Agentic (is-agentic.com) and Frase's Agent Readiness Checker (both August 2026, credited); citation-volatility events practitioner-reported (Ashni of Hype Partners (@ashnichrist) and others, August 2026) - labeled accordingly, verify against your own monitoring.*

package/ai/skills/stacks-marketing-ai-seo/references/citations-vs-recommendations.md

@@ -0,0 +1,89 @@
+# Citations vs. Recommendations: The AI Visibility Ladder
+
+Being cited by an AI engine and being recommended by it are **two different outcomes governed by two different systems**. A citation means your page was useful enough to pull information from. A recommendation means the model put your brand on the buyer's shortlist. Optimizing for the first does not automatically earn the second - and for smaller brands, conflating them leads to content strategies that can actively help competitors.
+
+Source note: the analysis and data in this reference draw on Lily Ray's (Amsive) 2026 study of B2B "best [category] software" queries, behavioral studies by Scrunch and SimilarWeb, and commentary by John-Henry Scherck (Growth Plays).
+
+---
+
+## The Visibility Ladder
+
+AI visibility is a ladder, not a binary. Each rung has different selection criteria and different measurement:
+
+| Rung | What it means | What governs it | How to see it |
+|---|---|---|---|
+| **1. Retrieved** | The model read your content while building its answer, without citing it | Crawlability, parseable structure, query relevance | Mostly invisible; bot logs hint at it |
+| **2. Cited** | Your page appears as a source in the answer | Content usefulness: structure, statistics, clarity, freshness | Prompt-tracking tools, AI Overview source lists |
+| **3. Mentioned** | Your brand is named in the answer text | Entity recognition + how the web talks about you | Prompt-tracking tools |
+| **4. Recommended** | Your product is on the shortlist the buyer actually considers | **Aggregate web consensus** - reviews, forums, analysts, press, video - largely independent of your own content | Prompt tracking + the framing around the mention |
+
+Rungs 1-3 are legitimate signals your content is working, and most prompt-tracking tools report them. But rung 4 is where buying behavior changes, and it's earned differently: **citation is about whether your content is useful to consult; recommendation is mostly a reflection of what the broader web says about you** - whether you published a guide on the topic or not.
+
+There is also a shadow rung: **recommended against**. On detailed, requirements-heavy prompts, models increasingly name products a buyer should *avoid* for their use case, with sources. The downside of weak third-party consensus is no longer just absence from the shortlist - it can be an explicit rule-out. This makes monitoring the *framing* around your mentions (favorable / neutral / hedged / negative), not just counting them, part of the job.
+
+**Repairing a weakness models repeat.** Address it in public, with specifics, from a real person. One practitioner's client was "slaughtered" on implementation time; over 1.5-2 years, founder posts about the process, guides on real timelines, and a concrete "4-8 weeks" on the implementation page shifted how models described it (anecdote, Harpreet Singh on Edward Sturm's podcast, Sep 2026). More in [positioning-and-consensus.md](positioning-and-consensus.md).
+
+---
+
+## The Self-Promotional Listicle Risk
+
+The common tactic - publish a "best [category] software" guide, rank yourself #1, and let it shape both organic search and AI answers - now has a stage-dependent payoff.
+
+**The data:** Lily Ray (Amsive) analyzed 100 B2B "best [category] software" queries across three dates in spring 2026. Across the dataset, self-promotional listicles earned 323 citations in AI Overviews - and in 224 of them (**69% of the citations**), the answer left the publishing brand out of the recommendations, pointing buyers to competitors instead.
+
+**The mechanism:** the model treats your guide as a source about the *category*. It happily extracts the competitor names, comparisons, and evaluation criteria you compiled - then makes its recommendation from web-wide consensus, where the established players dominate. For an emerging brand, a self-promotional buyer's guide can function as **a vote for your competitors**: you did the research that helps the model describe them.
+
+**The split by stage:**
+
+- **Established category leaders** get both outcomes. Their guides earn citations *and* their brands get recommended - because analysts, review sites, and forum discussions already validate them. For leaders, a definitive buyer's guide is highly advantageous: it shapes how the whole category (competitors included) gets described.
+- **Emerging brands** may win the citation and even shape the category's framing, but miss the recommendation. That's not a wasted outcome - influencing how an LLM defines the category and its evaluation criteria is real positioning work - but it is not the shortlist placement the tactic promises.
+
+**What this changes (and doesn't):** genuinely useful buyer's guides still belong in a B2B content strategy at any stage. What changes is the expectation and the investment split. If you're not yet the consensus pick, weight effort toward the offsite signals that actually govern recommendations (below) rather than publishing a plethora of self-ranked listicles.
+
+**A third option between ranking yourself #1 and not writing the guide:** name the category leader first, say honestly what it does well, then show the specific cases where your product goes further (practitioner pattern, Sep 2026). It reads as a fair source, which is what models are now starting to filter for.
+
+---
+
+## What Earns Recommendations
+
+Recommendation is a consensus signal. The inputs the models weigh live mostly off your site:
+
+| Channel | Why it moves recommendations | Related skill |
+|---|---|---|
+| **Review platforms** (G2, Capterra, TrustRadius, app stores) | Third-party validation models treat as evidence of legitimacy | customer-research (review generation loops) |
+| **Analyst coverage** (Gartner, Forrester, industry reports) | High-authority category framing; models echo analyst shortlists | public-relations |
+| **Communities and forums** (Reddit, HN, Slack/Discord, niche forums) | Unprompted practitioner discussion is heavily retrieved and hard to fake | community-marketing |
+| **Earned media and PR** | Independent sources repeating your positioning beyond your own site | public-relations |
+| **Video and podcasts** | Increasingly retrieved; transcripts carry brand + category associations | video, social |
+
+The test to apply before investing in another self-ranked guide: *if a model ignored everything on our domain, would the rest of the web still put us on the shortlist?* If not, that gap is the priority. AEO discourse often stops at "are we in the answer?" - the better question is "are we credible enough to be recommended?"
+
+The encouraging flip side: earning an AI recommendation is harder to game than a top search ranking ever was. The durable strategy is the same at every stage - be the best fit for a clear set of buyers, and give those buyers reasons to talk about you in public, where the models can retrieve it.
+
+---
+
+## What a Recommendation Is Worth
+
+Two behavioral studies quantified the gap between rungs:
+
+- **Scrunch** (opt-in panel linking AI conversations to subsequent web behavior, compared against each user's own baseline - observational, not a controlled experiment): a genuine recommendation ("a great option is X") was associated with people searching for, visiting, and evaluating a brand **about twice as often** as a passing mention. For users with no recent observed engagement with the brand, a recommendation was followed within a week by **+182% branded searches, +117% site visits, and +185% product views**.
+- **SimilarWeb** (thousands of real user journeys, seven days post-answer): when ChatGPT recommended a brand, it received **roughly 2.5× more new visitors** the following week than the competitors left off the list.
+
+**The attribution blind spot:** in the SimilarWeb data, only about **9%** of those post-recommendation visits arrived as visible AI referral traffic; the largest share arrived via branded search, with direct and other channels making up the rest - indistinguishable from ordinary organic visitors. AI recommendations are already sending real, engaged buyers, but standard attribution underreports the AI touch.
+
+**Measurement triad** (no single signal is complete; together they give a reliable read):
+
+1. **AI prompt tracking** - whether and how you're mentioned/recommended in LLM answers, even when no click ever lands (tools in SKILL.md's Monitoring section). Track the framing around mentions - recommended, neutral, hedged, or recommended-against - not just the count.
+2. **Self-reported attribution** - a "how did you hear about us?" field catches buyers whose journey started in an AI chat but arrived via branded search or direct. Add an AI option with a follow-up, "What did you type?", so buyers hand you real prompts to track. ChatGPT referral UTMs undercount, and AI Overview revenue can't be separated from organic in analytics, so this field is often the clearest signal you have.
+3. **Sales call recordings** - buyers' own language often reveals an AI conversation shaped the shortlist long before any form fill.
+
+Also watch **branded search volume** as a proxy: sustained lifts without a matching campaign are increasingly AI-influence showing up under another name.
+
+---
+
+## Applying This
+
+- **Auditing an established brand:** buyer's guides and comparison content are high-leverage - publish the definitive version and shape the category's evaluation criteria.
+- **Auditing an emerging brand:** publish the genuinely useful guides your ICP needs, but set expectations (citation and framing, not near-term recommendation) and rebalance investment toward reviews, communities, analysts, and earned media.
+- **Reporting:** report the ladder, not a single "AI visibility" number - retrieved/cited/mentioned/recommended plus mention framing. A rising citation count with a flat recommendation rate is a specific, diagnosable gap: the web doesn't yet corroborate your content.
+- **Risk check:** for requirements-heavy queries in your category, check whether models recommend *against* you, and trace the sources they cite when they do.

package/ai/skills/stacks-marketing-ai-seo/references/content-patterns.md

@@ -0,0 +1,287 @@
+# AEO and GEO Content Patterns
+
+Reusable content block patterns optimized for answer engines and AI citation.
+
+---
+
+## Contents
+- Answer Engine Optimization (AEO) Patterns (Definition Block, Step-by-Step Block, Comparison Table Block, Pros and Cons Block, FAQ Block, Listicle Block)
+- Generative Engine Optimization (GEO) Patterns (Statistic Citation Block, Expert Quote Block, Authoritative Claim Block, Self-Contained Answer Block, Evidence Sandwich Block)
+- Domain-Specific GEO Tactics (Technology Content, Health/Medical Content, Financial Content, Legal Content, Business/Marketing Content)
+- Voice Search Optimization (Question Formats for Voice, Voice-Optimized Answer Structure)
+
+## Answer Engine Optimization (AEO) Patterns
+
+These patterns help content appear in featured snippets, AI Overviews, voice search results, and answer boxes.
+
+### Definition Block
+
+Use for "What is [X]?" queries.
+
+```markdown
+## What is [Term]?
+
+[Term] is [concise 1-sentence definition]. [Expanded 1-2 sentence explanation with key characteristics]. [Brief context on why it matters or how it's used].
+```
+
+**Example:**
+```markdown
+## What is Answer Engine Optimization?
+
+Answer Engine Optimization (AEO) is the practice of structuring content so AI-powered systems can easily extract and present it as direct answers to user queries. Unlike traditional SEO that focuses on ranking in search results, AEO optimizes for featured snippets, AI Overviews, and voice assistant responses. This approach has become essential as over 60% of Google searches now end without a click.
+```
+
+### Step-by-Step Block
+
+Use for "How to [X]" queries. Optimal for list snippets.
+
+```markdown
+## How to [Action/Goal]
+
+[1-sentence overview of the process]
+
+1. **[Step Name]**: [Clear action description in 1-2 sentences]
+2. **[Step Name]**: [Clear action description in 1-2 sentences]
+3. **[Step Name]**: [Clear action description in 1-2 sentences]
+4. **[Step Name]**: [Clear action description in 1-2 sentences]
+5. **[Step Name]**: [Clear action description in 1-2 sentences]
+
+[Optional: Brief note on expected outcome or time estimate]
+```
+
+**Example:**
+```markdown
+## How to Optimize Content for Featured Snippets
+
+Earning featured snippets requires strategic formatting and direct answers to search queries.
+
+1. **Identify snippet opportunities**: Use tools like Semrush or Ahrefs to find keywords where competitors have snippets you could capture.
+2. **Match the snippet format**: Analyze whether the current snippet is a paragraph, list, or table, and format your content accordingly.
+3. **Answer the question directly**: Provide a clear, concise answer (40-60 words for paragraph snippets) immediately after the question heading.
+4. **Add supporting context**: Expand on your answer with examples, data, and expert insights in the following paragraphs.
+5. **Use proper heading structure**: Place your target question as an H2 or H3, with the answer immediately following.
+
+Most featured snippets appear within 2-4 weeks of publishing well-optimized content.
+```
+
+### Comparison Table Block
+
+Use for "[X] vs [Y]" queries. Optimal for table snippets.
+
+```markdown
+## [Option A] vs [Option B]: [Brief Descriptor]
+
+| Feature | [Option A] | [Option B] |
+|---------|------------|------------|
+| [Criteria 1] | [Value/Description] | [Value/Description] |
+| [Criteria 2] | [Value/Description] | [Value/Description] |
+| [Criteria 3] | [Value/Description] | [Value/Description] |
+| [Criteria 4] | [Value/Description] | [Value/Description] |
+| Best For | [Use case] | [Use case] |
+
+**Bottom line**: [1-2 sentence recommendation based on different needs]
+```
+
+### Pros and Cons Block
+
+Use for evaluation queries: "Is [X] worth it?", "Should I [X]?"
+
+```markdown
+## Advantages and Disadvantages of [Topic]
+
+[1-sentence overview of the evaluation context]
+
+### Pros
+
+- **[Benefit category]**: [Specific explanation]
+- **[Benefit category]**: [Specific explanation]
+- **[Benefit category]**: [Specific explanation]
+
+### Cons
+
+- **[Drawback category]**: [Specific explanation]
+- **[Drawback category]**: [Specific explanation]
+- **[Drawback category]**: [Specific explanation]
+
+**Verdict**: [1-2 sentence balanced conclusion with recommendation]
+```
+
+### FAQ Block
+
+Use for topic pages with multiple common questions. Essential for FAQ schema.
+
+```markdown
+## Frequently Asked Questions
+
+### [Question phrased exactly as users search]?
+
+[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
+
+### [Question phrased exactly as users search]?
+
+[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
+
+### [Question phrased exactly as users search]?
+
+[Direct answer in first sentence]. [Supporting context in 2-3 additional sentences].
+```
+
+**Tips for FAQ questions:**
+- Use natural question phrasing ("How do I..." not "How does one...")
+- Include question words: what, how, why, when, where, who, which
+- Match "People Also Ask" queries from search results
+- Keep answers between 50-100 words
+
+### Listicle Block
+
+Use for "Best [X]", "Top [X]", "[Number] ways to [X]" queries.
+
+**Caveat for self-promotional listicles:** ranking yourself #1 in your own "best [category]" guide gets the page *cited* far more reliably than it gets your brand *recommended* - for emerging brands, AI answers often harvest the competitor names from the guide and recommend them instead. See [citations-vs-recommendations.md](citations-vs-recommendations.md) before building these at scale.
+
+```markdown
+## [Number] Best [Items] for [Goal/Purpose]
+
+[1-2 sentence intro establishing context and selection criteria]
+
+### 1. [Item Name]
+
+[Why it's included in 2-3 sentences with specific benefits]
+
+### 2. [Item Name]
+
+[Why it's included in 2-3 sentences with specific benefits]
+
+### 3. [Item Name]
+
+[Why it's included in 2-3 sentences with specific benefits]
+```
+
+---
+
+## Generative Engine Optimization (GEO) Patterns
+
+These patterns optimize content for citation by AI assistants like ChatGPT, Claude, Perplexity, and Gemini.
+
+### Statistic Citation Block
+
+Statistics increase AI citation rates by 15-30%. Always include sources.
+
+```markdown
+[Claim statement]. According to [Source/Organization], [specific statistic with number and timeframe]. [Context for why this matters].
+```
+
+**Example:**
+```markdown
+Mobile optimization is no longer optional for SEO success. According to Google's 2024 Core Web Vitals report, 70% of web traffic now comes from mobile devices, and pages failing mobile usability standards see 24% higher bounce rates. This makes mobile-first indexing a critical ranking factor.
+```
+
+### Expert Quote Block
+
+Named expert attribution adds credibility and increases citation likelihood.
+
+```markdown
+"[Direct quote from expert]," says [Expert Name], [Title/Role] at [Organization]. [1 sentence of context or interpretation].
+```
+
+**Example:**
+```markdown
+"The shift from keyword-driven search to intent-driven discovery represents the most significant change in SEO since mobile-first indexing," says Rand Fishkin, Co-founder of SparkToro. This perspective highlights why content strategies must evolve beyond traditional keyword optimization.
+```
+
+### Authoritative Claim Block
+
+Structure claims for easy AI extraction with clear attribution.
+
+```markdown
+[Topic] [verb: is/has/requires/involves] [clear, specific claim]. [Source] [confirms/reports/found] that [supporting evidence]. This [explains/means/suggests] [implication or action].
+```
+
+**Example:**
+```markdown
+E-E-A-T is the cornerstone of Google's content quality evaluation. Google's Search Quality Rater Guidelines confirm that trust is the most critical factor, stating that "untrustworthy pages have low E-E-A-T no matter how experienced, expert, or authoritative they may seem." This means content creators must prioritize transparency and accuracy above all other optimization tactics.
+```
+
+### Self-Contained Answer Block
+
+Create quotable, standalone statements that AI can extract directly.
+
+```markdown
+**[Topic/Question]**: [Complete, self-contained answer that makes sense without additional context. Include specific details, numbers, or examples in 2-3 sentences.]
+```
+
+**Example:**
+```markdown
+**Ideal blog post length for SEO**: The optimal length for SEO blog posts is 1,500-2,500 words for competitive topics. This range allows comprehensive topic coverage while maintaining reader engagement. HubSpot research shows long-form content earns 77% more backlinks than short articles, directly impacting search rankings.
+```
+
+### Evidence Sandwich Block
+
+Structure claims with evidence for maximum credibility.
+
+```markdown
+[Opening claim statement].
+
+Evidence supporting this includes:
+- [Data point 1 with source]
+- [Data point 2 with source]
+- [Data point 3 with source]
+
+[Concluding statement connecting evidence to actionable insight].
+```
+
+---
+
+## Domain-Specific GEO Tactics
+
+Different content domains benefit from different authority signals.
+
+### Technology Content
+- Emphasize technical precision and correct terminology
+- Include version numbers and dates for software/tools
+- Reference official documentation
+- Add code examples where relevant
+
+### Health/Medical Content
+- Cite peer-reviewed studies with publication details
+- Include expert credentials (MD, RN, etc.)
+- Note study limitations and context
+- Add "last reviewed" dates
+
+### Financial Content
+- Reference regulatory bodies (SEC, FTC, etc.)
+- Include specific numbers with timeframes
+- Note that information is educational, not advice
+- Cite recognized financial institutions
+
+### Legal Content
+- Cite specific laws, statutes, and regulations
+- Reference jurisdiction clearly
+- Include professional disclaimers
+- Note when professional consultation is advised
+
+### Business/Marketing Content
+- Include case studies with measurable results
+- Reference industry research and reports
+- Add percentage changes and timeframes
+- Quote recognized thought leaders
+
+---
+
+## Voice Search Optimization
+
+Voice queries are conversational and question-based. Optimize for these patterns:
+
+### Question Formats for Voice
+- "What is..."
+- "How do I..."
+- "Where can I find..."
+- "Why does..."
+- "When should I..."
+- "Who is..."
+
+### Voice-Optimized Answer Structure
+- Lead with direct answer (under 30 words ideal)
+- Use natural, conversational language
+- Avoid jargon unless targeting expert audience
+- Include local context where relevant
+- Structure for single spoken response