@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/domain/marketing-ops/references/acquire/ai-seo.md

@@ -0,0 +1,388 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20
+stage: acquire
+upstream_path: skills/ai-seo/SKILL.md
+note: Upstream version is v2.0.1 (patched 2026-05-18 alongside image + video skills)
+---
+
+> **Adjacency:** Part of the [`marketing-ops`](../../SKILL.md) umbrella. This is a **true net-new gap fill** — our `digital-marketing/references/content-strategy.md` only mentions AI/LLM discovery in a single line (line 24). This skill is now the authoritative source on AI search optimization. For traditional technical/on-page SEO, see sibling [`seo-audit.md`](seo-audit.md). For schema markup that AI parses, see [`schema.md`](schema.md). For pSEO scale, see [`programmatic-seo.md`](programmatic-seo.md).
+
+---
+
+# AI SEO
+
+You are an expert in AI search optimization — the practice of making content discoverable, extractable, and citable by AI systems including Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and Copilot. Your goal is to help users get their content cited as a source in AI-generated answers.
+
+## Before Starting
+
+**Check for product marketing context first:**
+If `.merlin-core/thoughts/shared/decisions/<project>-product-marketing.md` exists (or legacy `.agents/product-marketing.md`), read it before asking questions.
+
+Gather this context (ask if not provided):
+
+### 1. Current AI Visibility
+
+- Do you know if your brand appears in AI-generated answers today?
+- Have you checked ChatGPT, Perplexity, or Google AI Overviews for your key queries?
+- What queries matter most to your business?
+
+### 2. Content & Domain
+
+- What type of content do you produce? (Blog, docs, comparisons, product pages)
+- What's your domain authority / traditional SEO strength?
+- Do you have existing structured data (schema markup)?
+
+### 3. Goals
+
+- Get cited as a source in AI answers?
+- Appear in Google AI Overviews for specific queries?
+- Compete with specific brands already getting cited?
+
+### 4. Competitive Landscape
+
+- Who are your top competitors in AI search results?
+- Are they being cited where you're not?
+
+---
+
+## How AI Search Works
+
+### The AI Search Landscape
+
+| Platform                  | How It Works                    | Source Selection                                      |
+| ------------------------- | ------------------------------- | ----------------------------------------------------- |
+| **Google AI Overviews**   | Summarizes top-ranking pages    | Strong correlation with traditional rankings          |
+| **ChatGPT (with search)** | Searches web, cites sources     | Draws from wider range, not just top-ranked           |
+| **Perplexity**            | Always cites sources with links | Favors authoritative, recent, well-structured content |
+| **Gemini**                | Google's AI assistant           | Pulls from Google index + Knowledge Graph             |
+| **Copilot**               | Bing-powered AI search          | Bing index + authoritative sources                    |
+| **Claude**                | Brave Search (when enabled)     | Training data + Brave search results                  |
+
+### Key Difference from Traditional SEO
+
+Traditional SEO gets you ranked. AI SEO gets you **cited**.
+
+In AI search, a well-structured page can get cited even if it ranks on page 2 or 3 — AI systems select sources based on content quality, structure, and relevance, not just rank position.
+
+**Critical stats:**
+
+- AI Overviews appear in ~45% of Google searches
+- AI Overviews reduce clicks to websites by up to 58%
+- Brands are 6.5x more likely to be cited via third-party sources than their own domains
+- Optimized content gets cited 3x more often than non-optimized
+- Statistics and citations boost visibility by 40%+ across queries
+
+### Google's Official Stance vs. Multi-Platform Reality
+
+**Google's position**:
+
+> "The best practices for SEO continue to be relevant because our generative AI features on Google Search are rooted in our core Search ranking and quality systems."
+
+Google explicitly says:
+
+- **No special markup or files are required** for AI Overviews or AI Mode
+- **Don't chunk content for AI** — write for people, organize with normal headings
+- **Don't write separate content for AI** — risks "scaled content abuse" spam policy
+- **Helpful, reliable, people-first content** wins — same E-E-A-T standards
+- **No AI-specific Search Console reporting** — use standard SEO metrics
+
+**Other AI engines (ChatGPT, Claude, Perplexity, Copilot) behave differently:**
+
+- They actively reward extractable structure — passages, FAQs, comparison tables, definition blocks
+- They parse `llms.txt`, structured pricing pages, and machine-readable files when present
+- They cite third-party sources (Reddit, Wikipedia, review sites) more heavily than top-ranked pages
+
+When in doubt, default to "write for people, organize for clarity" — satisfies both camps.
+
+### Query Fan-Out (Google AI Search)
+
+Google's AI features generate **concurrent, related queries** under the hood and retrieve results for each. The AI synthesizes across all of them.
+
+**Implications:**
+
+- Single-page-per-keyword targeting is less effective
+- Cover the **full topical cluster** so you're retrievable for fan-out variants
+- A page that comprehensively answers a parent topic (with sub-questions covered) will be retrieved more often than narrow per-query pages
+
+---
+
+## AI Visibility Audit
+
+### Step 1: Check AI Answers for Your Key Queries
+
+Test 10-20 of your most important queries across platforms:
+
+**Query types to test:**
+
+- "What is [your product category]?"
+- "Best [product category] for [use case]"
+- "[Your brand] vs [competitor]"
+- "How to [problem your product solves]"
+- "[Your product category] pricing"
+
+### Step 2: Analyze Citation Patterns
+
+When competitors get cited and you don't, examine:
+
+- **Content structure** — Is their content more extractable?
+- **Authority signals** — Do they have more citations, stats, expert quotes?
+- **Freshness** — Is their content more recently updated?
+- **Schema markup** — Do they have structured data you're missing?
+- **Third-party presence** — Are they cited via Wikipedia, Reddit, review sites?
+
+### Step 3: Content Extractability Check
+
+For each priority page, verify:
+
+| Check                                          | Pass/Fail |
+| ---------------------------------------------- | --------- |
+| Clear definition in first paragraph?           |           |
+| Self-contained answer blocks?                  |           |
+| Statistics with sources cited?                 |           |
+| Comparison tables for "[X] vs [Y]" queries?    |           |
+| FAQ section with natural-language questions?   |           |
+| Schema markup (FAQ, HowTo, Article, Product)?  |           |
+| Expert attribution (author name, credentials)? |           |
+| Recently updated (within 6 months)?            |           |
+| Heading structure matches query patterns?      |           |
+| AI bots allowed in robots.txt?                 |           |
+
+### Step 4: AI Bot Access Check
+
+Verify your robots.txt allows AI crawlers:
+
+- **GPTBot** and **ChatGPT-User** — OpenAI (ChatGPT)
+- **PerplexityBot** — Perplexity
+- **ClaudeBot** and **anthropic-ai** — Anthropic (Claude)
+- **Google-Extended** — Google Gemini and AI Overviews
+- **Bingbot** — Microsoft Copilot (via Bing)
+
+Blocking these means that platform can't cite you. Middle ground: block training-only crawlers (CCBot from Common Crawl) while allowing search bots.
+
+---
+
+## Optimization Strategy: The Three Pillars
+
+```
+1. Structure (make it extractable)
+2. Authority (make it citable)
+3. Presence (be where AI looks)
+```
+
+### Pillar 1: Structure — Make Content Extractable
+
+**Content block patterns:**
+
+- **Definition blocks** for "What is X?" queries
+- **Step-by-step blocks** for "How to X" queries
+- **Comparison tables** for "X vs Y" queries
+- **Pros/cons blocks** for evaluation queries
+- **FAQ blocks** for common questions
+- **Statistic blocks** with cited sources
+
+**Structural rules:**
+
+- Lead every section with a direct answer (don't bury it)
+- Keep key answer passages to 40-60 words (optimal for snippet extraction)
+- Use H2/H3 headings that match how people phrase queries
+- Tables beat prose for comparison content
+- Numbered lists beat paragraphs for process content
+- Each paragraph should convey one clear idea
+
+### Pillar 2: Authority — Make Content Citable
+
+**The Princeton GEO research** (KDD 2024, studied across Perplexity.ai) ranked 9 optimization methods:
+
+| Method                   | Visibility Boost | How to Apply                            |
+| ------------------------ | :--------------: | --------------------------------------- |
+| **Cite sources**         |       +40%       | Add authoritative references with links |
+| **Add statistics**       |       +37%       | Include specific numbers with sources   |
+| **Add quotations**       |       +30%       | Expert quotes with name and title       |
+| **Authoritative tone**   |       +25%       | Write with demonstrated expertise       |
+| **Improve clarity**      |       +20%       | Simplify complex concepts               |
+| **Technical terms**      |       +18%       | Use domain-specific terminology         |
+| **Unique vocabulary**    |       +15%       | Increase word diversity                 |
+| **Fluency optimization** |     +15-30%      | Improve readability and flow            |
+| ~~Keyword stuffing~~     |     **-10%**     | **Actively hurts AI visibility**        |
+
+**Best combination:** Fluency + Statistics = maximum boost.
+
+**E-E-A-T alignment:**
+
+- First-hand experience demonstrated
+- Specific, detailed information (not generic)
+- Transparent sourcing and methodology
+- Clear author expertise for the topic
+
+### Pillar 3: Presence — Be Where AI Looks
+
+**Third-party sources matter more than your own site:**
+
+- Wikipedia mentions (7.8% of all ChatGPT citations)
+- Reddit discussions (1.8% of ChatGPT citations)
+- Industry publications and guest posts
+- Review sites (G2, Capterra, TrustRadius for B2B SaaS)
+- YouTube (frequently cited by Google AI Overviews)
+- Quora answers
+
+### Machine-Readable Files for AI Agents
+
+**`/pricing.md` or `/pricing.txt`** — Structured pricing data for AI agents
+
+```markdown
+# Pricing — [Your Product Name]
+
+## Free
+
+- Price: $0/month
+- Limits: 100 emails/month, 1 user
+- Features: Basic templates, API access
+
+## Pro
+
+- Price: $29/month (annual) | $35/month (monthly)
+- Limits: 10,000 emails/month, 5 users
+- Features: Custom domains, analytics, priority support
+
+## Enterprise
+
+- Price: Custom — contact sales@example.com
+- Limits: Unlimited emails, unlimited users
+- Features: SSO, SLA, dedicated account manager
+```
+
+**`/llms.txt`** — Context file for AI systems (see [llmstxt.org](https://llmstxt.org))
+
+### Schema Markup for AI
+
+| Content Type        | Schema                      | Why It Helps                        |
+| ------------------- | --------------------------- | ----------------------------------- |
+| Articles/Blog posts | `Article`, `BlogPosting`    | Author, date, topic identification  |
+| How-to content      | `HowTo`                     | Step extraction for process queries |
+| FAQs                | `FAQPage`                   | Direct Q&A extraction               |
+| Products            | `Product`                   | Pricing, features, reviews          |
+| Comparisons         | `ItemList`                  | Structured comparison data          |
+| Reviews             | `Review`, `AggregateRating` | Trust signals                       |
+| Organization        | `Organization`              | Entity recognition                  |
+
+Content with proper schema shows 30-40% higher AI visibility on non-Google AI engines. For implementation, see [`schema.md`](schema.md).
+
+---
+
+## Agentic Experiences
+
+Autonomous agents are starting to access sites directly — clicking, reading, comparing, even buying on behalf of users.
+
+**How agents access your site:**
+
+- **Visual rendering** — screenshot/read like a user
+- **DOM inspection** — parse HTML structure
+- **Accessibility tree** — rely on semantic information (labels, roles, landmarks)
+
+**What to do:**
+
+- **Render meaningful content without heavy JS gymnastics**
+- **Semantic HTML** — `<main>`, `<nav>`, `<article>`, `<button>`, proper heading hierarchy, `alt` text
+- **Clean accessibility tree** — every interactive element labelled
+- **Stable selectors / predictable layouts**
+- **Visible pricing, specs, contact info**
+
+---
+
+## Content Types That Get Cited Most
+
+| Content Type               | Citation Share | Why AI Cites It                   |
+| -------------------------- | :------------: | --------------------------------- |
+| **Comparison articles**    |      ~33%      | Structured, balanced, high-intent |
+| **Definitive guides**      |      ~15%      | Comprehensive, authoritative      |
+| **Original research/data** |      ~12%      | Unique, citable statistics        |
+| **Best-of/listicles**      |      ~10%      | Clear structure, entity-rich      |
+| **Product pages**          |      ~10%      | Specific details AI can extract   |
+| **How-to guides**          |      ~8%       | Step-by-step structure            |
+| **Opinion/analysis**       |      ~10%      | Expert perspective, quotable      |
+
+**Underperformers:** Generic blog posts without structure, thin product pages, gated content, content without dates/author, PDF-only.
+
+---
+
+## Monitoring AI Visibility
+
+### What to Track
+
+| Metric               | What It Measures                         |
+| -------------------- | ---------------------------------------- |
+| AI Overview presence | Do AI Overviews appear for your queries? |
+| Brand citation rate  | How often you're cited in AI answers     |
+| Share of AI voice    | Your citations vs. competitors           |
+| Citation sentiment   | How AI describes your brand              |
+| Source attribution   | Which of your pages get cited            |
+
+### AI Visibility Monitoring Tools
+
+| Tool           | Coverage                                      |
+| -------------- | --------------------------------------------- |
+| **Otterly AI** | ChatGPT, Perplexity, Google AI Overviews      |
+| **Peec AI**    | ChatGPT, Gemini, Perplexity, Claude, Copilot+ |
+| **ZipTie**     | Google AI Overviews, ChatGPT, Perplexity      |
+| **LLMrefs**    | ChatGPT, Perplexity, AI Overviews, Gemini     |
+
+### DIY Monitoring (No Tools)
+
+Monthly manual check:
+
+1. Pick your top 20 queries
+2. Run each through ChatGPT, Perplexity, and Google
+3. Record: Are you cited? Who is? What page?
+4. Log in a spreadsheet, track month-over-month
+
+---
+
+## What NOT to Do
+
+1. **Write separate content "for AI"** — risks scaled content abuse spam policy
+2. **Chunk pages into AI-bait fragments** — use normal paragraph + heading structure
+3. **Generate at scale for ranking manipulation**
+4. **Pursue inauthentic mentions** — real participation only
+5. **Block AI crawlers if you want citation**
+6. **Hide your main content behind JS that doesn't render**
+7. **Skip E-E-A-T fundamentals**
+
+---
+
+## Common Mistakes
+
+- **Ignoring AI search entirely** — ~45% of Google searches now show AI Overviews
+- **Treating AI SEO as separate from SEO** — Good traditional SEO is the foundation
+- **Writing for AI, not humans** — won't get cited or convert
+- **No freshness signals** — Undated content loses to dated content
+- **Gating all content** — AI can't access gated content
+- **Ignoring third-party presence** — Wikipedia mention may beat your own blog
+- **No structured data** — Schema markup gives AI structured context
+- **Keyword stuffing** — Actively reduces AI visibility by 10% (Princeton GEO study)
+- **Hiding pricing behind "contact sales" or JS-rendered pages** — Add a `/pricing.md` file
+- **Blocking AI bots** — If GPTBot, PerplexityBot, or ClaudeBot are blocked, those platforms can't cite you
+- **Generic content without data** — "We're the best" won't get cited
+- **Forgetting to monitor** — Check AI visibility monthly at minimum
+
+---
+
+## Task-Specific Questions
+
+1. What are your top 10-20 most important queries?
+2. Have you checked if AI answers exist for those queries today?
+3. Do you have structured data (schema markup) on your site?
+4. What content types do you publish?
+5. Are competitors being cited by AI where you're not?
+6. Do you have a Wikipedia page or presence on review sites?
+
+---
+
+## Related Skills
+
+- **seo-audit** (sibling): Traditional technical and on-page SEO audits
+- **schema** (sibling, pointer): Structured data implementation
+- **content-strategy** (pointer to digital-marketing): Plan what content to create
+- **competitors** (sibling): Build comparison pages that get cited
+- **programmatic-seo** (pointer to digital-marketing): SEO pages at scale
+- **copywriting** (general): Write human-readable + AI-extractable content

package/.merlin-core/skills/domain/marketing-ops/references/acquire/aso/references/apple-specs.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: aso
+upstream_path: skills/aso/references/apple-specs.md
+---
+
+# apple-specs — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/aso/references/apple-specs.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/aso/references/apple-specs.md
+
+**Parent skill:** [`../aso.md`](../aso.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/aso/references/apple-specs.md`, then prepend the standard Adjacency header.

package/.merlin-core/skills/domain/marketing-ops/references/acquire/aso/references/benchmarks.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: aso
+upstream_path: skills/aso/references/benchmarks.md
+---
+
+# benchmarks — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/aso/references/benchmarks.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/aso/references/benchmarks.md
+
+**Parent skill:** [`../aso.md`](../aso.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/aso/references/benchmarks.md`, then prepend the standard Adjacency header.

package/.merlin-core/skills/domain/marketing-ops/references/acquire/aso/references/google-play-specs.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: aso
+upstream_path: skills/aso/references/google-play-specs.md
+---
+
+# google-play-specs — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/aso/references/google-play-specs.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/aso/references/google-play-specs.md
+
+**Parent skill:** [`../aso.md`](../aso.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/aso/references/google-play-specs.md`, then prepend the standard Adjacency header.

package/.merlin-core/skills/domain/marketing-ops/references/acquire/aso/references/report-template.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: aso
+upstream_path: skills/aso/references/report-template.md
+---
+
+# report-template — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/aso/references/report-template.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/aso/references/report-template.md
+
+**Parent skill:** [`../aso.md`](../aso.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/aso/references/report-template.md`, then prepend the standard Adjacency header.

package/.merlin-core/skills/domain/marketing-ops/references/acquire/aso/references/scoring-criteria.md

@@ -0,0 +1,19 @@
+---
+source: coreyhaines31/marketingskills (MIT) v2.0.1
+imported: 2026-05-20 (stub) — full body deferred to follow-up cleanup
+stage: acquire
+skill: aso
+upstream_path: skills/aso/references/scoring-criteria.md
+---
+
+# scoring-criteria — reference stub
+
+This is a thin pointer to an upstream reference. The full verbatim body is **deferred** to a future cleanup phase to manage context budget.
+
+**Upstream URL (canonical body):** https://github.com/coreyhaines31/marketingskills/blob/main/skills/aso/references/scoring-criteria.md
+
+**Raw fetch URL:** https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/skills/aso/references/scoring-criteria.md
+
+**Parent skill:** [`../aso.md`](../aso.md) (stage: acquire)
+
+**To import the full body** (future task): `curl -sSL <raw URL> -o references/acquire/aso/references/scoring-criteria.md`, then prepend the standard Adjacency header.