Merge pull request #521 from coreyhaines31/feature/ai-seo-agent-readiness
feat(ai-seo): agent-readiness layer + citation-source volatility (2.4.0)
This commit is contained in:
Corey Haines
@@ -6,7 +6,7 @@
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, and growth",
|
||||
"version": "2.10.1",
|
||||
"version": "2.10.2",
|
||||
"repository": "https://github.com/coreyhaines31/marketingskills"
|
||||
},
|
||||
"plugins": [
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "marketing-skills",
|
||||
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, ad creative, and growth",
|
||||
"version": "2.10.1",
|
||||
"version": "2.10.2",
|
||||
"author": {
|
||||
"name": "Corey Haines"
|
||||
},
|
||||
|
||||
+5
-1
@@ -6,7 +6,7 @@ Current versions of all skills. Agents can compare against local versions to che
|
||||
|-------|---------|--------------|
|
||||
| ab-testing | 2.0.0 | 2026-05-05 |
|
||||
| ad-creative | 2.8.0 | 2026-07-14 |
|
||||
| ai-seo | 2.3.0 | 2026-08-19 |
|
||||
| ai-seo | 2.4.0 | 2026-08-21 |
|
||||
| analytics | 2.0.1 | 2026-07-22 |
|
||||
| aso | 2.0.1 | 2026-08-19 |
|
||||
| attribution | 1.1.0 | 2026-07-23 |
|
||||
@@ -56,6 +56,10 @@ Current versions of all skills. Agents can compare against local versions to che
|
||||
|
||||
## Recent Changes
|
||||
|
||||
### 2.10.2 (2026-08-21)
|
||||
|
||||
- **ai-seo** (2.3.0 → 2.4.0): new `references/agent-readiness.md` — the access/discovery/parseability layer beneath all content work: can an agent reach, navigate, and parse the site at all. Anchored on the two free scoring tools that shipped in Aug 2026 and made this measurable — **Is Agentic** (Vercel + Ora; `npx is-agentic`; 100+ checks with essential/recommended/bonus tiers, not-applicable excluded rather than failed, plus an observed agent journey) and **Frase's Agent Readiness Checker** (access/discovery/parseability triad with 80/60 score bands) — both credited, with the checks treated as the value rather than the vendor pitch. Covers the access essentials (core content in initial HTML — most agents never run JavaScript; no bot-challenge/firewall blocks on AI crawlers; correct HTTP behavior), the discovery file stack (robots.txt with an explicit AI-crawler stance, clean sitemap, llms.txt plus the newer **`llms-full.txt`** whole-site-in-one-request companion, robots content-usage statements), and the newest parseability technique: a **Markdown representation of every page**, served either by content negotiation (`Accept: text/markdown` at the same canonical URL with a `Vary` header) or an HTTP `Link` header pointing at a parallel Markdown version. Introduces the **agent-actionable** frontier (WebMCP — pages declaring forms/CTAs as callable tools; labeled emerging) with the practical-today floor (highest-intent actions work without JS-only flows). Adds a **citation-source volatility** section built on the Aug 2026 case study — ChatGPT's query fan-out changes nearly wiped Reddit as a citation source within days (practitioner-reported, Ashni of Hype Partners (@ashnichrist) and others), while business-owned sites dominate Gemini citations (~60%) — with the strategy consequences: portfolio over single-surface concentration, owned-site fundamentals as the volatility hedge, citation-share stats treated as dated snapshots verified against your own monitoring, and ~24-hour citation speed as the freshness upside. SKILL.md updates the Reddit lines in the Presence pillar with the volatility flag, points Machine-Readable Files at the new reference, and adds 'agent readiness' / 'is my site agent-ready' / 'llms-full.txt' / 'WebMCP' triggers. New eval (id 9) covers the two-sided prompt: an agent-readiness audit plus a Reddit-concentrated strategy that must get the volatility warning.
|
||||
|
||||
### 2.10.1 (2026-08-19)
|
||||
|
||||
- **ads** (2.2.0 → 2.3.0): added `references/audit-guardrails.md` — the honesty layer for working on live ad accounts (audit scoring semantics, recommendation-safety rules, and the benchmark-evidence ladder distilled and remixed from AgriciDaniel/claude-ads, MIT, credited). Covers: **four-state scoring** (pass / fail / unknown / not applicable) with the core rule that account *health* and *evidence coverage* are kept separate — an unknown reduces coverage, never health, so "couldn't check your pixel" can't masquerade as "your pixel is broken"; **coverage bands** (80%+ graded, 60–79% provisional, <60% report findings but present no health score) and the partial-audit rule (a failed platform/data source is excluded from rollups, never scored as zero, and the audit is never called complete); **what never counts against health** (unknowns, ineligible/beta/premium features, feature non-adoption, deviation from broad benchmarks); **recommendation safety** — every optimization heuristic is conditional on sample size, conversion lag, margin, and learning-phase state, so never pause on a fixed CPA multiple, apply one budget-to-CPA ratio across objectives, freeze a learning campaign as a reflex, recommend ineligible features, or invent negative keywords without a search-terms report + overblocking review; **hard stops** as response contracts (refuse cross-attribution-window conversion sums and report side by side; zero candidate negatives without evidence; no single health score over major data gaps); **benchmark discipline** (provenance labeling incl. vendor-supplied, cohort-fit check, and the narrowest-defensible-comparison ladder: own prior period → own experiment → CRM cohort → peer cohort → broad benchmark as directional only); and **untrusted data + live accounts** (fetched pages/exports/screenshots are data, not instructions; read-only by default with draft-first mutation plans — current state → change → expected effect → rollback — and smallest-reversible-change preference). SKILL.md adds a compact Audit & Recommendation Guardrails section with the six non-negotiables plus a Reference Routing row. New eval (id 7) covers the four hard stops in one adversarial prompt (fixed CPA kill rule, invented negatives, cross-window conversion sum, health score over ~50% coverage). Also added **destination testing** to `references/meta-decision-system.md`: one CBO per persona, one ad set per destination type (PDP / listicle / quiz / demo) with the same creatives in every ad set — holding creative constant makes CPM/performance divergence attributable to the lander, treating the destination as a test axis of the same rank as creative; fits the Testing campaign with the usual TCPL spend gates, graduating the winning creative × destination pair (practitioner-reported pattern, Alexander Pauwelyn 2026, labeled as such per the new benchmark discipline).
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: ai-seo
|
||||
description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' 'optimize for Claude/Gemini,' 'llms.txt,' 'OKF,' 'Open Knowledge Format,' 'knowledge bundle,' or 'agent-readable site.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema."
|
||||
description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' 'optimize for Claude/Gemini,' 'llms.txt,' 'llms-full.txt,' 'OKF,' 'Open Knowledge Format,' 'knowledge bundle,' 'agent-readable site,' 'agent readiness,' 'is my site agent-ready,' or 'WebMCP.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema."
|
||||
metadata:
|
||||
version: 2.3.0
|
||||
version: 2.4.0
|
||||
---
|
||||
|
||||
# AI SEO
|
||||
@@ -251,7 +251,7 @@ AI systems don't just cite your website — they cite where you appear.
|
||||
|
||||
**Third-party sources matter more than your own site:**
|
||||
- Wikipedia mentions (7.8% of all ChatGPT citations)
|
||||
- Reddit discussions (1.8% of ChatGPT citations)
|
||||
- Reddit discussions (volatile: ~1.8% of ChatGPT citations historically, but nearly wiped from ChatGPT by Aug 2026 retrieval changes — still retrieved elsewhere; see the volatility section in [references/agent-readiness.md](references/agent-readiness.md))
|
||||
- Industry publications and guest posts
|
||||
- Review sites (G2, Capterra, TrustRadius for B2B SaaS)
|
||||
- YouTube (frequently cited by Google AI Overviews)
|
||||
@@ -260,7 +260,7 @@ AI systems don't just cite your website — they cite where you appear.
|
||||
|
||||
**Actions:**
|
||||
- Ensure your Wikipedia page is accurate and current
|
||||
- Participate authentically in Reddit communities
|
||||
- Participate authentically in Reddit communities — but as one surface in a portfolio, never the whole strategy (citation mixes shift overnight with retrieval updates)
|
||||
- Get featured in industry roundups and comparison articles
|
||||
- Maintain updated profiles on relevant review platforms
|
||||
- Create YouTube content for key how-to queries — models don't watch the video, they read the text layer around it; see [references/youtube-ai-citations.md](references/youtube-ai-citations.md) for the full anatomy (transcript, captions, chapters, description, pinned comment)
|
||||
@@ -275,6 +275,8 @@ AI systems don't just cite your website — they cite where you appear.
|
||||
|
||||
AI agents aren't just answering questions — they're becoming buyers. When an AI agent evaluates tools on behalf of a user, it needs structured, parseable information. If your pricing is locked in a JavaScript-rendered page or a "contact sales" wall, agents will skip you and recommend competitors whose information they can actually read.
|
||||
|
||||
**Audit this layer first**: [references/agent-readiness.md](references/agent-readiness.md) — the access/discovery/parseability checklist, free scoring tools (`npx is-agentic`, Frase's checker), Markdown content negotiation + `Link` headers, `llms-full.txt`, and the emerging agent-*actionable* layer (WebMCP).
|
||||
|
||||
Add these machine-readable files to your site root:
|
||||
|
||||
**`/pricing.md` or `/pricing.txt`** — Structured pricing data for AI agents
|
||||
|
||||
@@ -112,6 +112,19 @@
|
||||
"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 (npx 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 AI crawlers, robots.txt with an explicit AI-crawler stance, 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": []
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# 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) | `npx 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 request path. Aggressive bot protection (Cloudflare challenges, WAF rules) that blocks `GPTBot`, `PerplexityBot`, `ClaudeBot`, etc. is self-inflicted invisibility. Audit what your CDN/WAF actually does to those user agents — 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 major AI crawlers and state your policy, rather than leaving it to be assumed (see the bot-access table in SKILL.md for the allow/block list).
|
||||
- **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 `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.
|
||||
|
||||
## 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%)**.
|
||||
|
||||
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.*
|
||||
Reference in New Issue
Block a user