Comment Ça Marche

# How does an agent know if a site has
# AI-optimized content?

GET / HTTP/1.1
Accept: text/html

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 187429

# No signal for AI-optimized content
# No capability declaration
# Agent must download and parse HTML
# to understand anything about the site

# 1. Site-level: /.well-known/mako
GET /.well-known/mako HTTP/1.1

{ "mako": "1.0" }

# 2. Page-level: HTML <link> element
<link rel="alternate" type="text/mako+markdown">

# 3. Embedded: HTML <script> element
<script type="text/mako+markdown" id="mako">

HEAD /products/running-shoes HTTP/1.1
Host: example.com
Accept: text/html

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 187429
Last-Modified: Mon, 10 Feb 2026 09:00:00 GMT

# Agent knows: it's HTML, 187 KB
# Agent does NOT know:
#   - What type of content (product? blog?)
#   - How many tokens to process
#   - What language
#   - What entity this page is about
# Must download full page to decide relevance

HEAD /products/running-shoes HTTP/1.1
Host: example.com
Accept: text/mako+markdown

HTTP/1.1 200 OK

# MUST — required for valid MAKO response
Content-Type: text/mako+markdown
X-Mako-Version: 1.0
X-Mako-Type: product
X-Mako-Tokens: 245
X-Mako-Lang: en
Vary: Accept

# SHOULD — standard HTTP caching & context
ETag: "mako-a1b2c3"
Cache-Control: public, max-age=3600
Last-Modified: Sat, 15 Feb 2026 10:00:00 GMT
Content-Location: /products/running-shoes

# MAY — advanced agent capabilities
X-Mako-Actions: add_to_cart, check_availability

# 0 bytes transferred
# Agent knows: product, 245 tokens, en

<div class="product-page">
  <nav><!-- 800 tokens --></nav>
  <div class="sidebar"><!-- 600 tokens --></div>
  <div class="main-content">
    <h1>Running Shoes Pro</h1>
    <span class="price">$129.99</span>
    <p>Lightweight performance shoe...</p>
  </div>
  <div class="recommendations"><!-- 900 tokens --></div>
  <footer><!-- 500 tokens --></footer>
  <!-- 1,325 tokens of actual content
       buried in 4,125 tokens total -->
</div>

GET /products/running-shoes HTTP/1.1
Accept: text/mako+markdown

HTTP/1.1 200 OK
Content-Type: text/mako+markdown

---
mako: "1.0"
type: product
entity: Running Shoes Pro
tokens: 245
language: en
updated: 2026-02-15T10:00:00Z
summary: >-
  Lightweight running shoe with responsive
  cushioning. $129.99 at Example Store.
---

# Running Shoes Pro

Lightweight performance running shoe with
responsive ZoomX cushioning and breathable
mesh upper.

**Price:** $129.99
**Sizes:** 7-13
**Colors:** Black, White, Red

# Also available via HTML <script> embedding
# without content negotiation

# Agent finds 127 links on the page:
<a href="/">Home</a>
<a href="/about">About</a>
<a href="/cart">Cart (3)</a>
<a href="/products/running-shoes?color=red">Red</a>
<a href="/products/running-shoes?color=blue">Blue</a>
<a href="/privacy">Privacy Policy</a>
<a href="/terms">Terms of Service</a>
<!-- ...120 more links -->

# No context on which links matter
# Agent must guess or crawl them all

# Links section in MAKO frontmatter:
links:
  internal:
    - url: /products/running-socks
      context: Matching performance socks
    - url: /products/insoles-pro
      context: Compatible custom insoles
    - url: /guides/choosing-running-shoes
      context: Buying guide for runners
  external:
    - url: https://example.com/reviews
      context: Independent review (4.8/5)

# 5 links with purpose vs 127 blind links

<!-- Actions buried in JavaScript -->
<form id="add-to-cart"
      action="/api/cart"
      method="POST">
  <input type="hidden" name="id" value="SKU-1234">
  <input type="hidden" name="csrf" value="...">
  <button onclick="addToCart(event)">
    Add to Cart
  </button>
</form>

<!-- Agent cannot discover or invoke this
     without executing JavaScript -->

# Actions section in MAKO frontmatter:
actions:
  - name: add_to_cart
    description: Add to shopping cart
    endpoint: /api/cart
    method: POST
    params:
      sku: "SHOE-PRO-001"
      quantity: 1
  - name: check_availability
    description: Check stock by zip code
    endpoint: /api/stock?sku=SHOE-PRO-001
  - name: notify_restock
    description: Get notified when back in stock
    endpoint: /api/notify

# Machine-readable, no JS required

# Every visit downloads the full page

GET /products/running-shoes HTTP/1.1
Accept: text/html

HTTP/1.1 200 OK
Content-Length: 187429

# Same content, downloaded again
# 187 KB transferred
# 4,125 tokens re-processed
# No way to check "has it changed?"

GET /products/running-shoes HTTP/1.1
Accept: text/mako+markdown
If-None-Match: "a1b2c3"

HTTP/1.1 304 Not Modified
ETag: "a1b2c3"
Cache-Control: public, max-age=3600

# 0 bytes transferred
# 0 tokens processed
# Agent confirms: content unchanged
# Saved: 245 tokens + full round-trip