| name | aaio |
| description | Agentic AI Optimization — make websites crawlable, citable, and usable by AI agents and browser automation. Use when building or auditing web projects for AI discoverability, implementing robots.txt AI bot policies, adding JSON-LD structured data, creating markdown twin routes, building accessibility trees for agent UX, or optimizing content structure for AI citation. Triggers on: AI SEO, AAIO, agentic optimization, AI discoverability, llms.txt, markdown twins, agent-ready, AI crawlers, structured data audit, schema.org, AI bot policy. |
Agentic AI Optimization (AAIO)
Make sites visible and usable to AI crawlers, citation engines, and browser agents.
Based on Joel Hooks' implementation checklist. Not just "AI SEO" — it's the overlap of traditional SEO, static truth in initial HTML, machine-readable surfaces, and UX ergonomics for agents.
Core Principle
If AI crawlers can't read your pages and browser agents can't operate your UI, your site is invisible in the workflows that matter next.
8-Step Checklist
1. Crawl Policy
Set explicit robots.txt for AI bots. Three classes:
- Search/indexing: OAI-SearchBot, Googlebot, Bingbot, Claude-SearchBot, PerplexityBot → Allow
- User-triggered: ChatGPT-User, Claude-User, Perplexity-User → Allow
- Training: GPTBot, Google-Extended, ClaudeBot → Block (unless you want training)
Add sitemap. Use noindex on private pages. Don't confuse llms.txt with discoverability — it's a hint surface, not the main channel.
See references/robots-txt-template.md for copy-paste template.
2. Critical Content in Initial HTML
- Server-render every page you want cited (docs, pricing, features, FAQs)
- Don't ship blank SPA shells — if
curl can't see it, AI can't see it
- Don't hide facts behind tabs, modals, accordions, or client-side fetches
- Use real
<a href> links, not div + onClick
Verify: curl -sL URL | grep 'key fact' — if missing, fix rendering.
3. Structured Content Patterns
- One heading = one idea. One paragraph = one claim.
- Front-load answers in first sentence under each heading
- Sections must make sense when copied out of context
- Use Q&A blocks, numbered steps, bullets, tables for citable facts
- Replace vague adjectives with measurable claims
- Put canonical answer in ONE place — duplication creates conflict
4. JSON-LD Schema
Match schema to page type. See references/json-ld-templates.md for templates.
| Page Type | Schema Types | Minimum Fields |
|---|
| Site-wide | Organization, WebSite | name, url, logo |
| Article/doc | Article, WebPage, BreadcrumbList | headline, description, dates, author, publisher |
| FAQ | FAQPage | mainEntity[] with Question + acceptedAnswer |
| How-to | HowTo | name, step[] |
| Product | Product, Offer | name, description, price, availability, brand |
Rule: Every JSON-LD value must match visible page content exactly. Re-validate after every content change.
5. Accessibility Tree = Agent Interface
OpenAI Atlas, Microsoft browser automation, and most agent frameworks use ARIA roles/labels/states. A11y work IS agent-interface work.
- Native elements first:
<button>, <a>, <input>, <select>, <table>
- Label every form control. Add
autocomplete values.
- Use landmarks:
<nav>, <main>, <header>, <footer>
- Logical heading hierarchy. Descriptive link text.
- Expose state changes via ARIA.
Anti-patterns: <div class="button" onclick>, <input placeholder="Email"> without label, <div onclick="location.href">
Verify: If Playwright getByRole() can't find it, agents can't either.
6. Machine Interfaces & Markdown Twins
The money section. A page can be indexable and still suck for agents.
Three-surface pattern:
/page → HTML for humans/page.md → Markdown for agents (Content-Type: text/markdown)/api/... → Structured JSON
Same canonical source. Different projections. No drift.
Discovery surfaces:
robots.txt → advertise sitemap.xml AND sitemap.mdsitemap.md → list human URLs + markdown twinsllms.txt → point to markdown sitemap and access patterns/api → discovery route with next_actions
MIME discipline:
- HTML:
text/html; charset=utf-8
- Markdown:
text/markdown; charset=utf-8
- JSON:
application/json; charset=utf-8
- llms.txt:
text/plain; charset=utf-8
If a markdown endpoint returns text/html, that's a bug.
See references/machine-interfaces.md for implementation patterns.
7. Agent-Ready Checkout (Commerce Only)
Skip for non-commerce. For e-commerce:
- Clean product catalog (precise titles, current prices, stable SKUs)
- Product + Offer schema on every product page
- Price/availability/shipping in visible HTML
- Evaluate Stripe Agentic Commerce Protocol if applicable
8. Measurement & Regression
- Track AI referrals separately (utm_source=chatgpt.com etc.)
- Log bot hits by user-agent
- Track citation presence for core queries
- Regression tests for important pages:
rg 'OAI-SearchBot|Googlebot|Claude-SearchBot|PerplexityBot' access.log
curl -sL URL | rg 'application/ld\+json'
lynx -dump URL
Quick Audit Workflow
When auditing an existing site:
curl -s SITE/robots.txt — check AI bot policycurl -sL SITE/ | head -100 — facts in initial HTML?curl -sL SITE/ | rg 'application/ld\+json' — schema present?- Check heading hierarchy and content structure
- Test a11y tree in devtools or Playwright
- Check for markdown/API discovery surfaces
curl -I -A 'OAI-SearchBot/1.3' SITE/ — bot response correct?
For Coding Repos (AGENTS.md)
Passive always-on context in AGENTS.md beats optional skills the agent may never load:
## Agent retrieval hints
- Prefer retrieval-led reasoning over pretrained guesses
- Start with `/api`, `sitemap.md`, and `/.md` twins before scraping HTML
- Verify Content-Type before parsing
- Treat HTML, markdown, JSON as projections of same resource
## Operator path
- Machine-readable content: try `{page}.md` first
- Structured discovery: `/api`
- Broad site discovery: `/sitemap.md`
Definition of Done
