By JaySeptember 2026
How We Keep Our Own Blog Readable to AI Agents
Our last post made a simple point: if an AI agent can't read your site, it can't recommend you to the person asking - and that customer just quietly goes somewhere else, with nothing in your analytics to explain why. That post also set the goal for our own blog: not just crawlable, but genuinely easy for an agent to read cleanly. Here's what we've built toward that so far, and what we're rolling out next.
Two pieces are already live, with more on the way.
The skill: word-for-word, not a summary
Every post on this blog is written once, as HTML. A Claude Code skill (blog-to-markdown, living in this repo's .claude/skills/) converts that HTML into a Markdown companion file, following a fixed set of structural rules rather than improvising. It's self-contained and de-branded on purpose, so it's just as useful on someone else's blog as it is on ours - download it here and drop it straight into your own project's .claude/skills/ folder.
- A blockquote stays a real Markdown blockquote, not flattened into inline italic text - the structure matters to a parser, not just the words.
- Every byline line gets preserved, including a second one most people would miss (an author name linking to a
mailto:address, sitting below a separate brand/category line). - Code blocks keep their caption, placed directly under the closing fence, exact same text.
- A styled CTA button becomes a plain Markdown link, using whatever its label actually says today - not whatever prose used to sit next to it before it became a button.
The one rule that matters most: word-for-word accurate. Not a summary, not a "close enough" rewrite. An agent reading the Markdown version should come away with exactly what a human gets from the rendered page, no more and no less.
We hold this to a higher bar than "looks right."
We actually invoked the skill for real, against both live posts on this blog, output to a scratch directory, and diffed the result against the already-deployed, known-correct .md files.
Byte-for-byte identical, both times. That same testing pass is also how we caught and fixed two specific improvements now built into the skill: the byline mapping now accounts for a second metadata line, and there's explicit guidance for writing a fresh .md file when none exists yet to diff against.
Live today: a Markdown twin for every post
Each post already has a plain .md file sitting next to its HTML, live at its own URL. An agent that fetches /blog/how-to-make-your-website-visible-to-ai.md directly gets clean Markdown right now. We're rolling out the fuller version next: the same URL responding automatically based on what's actually asked for, across every page on the site.
A static file nobody knows exists isn't worth much, so each post's HTML head carries a pointer to its own Markdown twin, using the same rel="alternate" link type the HTML standard defines for exactly this - the standard's own wording is "a reformulation of the current document in the specified format," with an RSS or Atom feed as its most familiar example, not the only one:
<link rel="alternate" type="text/markdown" href="/blog/how-to-make-your-website-visible-to-ai.md">The same relationship also goes out as an HTTP Link header on every response for that page, alongside the sitemap and api-catalog links this site already sends:
Link: </blog/how-to-make-your-website-visible-to-ai.md>; rel="alternate"; type="text/markdown"Either way, something reading the page - or just its headers, without ever parsing the HTML body - can find the Markdown version on its own.
The real benefit: efficiency, not rankings
This is an efficiency story, not a ranking one. Cloudflare's own announcement of their equivalent feature makes the case in one line:
This blog post you're reading takes 16,180 tokens in HTML and 3,150 tokens when converted to markdown. That's a 80% reduction in token usage.
That's the actual claim: cost and accuracy for an agent that's already decided to read the page. Cloudflare's own marketing stops right there. A controlled experiment run by OtterlyAI in 2026 tested whether serving Markdown goes further than that, into actual citations: an HTML page and an identical Markdown twin, linked equally from a footer, tracked for 14 days. HTML picked up 137 AI-bot visits and showed up as a citation source. The Markdown twin got zero of both. One site, two weeks, and the authors are upfront it's "not an industry-wide study" - but it's the clearest evidence available, and it lines up with what Cloudflare's own numbers already point to: efficiency for the agents that show up, not a way to get more of them showing up in the first place.
Getting found in the first place is a different job, one the first post's robots.txt and bot-naming work already covers. This layer is about what happens once an agent arrives, and we're rolling it out across the whole site: one URL responding automatically with the right format, instead of two hand-made siblings, backed by a Cloudflare Pages Function reading the Accept header.
Confirming that build turned up something we're folding in from the start: Cloudflare's edge cache doesn't honor Vary: Accept by default. Per Cloudflare's own cache documentation, only Vary: Accept-Encoding is respected automatically - everything else needs an explicit Cache Rule. The rollout ships with that Cache Rule alongside the header itself, not the header on its own.
Today, that means a Markdown twin at its own URL for every post, plus the header and link that let an agent find it on its own. The full version - one URL, automatic, sitewide - is what's rolling out next. Either way, it's not a ranking play: just the most efficient way to actually serve content to an agent that already knows to ask for it by name.
This is the same standard we hold everything on this site to: test the actual claim before building around it, not the marketing version of it. That's the part we bring to your site too.
Want to see it firsthand first? Download the skill and run it against your own blog.