Timothy Jordan

llms.txt saves an agent real tokens, but it won’t read it unless you ask

2026-07-01T00:00:00+00:00

Cross-posted from a14y.dev

Summary

Ship the discovery layer, then tell the agent to use it.

Publishing an llms.txt is increasingly common, though far from universal: in our survey of the CrUX top-100k, only about 1 in 4 sites (27% of the 50,074 we reached) ship one. The harder part is getting an AI agent to actually read the file. In an earlier a14y benchmark, a clean discovery layer (an llms.txt index plus markdown mirrors) cut an agent’s token use roughly in half at the same answer quality. In a new benchmark, the agent captured that saving only when we told it to look. Not one of the in-page signals we tried (a tag, a visible “For agents” footer link) got it to use llms.txt on its own. A single line in the prompt did.

Metric	Result
Page-side links	0 / 20 reps used llms.txt
One line in the prompt	5 / 5 reps used it
Tokens, with the nudge	−33% on the same page

The payoff is real

Let’s start with the good news. In our earlier discovery-layer study, we ran the same evaluation task twice against the same site: once with the agent-discovery files served, once with them missing. Same content, same prompt, same model. The discovery layer cut the cost about in half.

Condition	Tokens (mean)	Tool calls	Answer quality (judge)
Discovery layer present	~123K	~10	tied
Discovery layer absent	~240K	~20	tied

Roughly 2x fewer tokens, about half the tool calls, no measurable drop in quality. When an agent can pull a tight markdown index instead of crawling and re-parsing a pile of HTML, it does less work to reach the same answer.

But the agent won’t take the payoff on its own

Five arms, identical content and identical discovery files (all returning 200). The only thing that changed was how the page points at /llms.txt. Claude 2.1.141, isolated Docker, five reps each, adoption read from the web server’s request log.

Arm	Signal	Fetched /llms.txt	Tokens (avg ± sd)	Tools	Page GETs	Judge	Pass
no-link (control)	none	0 / 5	266,591 ± 32,066	14.6	59	75.2 ± 6.8	80%
head link		0 / 5	257,743 ± 53,953	13.2	47	72.4 ± 8.3	80%
head link		0 / 5	254,641 ± 47,968	14.4	65	80.4 ± 5.5	100%
visible footer link	“For agents” block	0 / 5	251,741 ± 38,857	12.8	48	76.0 ± 3.3	100%
nudge	prompt: “check /llms.txt first”	5 / 5 (+4/5 sitemap.md)	177,735 ± 32,131	17.0	91	88.8 ± 1.6	100%

We tried three genuinely different ways to point the page at /llms.txt: a machine-readable in the head, a standards-style , and a plain visible “For agents” footer link a human would click. The agent ignored all three. The four page arms cluster tightly, 252K to 267K tokens and 0 of 5 adoption, with the spread between link styles sitting well inside the noise (token sd of 32K to 54K, judge sd of 3 to 8). The agent received the bytes (it fetched the homepage, head tags and all) and acted on none of them.

It’s not that we picked the wrong link format. Every link format failed. The lever is the instruction, not the markup. We changed one line of the prompt and left the page exactly as it was, with no link at all. Adoption went to five out of five (and four of five also pulled sitemap.md), and tokens dropped from 266,591 to 177,735. That is 88,856 fewer tokens, a 33% reduction on the same page, attributable purely to the agent using a layer that was already there in every arm. Sitting next to the earlier ~2x, the two figures bracket the opportunity: the prior study measured having the layer at all, this one measures actually using it, isolated to a single line of prompt.

A few details from the run that sharpen the picture:

The cost is ingestion, not generation. Output tokens were tiny across every arm, roughly 5K to 9K per rep. Almost the entire bill is input plus cache, the cost of reading the site in. That is exactly the cost the discovery layer cuts, which is why “use the index” shows up as a token drop and not a quality drop.
More fetches, far less content. The nudge arm actually made more requests than the control (91 page GETs versus 59), yet used fewer tokens. It pulled the lean .md mirrors (for example /scorecards/0.2.0/checks/llms-txt.exists.md) instead of full HTML pages. More round trips, a fraction of the bytes each.
Quality went up, not down. The nudge arm posted the highest judge score (88.8) and the tightest spread (± 1.6) of any arm, at 100% pass. Using the structured index made the answers cheaper and more consistent.
Clean measurement. Zero requests hit the live a14y.dev in any arm. Adoption was read from the static server’s log, filtered to the agent container’s IP, so there is no contamination from background traffic. (a14y.dev’s own copy documents the llms-txt.exists check, so this was a friendly case for content-based discovery; adoption was still 0 of 5 without the nudge.)

This is not just a Claude quirk

It would be easy to write this off as one model’s behavior on one site. It is not. When we went looking for whether any major agent or crawler consumes llms.txt in the wild, the evidence pointed the same direction.

The cleanest distinction to hold onto is publish versus consume. Almost everyone publishes. Cursor serves an llms.txt for its own docs. Anthropic publishes one. Every site built on Mintlify gets an llms.txt (and an llms-full.txt) automatically, zero maintenance, which is how a whole category of docs sites gained one at once. That is a real and healthy trend. But publishing a file is not the same as an agent reading one, and on the consume side the record is close to empty.

Ahrefs analyzed 137,210 domains. Of the roughly 38,000 with a valid llms.txt, 97% received zero requests for that file in the month studied. Of the requests that did land, most were ordinary bots, not AI agents. No AI bot went looking for files that did not exist.
Google’s John Mueller has said, more than once, that no AI system currently uses llms.txt, that you can see in your server logs the bots do not even check for it, and that it is “comparable to the keywords meta tag.” When llms.txt files showed up on Google’s own developer properties, he said plainly it was a CMS artifact, not an endorsement.
Google’s official generative-AI search guidance now states you do not need to create llms.txt or any special machine-readable files to appear in AI search, and that Search ignores them: keeping one is fine, it just “won’t harm (nor help)” rankings.
Independent server-log audits (Adobe AEM, OtterlyAI) put verified LLM fetches of llms.txt at roughly 0.1% to 1% of traffic to those files. Most of the rest is scanners and auditors.

And the tools people assume are quietly reading it? For GitHub Copilot, Windsurf, Cline, Aider, Continue, Devin, ChatGPT’s browsing and Atlas modes, and Gemini’s agent, we found no public statement either way (as of this research, mid-2026). Silence is not adoption. We also went in expecting to find that Claude Code would fetch llms.txt when linked from the page. The hope did not survive verification. Claude Code can show up in server logs fetching llms.txt, but only when a user or a prompt points it there, not on its own. We don’t have any evidence that any major agent fetches llms.txt by default.

What to actually do with this

The wrong conclusion here would be “don’t bother.” That is not what the data says: the value of the discovery layer is real and significant, and it lands whenever you control the agent or its instructions. Three situations where that is true today.

Your own agents

If you build a docs assistant, a support bot, an MCP server, or an internal coding agent that reads your site, you write the prompt. Tell it to start from /llms.txt. This data says that a single instruction is worth roughly a third of the tokens on the spot, and up to half against a no-discovery baseline.

Agentic tooling you can configure

A growing set of harnesses let the user or the project point the agent at a markdown index. The payoff shows up the moment the pointer exists. Notably, Chrome’s experimental “agentic browsing” audit in Lighthouse already checks for llms.txt, a hint that the consume side may start catching up to the publish side.

Future-proofing at near-zero cost

Publishing the layer is cheap and mostly static. If and when agents start consuming it by default, you are already done. If they never do, you have lost very little, and your own tooling benefited the whole time.

What the data definitely does not support is treating llms.txt as an SEO move for third-party AI search. Today, the big crawlers mostly ignore it. Publish it because it makes the agents you point at your content dramatically cheaper and more accurate, not because ChatGPT or Gemini will discover it on their own.

Also, llms.txt is not a standard. It is a good idea that caught on, but a better convention may well replace it. What the data backs is narrower and more durable: a clean and lean discovery layer saves real tokens, and the way you capture that saving today is to tell the model to use it. So bet on the two things that hold no matter how the conventions shake out, the token savings and the instruction, rather than on llms.txt being the permanent answer.

Why keep this in the scorecard

At a14y we score sites on agent-readability, and llms.txt is part of that score. This research does not weaken that, it sharpens it. A high score means your site is ready to be read cheaply by an agent. Whether a given agent takes you up on it depends on how that agent was built or prompted, which is exactly the variable we just isolated. We would rather tell you both sides than sell you one.

If you want to see the gap for yourself, run a14y against your docs, then point your own agent at the llms.txt we find (or flag as missing) and watch the token count. That is the experiment that convinced us, and it takes about ten minutes. We would genuinely like to see your numbers, especially if you can get any agent to adopt llms.txt from a page-side link alone.

Caveats

Where to read these numbers with care.

Small n, one setting. Five reps per arm (adoption is a low-frequency, near-binary event), a single retrieval prompt, a single model (Claude 2.1.141), and a single site. Treat the adoption pattern as directional, not the last word.
One site’s content. Every arm serves the same a14y.dev content; only the linking changes. And because a14y.dev documents its own discovery checks, it is a friendly case for content-based discovery. The relative ordering should generalize; the absolute numbers are tied to this content.
A snapshot of a moving target. Agent behavior and vendor support change fast. The “no public statement” list and the “no agent fetches by default” finding are true as of mid-2026 and worth re-checking over time.

Method notes

The page-side and nudge figures are from the a14y benchmark llms-txt-linking-2026-06-27 (Claude 2.1.141, isolated Docker, n=5 per arm), with adoption read from the static server’s request log filtered to the agent container’s IP. The ~2x figure is from the earlier discovery-layer case study. The agent reached our test build via in-container HTTP, so it received the full page including the head tags and chose not to act on them. External claims are linked inline. Full data and the reproducible harness live in the a14y benchmark repo.

Reproduce this study

Which agent-readiness features actually pay off

2026-06-25T00:00:00+00:00

Cross-posted from a14y.dev

Summary

Ship a markdown mirror and a real meta description first. Skip the agent-skills directory for now.

We took a14y.dev, toggled each of its 11 agent-readiness features on and off, and measured what each one is worth to an AI agent doing a real retrieval task. For Claude, the full discovery layer cuts token use about 47%, and a markdown mirror alone does most of that. But the features do not simply add up: some substitute for each other, one (the agent-skills directory) actively makes things worse, and a judge re-grade found the answers stayed exactly as accurate. The features make the agent faster and more efficient, not smarter. We ran the same probe through Codex and Cursor too, but only Claude’s runs were cleanly instrumented enough to quantify, which is a finding in itself (more on that below).

Metric	Result
Full layer (Claude)	−47% tokens
Best single feature	−48.6% (md-mirrors)
Answer quality	flat, ~75/100 across all variants

The question

The a14y scorecard rewards a long list of agent-readiness features. A fair question for any site owner with finite time: which of them actually pay off, and do they stack or just overlap? So we ablated them. Starting from a stripped site, we added each feature alone to see what it buys (call it sparse). Then, starting from a fully featured site, we removed each feature one at a time to see what it costs (dense). The gap between those two numbers is where the interesting behavior lives.

One caveat belongs up front, not in a footnote: this is a black box, and it is moving fast. None of these signals is a ratified web standard. llms.txt, for instance, is a good idea, not a spec, and it does not look like most agents go hunting for it on their own. But if an agent does encounter it, because you linked it, referenced it in robots.txt, or told the agent to look, it can help a lot. So read these results as a snapshot of how today’s agents behave with today’s signals, not as laws of nature. They will shift as the agents do.

Methodology

A focused retrieval probe run against 24 builds of the same site, each exposing a different subset of a14y’s features, across three coding agents.

Field	Value
Probe	5 fact-retrieval questions about a14y.dev (a scorecard version, specific check IDs, a threshold). The site’s discovery structure decides how much the agent has to crawl to answer.
Features	11 toggles: `llms-txt`, `robots-txt`, `sitemap-xml`, `sitemap-md`, `agents-md`, `agent-skills`, `md-mirrors`, `canonical-link`, `meta-description`, `og-tags`, `json-ld`
Variants	`baseline` (all off), `only-X` (each feature alone), `all-except-X` (each removed from full), and `all` = 24 builds
Sparse vs dense	Sparse = `only-X` vs baseline (what a feature buys from zero). Dense = `all-except-X` vs all (what removing it costs from a full site).
Runs	24 variants × 3 repeats = 72 runs
Agents	Claude Code, Codex CLI, Cursor, and Gemini. Only Claude is reported (see Why this is Claude only).
Metrics	Tokens per run (efficiency) and a judge re-grade of answer quality against canonical answers (effectiveness)
Date	June 4, 2026

The matrix below is Claude. We also ran Codex and Cursor, but only Claude’s runs could be cleanly tied to the build we served, so every number on this page is Claude’s. The “Why this is Claude only” section explains what went wrong with the other two.

What each feature is worth (Claude)

Token change for each feature, alone and removed-from-full. Negative is fewer tokens. The full layer saves 47%, but markdown mirrors alone save 48.6%, so the discovery features hit diminishing returns fast.

Feature	Alone	Removed	Reading
`md-mirrors`	-48.6%	+10.3%	Biggest win alone; partly substitutable in a full site
`agents-md`	-45.5%	-1.9%	Huge alone, redundant once llms.txt + mirrors exist
`meta-description`	-43.0%	+43.3%	Irreplaceable; nothing else substitutes for it
`canonical-link`	-40.4%	+13.0%	Moderate marginal value
`og-tags`	-40.0%	+13.2%	Moderate marginal value
`agent-skills`	-35.1%	-7.8%	Helps alone, distracts when stacked
`llms-txt`	-31.6%	+25.4%	Meaningful marginal value
`sitemap-md`	-28.6%	+12.2%	Moderate marginal value
`robots-txt`	-25.7%	+23.7%	Meaningful marginal value
`json-ld`	-25.3%	+6.5%	Small marginal value
`sitemap-xml`	-16.3%	+3.8%	Smallest effect

“Alone” is the feature added to a stripped site (sparse). “Removed” is the feature taken out of a full site (dense). A negative number for the Alone column means fewer tokens required with the feature. A positive number in the Removed column means more tokens required without the feature. A negative number in the Removed column means more tokens required with the feature.

Four findings

Markdown mirrors are the biggest single win

Alone, a markdown mirror cuts Claude’s tokens 48.6%, more than any other feature and more than the full layer combined. But remove it from a full site and the cost is only 10.3%, because llms.txt, sitemap.md, and a meta description can partly cover for it. Starting from zero, though, a mirror is the highest-impact thing you can ship.

A meta description is uniquely irreplaceable

It cuts 43.0% alone and costs 43.3% to remove. Nothing else in the matrix is that symmetric. Every other feature substitutes for something; the meta description does a job none of the others can. The likely reason: it short-circuits the “what is this page even about” step an agent does early in its navigation. Surfacing that one line cheaply seems to matter more than any amount of structured discovery.

AGENTS.md is redundant once you have the basics

Alone it is huge (−45.5%), but removing it from a full site costs nothing (−1.9%, within noise). The combination of llms.txt and markdown mirrors already carries the information it would. So AGENTS.md is a fine choice if it is the easiest file for you to maintain, but it is not pulling independent weight when the rest of the layer is present.

The agent-skills directory is actively distracting

It helps a little alone (−35.1%), but in a full site, removing it makes Claude faster (−7.8%). The .well-known/agent-skills/ index appears to pull Claude into a wrong-direction exploration when other signals are already present. It is the only clear “stop doing this” in the study, small in absolute tokens but consistent.

Faster and more efficient, not smarter

Efficiency is only half the question. We re-graded every answer with a judge against the canonical answers. Claude’s answer quality is essentially flat at about 75 of 100 across all 24 variants, while token use swings 2×. The discovery layer makes Claude reach the answer with less work; it does not change whether the answer is right. That is the clean version of the win: the same answers, reached with far less effort.

The re-grade also corrected the record. Our first pass used a strict substring rubric, and one question’s canonical answer (“5%”) matched inside a wrong answer (“15%”), so every agent “passed” a question they all actually got wrong. The judge caught it. Pass-rate numbers from the first draft were inflated by that bug; the quality figures here come from the re-grade.

Why this is Claude only

We initially did this audit with four agents: Claude, Codex, Cursor, and Gemini. However, today’s agent CLIs are still hard to benchmark in a controlled way, and so only Claude could be measured cleanly.

Codex calls a hosted web_search tool that cannot be turned off, so it reaches the open web (the live a14y.dev included), not just the controlled build. Its token counts measure that off-target exploration, not the variant in front of it. Cursor, in headless mode, does not surface its fetches at all, so we have no record of what it actually read; its answers looked reasonable, but we cannot attribute its cost to any one feature. Gemini’s CLI could not fetch our target and was dropped.

That left Claude as the only agent whose runs we can tie to the exact build it was given, which is why every number on this page is Claude’s. The finding underneath stands on its own: agents differ a great deal in how they read a site, and the tooling to measure them rigorously is still catching up. We will fold other agents back in as their CLIs expose what they fetch. The caveats below list the specific instrumentation gaps.

What to ship

For site owners

Assuming Claude-class agents are your main readers: ship a markdown mirror first, it is the largest win and the hardest to substitute. Always include a meta description; it is cheap and uniquely irreplaceable. Add llms.txt and sitemap.md as a pair (they back each other up). Treat AGENTS.md as optional once you have mirrors and llms.txt. And skip .well-known/agent-skills/ unless you have a specific reason to publish skills.

For agent and model builders

A discovery file can be read as a jump list or as a reading list, and those have very different cost profiles for the same content (we saw both behaviors across the agents we ran). The outsized pull of the meta description suggests agents spend real effort early on “what is this page about”; surfacing that cheaply may matter more than richer discovery. And the agent-skills directory needs clearer semantics: more than one agent failed to benefit from it, and Claude was slowed by it.

For everyone, while this is still a black box

These are not standards, and the agents are changing under us. Linking your agent files so they get found matters as much as having them. The safe bets are the ones that held across agents and map to plain readability: a clean mirror and a real description. We will re-run this as the agents evolve.

Caveats

Where to read these numbers with care.

One task. A 5-question retrieval probe. Long-form summarization, code generation, or multi-hop reasoning could rank the features very differently. The defensible generalization is “for focused retrieval.”
One site. Every variant serves the same a14y.dev content; only the discovery scaffolding changes. Whether the deltas hold on other sites is untested.
Only Claude is reported. We ran Codex and Cursor too, but Codex’s hosted web_search cannot be disabled and reaches the open web, and Cursor’s headless mode does not surface its fetches, so neither could be cleanly tied to the served build. Gemini was dropped (its CLI could not fetch). See “Why this is Claude only.”
Rubric bug. The original strict-substring rubric scored a universally-wrong question as passing (“5%” inside “15%”). Quality figures here use the judge re-grade; the first-draft pass rates were inflated.
Mirror quality is a lower bound. The mirrors used v0.2.0-style output. v0.3.0-draft tightens mirror checks, so a fully compliant mirror could save more than 48.6%.

Reproduce this study

The State of Agent Readability on the Web

2026-06-25T00:00:00+00:00

Cross-posted from a14y.dev

Summary

On most of the popular web, an AI agent burns roughly twice the tokens it should.

We scored the 50,074 most-visited websites for how well an agent can discover, parse, and comprehend them. The plumbing search engines asked for is everywhere: 88% expose a robots.txt. The layer agents need is not. Only 27% ship an llms.txt and 25% an AGENTS.md. The median site scores 52/100, and not one of the 50,074 scored “excellent.” Raising a site’s a14y score roughly halves the tokens an agent spends to use it. The web is wide open for improvement and very few have moved.

Metric	Result
Sites scored	50,074
Median score	52 / 100
Scored “excellent”	none (best is 83)
llms.txt	27%
AGENTS.md	25%

The question

AI agents are becoming a primary way people reach the web. They read sites, follow links, and synthesize answers on someone’s behalf. That raises a concrete question for every site owner: can an agent use my site efficiently? The a14y scorecard answers it for one site. We ran it across the web at scale to ask the bigger version: is the web ready for agents?

“Ready” here is mechanical, not subjective. Does the site expose what an agent needs to find and parse it: a usable llms.txt, an AGENTS.md, a sitemap, clean robots rules, semantic HTML, all measured by the v0.2.0 scorecard’s checks. It does not judge the quality of the content itself.

Methodology

A single point-in-time scan of the CrUX most-visited list, scored in page mode against the published scorecard. Run on cloud infrastructure, off any residential IP.

Field	Value
Source	CrUX top-100k most-visited origins (zakird/crux-top-lists, global)
Sample	50,074 scored: 100,000 rows → 64,746 after dedup to one per registrable domain → 50,074 reachable & not adult/gambling/spam
Mode	Page mode: each site’s homepage, not a full-site crawl
Scorecard	Published `v0.2.0` (38 checks) and the in-flight `v0.3.0-draft` (45 checks), scored 0–100. Headline scores use v0.2.0; the analysis below draws on both, tagged.
Tool	`npx a14y` (the same audit anyone can run)
Infra	Sharded across 64 Cloud Run tasks; run data archived in object storage
Source label	`crux batch-2026-06-15-100k`
Date	June 18, 2026

Page mode is deliberate. Scoring one homepage per site keeps a survey this size tractable and comparable. It proxies a site’s agent readiness; it does not capture readiness that lives deeper in the site.

Results: the web scores low

Distribution of agent-readability scores across all 50,074 sites. Mean 50.5, median 52.

Band	Sites	Share
Excellent (85–100)	0	0%
Good (70–84)	1,678	3.4%
Fair (50–69)	26,530	53%
Poor (0–49)	21,866	43.7%

The popular web clusters in the middle and below. 43.7% of sites score under 50, and only 3.4% clear 70. Not one site in the top 50,074 scored “excellent” (85 or above); the single best managed 83. Whatever the web was optimized for, it wasn’t agents.

Explore all 50,074 sites on the web leaderboard →

Results: the agent-era layer is missing

What the most-visited sites actually expose to agents, against the published v0.2.0 scorecard and the in-flight v0.3.0-draft.

The signals search engines taught the web to ship are nearly everywhere: 87% expose a robots.txt and 63% a sitemap. But only 78% actually let the major AI crawlers in, so close to a fifth of the most-visited sites block them outright.

The signals agents need are not just rare, they are often a mirage. 29% ship an llms.txt, and most are real (97% are non-empty). The other agent files mostly answer with a 200 but not a usable document: 30% appear to have an AGENTS.md while only 0.2% carry the expected sections, and 24% answer at /sitemap.md while only 0.1% are a real structured sitemap.

The markdown mirror tells the same story, and the draft scorecard makes it sharper. 27% advertise one, but under v0.3.0-draft only 1.8% of those mirrors are actually markdown rather than HTML. And the page itself often needs a browser to read: v0.3.0-draft finds 74% serve real homepage content in the initial HTML, which leaves about a quarter as JavaScript shells that agents without a JS engine (Claude, Perplexity, OpenAI’s SearchBot) see as blank.

Signal	Sites	What’s behind the number	From
robots.txt allows AI bots	78%	22% block GPTBot, ClaudeBot, CCBot, or Google-Extended	`v0.2.0`
llms.txt	29%	97% of them are non-empty, a real file	`v0.2.0`
AGENTS.md	30%	only 0.2% carry the expected sections	`v0.2.0`
sitemap.md	24%	only 0.1% are a real structured sitemap	`v0.2.0`
Markdown mirror advertised	27%	4% serve it on request via content negotiation	`v0.2.0`
Mirror is valid markdown	1.8%	of advertised mirrors are actually markdown, not HTML	`v0.3.0-draft`
Homepage server-renders content	74%	26% are JavaScript shells, invisible to agents that don’t run JS	`v0.3.0-draft`
No consent interstitial	93%	7% gate content behind a wall an agent can’t click	`v0.3.0-draft`
JSON-LD structured data	37%	6% include a dateModified	`v0.2.0`
Glossary link	0.5%	effectively nobody	`v0.2.0`

Full reference: every check, by theme

The Ghost of PageRank: AI Spam Will Backfire

2026-05-26T00:00:00+00:00

In the early days of search, the people who built and tuned websites were called webmasters, and a good number of them spent their time trying to trick the crawler. This started before Google. On engines like AltaVista, Lycos, and Excite, which leaned heavily on on-page text, the moves were crude: stuff a meta tag with repeated keywords, hide white text on a white background, climb the rankings. Reverse-engineering the algorithm to beat it was the game from the very beginning.

Google arrived in 1998 with a better idea. PageRank treated an inbound link as a vote of confidence, on the assumption that a genuinely useful page would accumulate more high-quality citations over time than a thin one. But the core mechanics were published in an academic paper, so they were never a secret. If links were votes, you just needed more votes. Webmasters figured that out immediately and built the machinery to manufacture them: automated link farms, guestbook spam, Google bombing. None of it waited for permission, and none of it waited for tools. By the early 2000s it was a full shadow economy.

Google’s first real answer, came in November 2003 when the “Florida” update wiped out a swath of sites built on spam tactics, right before the holiday shopping season. The message was clear: game the algorithm and you could lose your rankings overnight. The tools came afterward, as a kind of peace offering. Google Sitemaps launched in 2005 (renamed Webmaster Tools in 2006, eventually Search Console) and finally gave webmasters a legitimate channel to see crawl errors, submit URLs, and understand how the bot actually saw their site. Google paired it with guidelines that named the bad behaviors plainly, link schemes, keyword stuffing, cloaking, doorway pages, and over time made the consequences explicit: these tactics wouldn’t merely fail to help, they would actively lower your rank, and a Manual Actions report would tell you for certain whether you’d been hit. The whole shadow economy of link farms slowly turned from an edge into a liability.

Now fast-forward to today, because the same arc is repeating against a new target, and how it ended last time tells you what to actually do now.

People have figured out that models are trained on, and increasingly retrieve from, what’s available on the web. So picture a model asked for an infrastructure recommendation. It has absorbed a lot of “top 10 best tools for X” content. The gameable insight writes itself: produce a pile of those lists, make sure your company always lands at or near the top, and seed them everywhere a crawler might look. It’s PageRank’s link farm, reincarnated. Same move, new target.

This is the “get rich quick” side of AEO (agent/answer engine optimization), or GEO (generative engine optimization). And the straight answer to “what are the model companies doing about it” is: it’s early, and it’s uneven. But it’s worth noting where Google has already landed, because they have been here before. In Google’s guide to optimizing for generative AI features, they tell site owners to ignore a set of AI-specific tactics, and one of the named tactics is pursuing inauthentic brand mentions. That is, in plain terms, the seeding-fake-top-10-lists move. Google is also explicit that, from their perspective, optimizing for generative AI search is still just SEO, and that commodity content (the generic “7 Tips for X” piece anyone could reproduce) doesn’t earn visibility.

There’s a complication this time that early SEO didn’t have, and it’s the one that should worry you most: it’s now trivially easy to generate the content. In the link-farm era you at least had to author pages. Today you get slop: AI-generated text, unreviewed, carrying no real signal, nothing new or unique. Hundreds of top 10 lists, your company conveniently at the top, published at an endpoint that nothing but a crawler will ever visit. The hope is that all the robots ingest it and none of the humans notice.

And right now, this appears to work.

Let’s be precise about why it works. It works only because the algorithms haven’t yet caught up to the opportunity to penalize it. That’s the entire reason. In SEO’s early years, manipulative tactics often worked for a while before Google caught on; today the opposite holds: sites caught in link schemes face swift algorithmic devaluation, and recovery can take months or years. When the AEO algorithms catch up, and they will, this content doesn’t just stop being evaluated favorably. It becomes the thing that gets you penalized.

So why does this matter, and what should you actually do?

I’m not going to moralize about whether generating slop to nudge recommendations is good or bad. Right now it’s a Wild West strategy, and that just is what it is. What I’ll say instead is the part that’s actually defensible: it is not a long-term strategy. It has a shelf life, and the shelf life is “until the algorithm notices.”

The long-term play is the same one it always was. Invest in the core principles and value of the business. Make your product genuinely, unmistakably great, for humans and for agents. Be the best, so that when someone asks a model for the best recommendation and the model is accurate, it arrives at you. Not because you gamed the retrieval layer, but because you are the answer.

This is not a new conclusion. It’s exactly where the SEO industry landed after a decade of penalties. There’s a real, useful technical checklist (make sure the search engine can crawl, read, and index your content properly), and that checklist is worth following. But it was never a substitute for having something worth indexing.

The AEO version is the same shape. Follow the technical checklist: make your site agent-readable, structured, clean, accessible. If it’s a mess for humans to navigate, it’ll be a mess for agents too, and there’s a fast-growing set of practices for getting this right (serve markdown, support .md endpoints, publish llms.txt and sitemap.md, expose search and MCP tools, the same agent-readability work I’ve written about before that you can audit and implement with the a14y scorecard and toolset. Then do the part that actually compounds: produce great content, build a great website, get referenced for real. Those moves are good for your customers, good for your business, and good for your discovery, all at once. Everything else is just borrowing visibility from a future penalty.

If you’re working through how your org should show up for agents, or wrestling with the strategy and governance questions underneath it, I’d love to learn more and discuss.

Raising an a14y score from 37 to 89 halved an AI agent’s token use

2026-05-16T00:00:00+00:00

Cross-posted from a14y.dev

Summary

Same docs, same answer quality, statistically indistinguishable judge scores. The only thing we changed was running an a14y audit and shipping the top fixes, bringing the site’s a14y score from 37 to 89. That roughly halved Claude’s token use and tool calls on the same evaluation task.

Metric	Result
a14y score	37 → 89
Tokens	−49%
Tool calls	−52%
Wall-clock	−30%
Judge score	tied (84 ± 3 vs 83 ± 5)

The question

Does raising an a14y score actually translate into AI agent efficiency? We took the same docs site, audited it at score 37 and again at score 89, and measured how much an AI agent had to do to produce the same evaluation against each version.

Note on the baseline: the same Astro project is served twice. The score-37 version has the five discovery files removed from public/; the score-89 version restores them. This isolates the audit signal from any other change. The two targets are otherwise identical content, same build, same day.

Methodology

Two targets, same prompt, same image digest, same day. Three reps per side. The judge is transcript-aware and grades 0–100.

Field	Value
Spec	`scorecard-eval` (sha256:f39a89c86c9b…)
Targets	a14y.dev (score 89) vs same site, no audit fixes (score 37)
a14y audit	Score 37 (baseline) → 89 (after fixes), scored with `npx a14y --mode site`
Rubric	judge · claude-sonnet-4-6 grader · ≥70 = pass
Agent	claude 2.1.143 (Claude Code)
Runtime	docker · `a14y/bench-claude:2.1.141-0.1.0`
Auth	login-volume · bench-claude-auth
Reps	3 per target
Date	2026-05-16

The prompt (verbatim)

Make your documentation readable by AI agents

2026-03-27T00:00:00+00:00

Cross-posted from Vercel KB

AI agents (Claude Code, ChatGPT, Cursor, Copilot) are a primary consumer of developer documentation. They don’t need navigation chrome, dark mode toggles, or animated code blocks. They need:

Discoverable content: Where the docs are and what they cover
Clean retrieval: Markdown, not a DOM tree
Structured metadata: Version, last updated, and canonical URL
Tool access: Search and fetch via protocol, not scraping

Most content platforms serve agents the same HTML page they serve humans. The agent then spends tokens stripping tags, guessing at content boundaries, and hoping the important information survives extraction. The result: hallucinated APIs, outdated code examples, and missed context.

Three layers of agent readiness

Agents interact with content in three layers. They discover what exists, retrieve clean content, optionally index at scale, and use tools for precision queries.

Layer 1: Discovery

Help agents find what exists before they fetch anything.

Requirement	Implementation	Purpose
`/llms.txt`	Curated markdown index at the site root with section headings and links	Entry point for agents and humans pasting docs into an IDE
`sitemap.xml`	Standard sitemap with accurate `lastmod` dates	Freshness tracking for agents that monitor content changes
`sitemap.md`	Semantic sitemap served as markdown with section headings, categories, and page descriptions	High-level orientation for LLM-assisted navigation and contributor onboarding
`robots.txt`	Documented stance on agent access (which bots can crawl, which pages are off-limits)	Crawl control and access transparency
JSON-LD structured data	Title, description, canonical URL, and breadcrumbs on every HTML page	Agents that parse HTML can understand page type and relationships without traversing the DOM

Example JSON-LD for a docs page:

{
  "@context": "",
  "@type": "TechArticle",
  "headline": "Vercel Functions",
  "description": "Deploy server-side code on Vercel.",
  "url": "",
  "breadcrumb": { "@type": "BreadcrumbList",
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "name": "Docs",
        "item": ""
      },
      {
        "@type": "ListItem",
        "position": 2,
        "name": "Functions",
        "item": ""
      }
    ]
  }
}

Layer 2: Retrieval

This is the highest-impact layer. When an agent fetches a docs page, it should get markdown, not HTML with embedded scripts.

Mechanism	How it works
Content negotiation	Agents that send `Accept: text/markdown` receive markdown with `Content-Type: text/markdown; charset=utf-8` and a `Vary: Accept` header. Claude Code sends this header natively.
Agent auto-rewrite	Detected AI agents receive markdown automatically, even without an `Accept: text/markdown` header. Detection uses user-agent matching, RFC 9421 Signature-Agent headers, and a heuristic fallback for unknown agents.
`.md` endpoints	Append `.md` to any docs URL to get the markdown version directly. Works without custom headers. Useful for pasting docs into a chat or IDE.
Rich frontmatter	Every markdown response includes metadata for accurate citations.
HTML alternate link	Adding in the HTML tells agents a markdown version exists.

Example request and response:

curl -H "Accept: text/markdown"

---
title: Functions
description: Deploy server-side code on Vercel.
canonical_url: 
md_url: 
last_updated: 2026-01-15T12:34:56.000Z
---

# Functions

Deploy server-side code on Vercel...

Without canonical_url and last_updated, agents can’t link back to the source or judge whether their information is stale.

The Vary: Accept header tells CDNs to cache HTML and markdown responses separately for the same URL. Without it, an agent’s markdown response could be served to a browser, or vice versa.

Always serve markdown to agents

Content negotiation and .md endpoints cover agents that explicitly request markdown. Many agents don’t. They send a standard GET with no special headers. If your platform can detect that the request comes from an AI agent, serve markdown anyway.

Vercel uses a three-layer detection approach:

User-agent matching: Check against a maintained list of known AI agent strings (Claude, ChatGPT, GPTBot, Cursor, Copilot, and others). This is the most reliable signal.
Signature-Agent header: The RFC 9421 standard header, used by ChatGPT’s agent. Validate against known AI service domains.
Heuristic fallback: If the request is missing the sec-fetch-mode header (which real browsers always send) and the user-agent matches a bot-like pattern, treat it as an agent. This catches unknown agents at the cost of occasional false positives, which are low-harm since serving markdown to a non-AI bot has no negative effect.

This means agents get markdown on every valid docs request, regardless of how they make it.

Handle 404s with markdown, not HTML

When an agent requests a page that doesn’t exist, an HTML 404 page is useless. The agent can’t parse it, and the conversation stalls. Instead, return a markdown response with actionable content:

Search your docs index for pages similar to the requested path.
If a result scores above a high-confidence threshold (0.99+), redirect the agent to the correct page.
Otherwise, return markdown-formatted suggestions listing the closest matches as links.
Return a 200 status, not 404. Agents need content they can act on.
Append a sitemap footer to every markdown response so agents can browse the full index if they hit a dead end.

Layer 3: Tool access

The most sophisticated agents don’t scrape at all. They call tools.

Tool	Description
MCP servers	Search docs, fetch specific pages, and list available content through a standard protocol. The Vercel MCP server covers `vercel.com/docs`, `nextjs.org`, and the AI SDK docs.
Search APIs	Return structured JSON results with canonical URLs, snippets, and freshness metadata.
AI Chat	Conversational interface on docs sites backed by doc-aware tools: `search_docs`, `get_doc_page`, and `list_docs`. Available to both humans and agents.

Checklist

For the full scoring rubric (0–100) and detailed verification steps, see the Agent-Readability Spec.

Discovery

Serve /llms.txt with a curated H1 + H2 index of your content
Publish sitemap.xml with accurate lastmod dates
Serve /sitemap.md with a semantic, markdown-formatted sitemap describing docs sections and pages
Document agent access policy in robots.txt
Add JSON-LD structured data (title, description, canonical URL, and breadcrumbs) to every page

Retrieval

Return markdown for Accept: text/markdown with a Vary: Accept header
Generate .md endpoints for all content pages
Include frontmatter metadata (title, canonical_url, last_updated) in every markdown response
Add to HTML pages
Detect AI agents (user-agent matching, Signature-Agent header, heuristic fallback) and serve markdown automatically
Verify by appending .md to any page URL and confirming you get clean markdown with frontmatter

Tool access

Expose search via MCP server or search API
Add a SKILLS.md or AGENTS.md file with install, config, and usage instructions for coding agents

To get started, run through the checklist above, then score your site against the Agent-Readability Spec.

Agent Readability: A Specification for AI-Optimized Websites

2026-03-23T00:00:00+00:00

Cross-posted from Vercel KB

AI agents — tools like ChatGPT, Claude, Copilot, and Cursor — are becoming a primary way people discover and consume web content.

Agent readability is a set of best practices that make your website accessible to AI agents and assistants. It covers three areas:

Discovery — Can agents find your pages? (llms.txt, sitemaps, robots.txt)
Structure — Can agents parse your pages? (meta tags, headings, structured data, markdown mirrors)
Context — Can agents understand your content? (skill files, content negotiation, code documentation)

This guide describes what to implement, why it matters, and how to verify each requirement.

Quick-Start Checklist

Site-Level Files

Serve an llms.txt file at your site root
Allow AI bots in robots.txt
Publish a sitemap.xml with dates
Publish a sitemap.md with headings and links
Create an AGENTS.md with install, config, and usage sections
Ensure all pages are discoverable from at least one source

Page-Level HTML

Return HTTP 200 with 0–1 redirects
Set correct Content-Type headers
Do not set restrictive x-robots-tag values
Include a tag
Add meta description (50+ characters), og:title, og:description, and html lang
Add Schema.org / JSON-LD structured data
Use 3+ section headings (h1–h3) per page
Maintain a text-to-HTML ratio above 15%
Include a glossary or terminology link

Server Configuration

Provide markdown mirrors for HTML pages
Add to HTML pages
Return Link header with rel="canonical" from markdown endpoints
Support Accept: text/markdown content negotiation
Include a ## Sitemap section in markdown pages

Content Quality

Fence all code blocks with language identifiers
Link to OpenAPI/Swagger schemas from API reference pages

Scoring

Your agent readability score measures how well your site meets these requirements:

score = round((passed checks / total checks) x 100)

Only checks with a pass status count toward the numerator. Checks that fail, warn, or error do not.

The total is the sum of all site-wide checks plus all per-page checks across every discovered page. Because per-page checks run on every page, sites with many pages have a larger denominator — a single failing check matters less on a large site, but a systemic issue (such as missing canonical links on every page) compounds significantly.

Score	Rating	Meaning
90–100	Excellent	Highly optimized for AI agents. All critical checks pass.
70–89	Good	Meets most requirements. Address warnings to improve.
50–69	Fair	Has gaps. Review failed checks and implement fixes.
0–49	Needs Improvement	Significant work needed across multiple areas.

Site-Level Requirements

These requirements apply once per site, at the root level.

llms.txt

What: Serve an llms.txt file that lists your documentation pages. This is the primary entry point for AI agents discovering your content.

Why: AI agents look for llms.txt as a machine-readable index of your site’s content, similar to how search engines use sitemap.xml. Without it, agents must crawl your site to find pages, which is slower and less reliable.

Requirements:

Serve the file at one of: /llms.txt, /.well-known/llms.txt, or /docs/llms.txt
Alternatively, serve llms-full.txt at the same paths
Use text/plain as the Content-Type
The file must not be empty
Listed URLs should use .md or .mdx extensions, not .html

Example:

# Example Product Documentation

## Getting Started
- [Installation](/docs/installation.md)
- [Quick Start](/docs/quick-start.md)
- [Configuration](/docs/configuration.md)

## API Reference
- [Authentication](/docs/api/auth.md)
- [Endpoints](/docs/api/endpoints.md)
- [Error Handling](/docs/api/errors.md)

## Guides
- [Deployment](/docs/guides/deployment.md)
- [Monitoring](/docs/guides/monitoring.md)

How to verify:

curl -I 
# Should return 200 with Content-Type: text/plain

robots.txt

What: Ensure your robots.txt does not block known AI bots.

Why: AI agents respect robots.txt directives. If you block them, your content will not be indexed or cited by AI assistants.

Requirements:

Do not block GPTBot, ClaudeBot, CCBot, or Google-Extended
Do not disallow /llms.txt
Having no robots.txt at all triggers a warning — it is better to explicitly allow access

Example:

User-agent: *
Allow: /

User-agent: GPTBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: CCBot
Allow: /

User-agent: Google-Extended
Allow: /

Sitemap: 

How to verify:

curl 
# Inspect output for Disallow rules targeting AI bots or /llms.txt

Sitemap (XML and Markdown)

What: Publish both a sitemap.xml and a sitemap.md to help agents understand your site structure.

Why: XML sitemaps are the standard for search engine crawlers. Markdown sitemaps give AI agents a structured, readable overview of your documentation hierarchy. Publishing both maximizes discoverability.

Requirements for sitemap.xml:

Serve a valid XML sitemap with or containing entries
Include dates so agents know which pages have changed

Requirements for sitemap.md:

Serve at one of: /sitemap.md, /docs/sitemap.md, or /.well-known/sitemap.md
Include headings and links that reflect your site’s structure

Example sitemap.md:

# Sitemap

## Getting Started
- [Installation](/docs/installation.md)
- [Quick Start](/docs/quick-start.md)

## API Reference
- [Authentication](/docs/api/auth.md)
- [Endpoints](/docs/api/endpoints.md)

## Guides
- [Deployment](/docs/guides/deployment.md)
- [Monitoring](/docs/guides/monitoring.md)

How to verify:

curl  | head -20
# Should contain  with  and  entries

curl 
# Should return structured markdown with headings and links

Skill File (AGENTS.md)

What: Create an AGENTS.md file that gives coding agents direct context about your product — how to install it, configure it, and use it.

Why: Coding agents like Copilot, Claude Code, and Cursor use skill files to understand how to work with your product. A well-written skill file means agents can generate correct code for your users without guessing.

Requirements:

Serve the file at one of: /AGENTS.md, /agents.md, /.well-known/agents.md, /docs/AGENTS.md, /llms-full.txt, /CLAUDE.md, /.cursor/rules, or /.cursorrules
Include at least 2 of the following sections: installation instructions, configuration details, usage examples or code blocks

Example AGENTS.md:

# My Product

## Installation

```bash
npm install my-product
```

Configuration

Create a my-product.config.ts file in your project root:

import { defineConfig } from 'my-product';
export default defineConfig({
  apiKey: process.env.MY_PRODUCT_API_KEY,
  region: 'us-east-1',
});

Usage

import { createClient } from 'my-product';

const client = createClient();
const result = await client.query('SELECT * FROM users');
console.log(result.rows);

How to verify:

curl 
# Should return markdown with install, config, and/or usage sections

Page Discoverability

What: Ensure every page on your site is reachable from at least one discovery source.

Why: Pages that are not linked from sitemap.xml, llms.txt, sitemap.md, or other pages cannot be found by agents. Orphaned pages are invisible to AI.

Requirements:

Every page should appear in at least one of: sitemap.xml, llms.txt, sitemap.md, or be reachable via links from other discoverable pages

How to verify: Cross-reference your page count against the URLs listed in your sitemaps and llms.txt. Any page not present in any source is undiscoverable to agents.

Page-Level Requirements

These requirements apply to every page on your site.

HTTP Response Basics

What: Ensure pages return clean HTTP responses that agents can process without issues.

Why: Agents follow redirects and inspect headers to decide whether to index a page. Broken responses, long redirect chains, or restrictive headers cause agents to skip your content.

Requirements:

Return HTTP 200 for all live pages
Limit redirect chains to 0–1 hops (2+ redirects cause failures)
Set the correct Content-Type header:
- HTML pages: text/html;charset=UTF-8
- Markdown pages: text/plain;charset=UTF-8
Do not include noindex, noai, or noimageai in the x-robots-tag response header

How to verify:

curl -I -L 
# Check: HTTP status is 200, no more than 1 redirect, correct Content-Type
# Check: x-robots-tag does not contain noindex, noai, or noimageai

HTML Meta and Structure

What: Include proper metadata, structured data, and heading hierarchy so agents can understand each page’s content and context.

Why: Meta tags tell agents what a page is about before they read the full content. Schema.org structured data provides machine-readable context like authorship, dates, and breadcrumbs. Headings create a scannable structure that agents use to extract sections relevant to a user’s query. A high text-to-HTML ratio ensures the page contains real content rather than framework boilerplate.

Requirements:

Canonical link

Include on every page to tell agents which URL is authoritative.

Meta tags

Include all of the following:

(at least 50 characters)
lang attribute on the element

Schema.org / JSON-LD

Include a

Section headings

Use 3 or more headings (h1–h3) per page to create a clear structure. Well-structured pages produce better embeddings and allow agents to extract specific sections.

Signal-to-noise ratio

Maintain a text-to-HTML ratio above 15%. Pages dominated by JavaScript bundles, framework boilerplate, or empty wrappers are harder for agents to parse.

Glossary link

Include a link to a glossary or terminology page. This helps agents resolve ambiguous terms in your content.

How to verify:

curl -s  | grep -E 'canonical|og:title|og:description|ld\\\\+json|
# Each should return a match

Markdown Mirrors and Content Negotiation

What: Provide markdown versions of your HTML pages and support content negotiation so agents can request the format they prefer.

Why: AI agents work natively with markdown. Raw HTML requires parsing and stripping away navigation, headers, footers, and scripts. A markdown mirror gives agents clean, structured content they can process directly — resulting in more accurate citations and better answers.

Requirements:

Markdown mirrors — For every HTML page, provide a corresponding .md or .mdx version. Include frontmatter metadata:

---
title: Getting Started
description: Learn how to install and configure My Product
doc_version: "2.1"
last_updated: "2025-01-15"
---

Alternate link in HTML — Add a tag pointing to the markdown version:

 rel="alternate" type="text/markdown" href="/docs/getting-started.md">

Canonical link in markdown responses — When serving markdown files, include a Link HTTP header:

Link: ; rel="canonical"

Content negotiation — Return markdown when the client sends an Accept: text/markdown header:

curl -H "Accept: text/markdown" 
# Should return markdown content with Content-Type: text/markdown

Sitemap section — Include a ## Sitemap heading in each markdown page with a link to /sitemap.md:

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.

How to verify:

# Check alternate link
curl -s  | grep 'rel="alternate".*text/markdown'

# Check content negotiation
curl -H "Accept: text/markdown" -I 
# Content-Type should be text/markdown

# Check markdown mirror directly
curl 
# Should return markdown with frontmatter

Code and API Documentation

What: Fence all code blocks with language identifiers and link to machine-readable API schemas.

Why: Language-tagged code blocks let agents generate syntactically correct examples. API schema links (OpenAPI, Swagger) give agents the full contract of your API, enabling them to write integration code without guessing endpoints or parameters.

Requirements:

Code blocks

Every

 block should have a language-* or lang-* class:


 class="language-typescript">
const client = createClient();




const client = createClient();



In markdown, always specify the language after the opening fence:

```typescript
const client = createClient();
```


Open API schema

API schema links
— On pages with API documentation (URLs containing /api/, /reference/, /endpoints/, /swagger/, or /openapi/), include links to your machine-readable schema files (openapi.json, swagger.json, swagger.yaml, or schema.json).

How to verify:
# Check code blocks have language classes
curl -s  | grep -E '# Check API schema links
curl -s  | grep -E 'openapi\\\\.json|swagger\\\\.(json|yaml)|schema\\\\.json'




Optional: AI Text Style Analysis

For technical documentation sites, an AI-powered analysis can evaluate your content against documentation best practices:


  
    Voice and tone — Is the writing clear, direct, and consistent?
  
  
    Formatting — Are lists, tables, and code examples used effectively?
  
  
    Examples — Does the documentation include runnable code samples?
  
  
    Units and precision — Are measurements, limits, and thresholds clearly stated?
  
  
    Pricing clarity — If applicable, is pricing information unambiguous?
  


This analysis is opt-in and requires an AI model to evaluate your content. It is most useful for sites with extensive technical documentation where writing quality directly impacts whether agents can extract accurate information.



Further Reading


  
    llms.txt specification — The standard for providing LLM-readable content
  
  
    Schema.org documentation — Structured data vocabulary for the web
  
  
    OpenAPI specification — Machine-readable API documentation standard
  
  
    robots.txt specification — The standard for web crawler access control



Building Slack agents can be easy
2026-03-03T00:00:00+00:00
Cross-posted from vercel.com/blog

Slack is already where teams work. It provides a natural interface for agents, with messages, threads, buttons, and events, so you don’t need to invent a new UI or onboarding flow. Getting from “I want a Slack agent” to a running deployment, though, means coordinating across a lot of systems:


  Creating an app in the Slack API console
  Configuring OAuth scopes and event subscriptions
  Writing webhook handlers and signature verification
  Deploying to infrastructure that can handle Slack’s 3-second response window


Each piece has its own docs, and they all need to work together.

Coding agents like Claude Code, OpenCode, Cursor, and GitHub Copilot are well suited for exactly this kind of coordination because they can read docs, reason through dependencies, and generate code in seconds. We built the Slack agent skill to take advantage of that. It builds on our Slack Agent Template, works with the coding agent of your choice, and takes you from idea to a deployed Slack agent on Vercel in a single session, automating steps when possible and showing you exactly what to click when it can’t.

From idea to deployed agent with the skill wizard

Install the skill and run the wizard:

npx skills add vercel-labs/slack-agent-skill


Then run the skill in your agent. For example, with Claude Code:

/slack-agent new


The wizard starts by asking what kind of agent you want to build. You might say “a support agent that answers questions from our internal docs,” or “a standup bot that collects updates from the team every morning.” Based on your answer, it generates a custom implementation plan tailored to your use case. You review and approve the plan before any code is written.

From there, you move through five stages:


  Project setup: You choose your LLM provider, and the agent scaffolds your project from our Slack Agent Template.
  Slack app creation: The agent customizes your manifest.json with your app name, description, and bot display settings, then opens Slack’s console and walks you through creating the app and installing it to your workspace. OAuth scopes, event subscriptions, and slash commands come pre-configured from the template.
  Environment configuration: The agent walks you through setting up your signing secret, bot token, and any API keys your project needs.
  Local testing: The agent starts your dev server and connects it to Slack so you can message your bot and see it respond in real time before anything touches production.
  Production deployment: The agent walks you through deploying to Vercel and setting up your environment variables. From this point, every git push triggers a new deployment.




What the skill gives you

The Slack agent skill gives you an agent that can:


  Hold multi-turn conversations across messages and threads
  Pause for human approval before taking sensitive actions
  Stream responses to Slack in real time
  Read channels and threads on its own


Your agent interacts with Slack and your systems through tools, functions it can call to take actions or retrieve information. The template ships with tools for:


  Reading channel messages
  Fetching thread context
  Joining channels (with human approval)
  Searching channels by name, topic, or purpose


You can also tell your coding agent to add custom tools that connect to your own systems. Want the agent to look up a customer record, create a support ticket, or query a database? Each of those becomes a tool the agent knows when and how to call.

import { tool } from "ai";
import { z } from "zod";
const lookupCustomer = tool({
  description: "Look up a customer record by email",
  inputSchema: z.object({
    email: z.string().describe("Customer email address"),
  }),
  execute: async ({ email }) => {
    "use step";
    const customer = await db.customers.findByEmail(email);
    return { success: true, customer };
  },
});


Workflow DevKit is what makes the agent durable. A Slack agent often needs to hold a conversation across many messages, or wait hours for someone to approve a request. Workflow DevKit lets the agent suspend mid-conversation, wait for external input, and pick back up exactly where it left off. Tool calls are automatically retried on failure, and responses stream back to Slack in real time.

Human-in-the-loop is built in. When the agent needs to perform a sensitive action like joining a channel, it posts a message with Approve and Reject buttons and suspends. You’re only billed for active CPU time, so waiting costs nothing, even if approval takes days. This pattern extends to any action requiring approval, from sending messages to modifying data to calling external APIs.

AI Gateway gives your agent access to hundreds of models from every major provider through a single API key. Switching models is a one-line change, and if a provider goes down, AI Gateway automatically routes to another so your agent stays up.

import { gateway } from "@ai-sdk/gateway";
const result = await generateText({
  model: gateway("anthropic/claude-sonnet-4.6"),
  prompt: userMessage,
});


Going deeper

Once your agent is live, there are a few ways to extend it and understand it better.

Our Vercel Academy Slack Agents course covers the entire lifecycle, from creating and configuring a Slack app to handling events and interactive messages, building agents with the AI SDK, and deploying to production.

Vercel preview deployments let you test changes before they reach production. For Slack bots, this may require bypassing deployment protection so Slack’s webhook verification can reach your endpoint. Our testing guide explains how to set this up.

Vercel Sandboxes let your agent execute code in isolated environments, so it can run user-provided scripts like analyzing a spreadsheet, generating a chart, or transforming data without risking your infrastructure.

Get started

The whole experience fits in one session with your coding agent.


  Slack Agent Skill
  Slack Agent Template
  Vercel Academy: Slack Agents



Hello, Vercel.
2025-11-03T00:00:00+00:00


I’ve redeployed timothyjordan.com to Vercel, and I’m super excited to lead the Developer Experience team at a company famous for excellent Developer Experience.


My exit from Google: we don’t say goodbye, we say good journey.
2025-10-25T00:00:00+00:00


Although I wasn’t searching for a new role, one found me, and after a long period of accumulating scope and responsibilities at Google, I’m excited to try something new.

I’m incredibly grateful for the 15.75 years I’ve had to work side-by-side with some of the most amazing engineers and storytellers I’ve ever met… and to do so on a global scale. I first learned about Developer Advocacy when I ran into Mano Marks at Google I/O in 2009. He had just returned from a talk at the UN, where he spoke about combating deforestation by empowering indigenous peoples with mapping platforms. I knew right away that it was my dream job, and I applied to Google.

I started as a Developer Advocate working on the social web. First there was Open Social, then Friend Connect, and Google Buzz. The +1 button was one of our first major launches leading up to Google+, and it ended up being on a shockingly high percentage of page loads on the Internet (the TL used to say, “it’s not just a f#$%ing button”). I changed teams to work on Google Glass and gave the first public demo of Glass alongside an introduction to our developer platform. That was probably the only time I’ll ever be the subject of a Saturday Night Live parody. After Glass, I helped evolve the DevRel structure at Google a few times. First leading a small team of DAs for “ubiquitous computing”, then all of Developer Advocacy and the Google Developer Studio, then a portfolio of DevRel teams. That portfolio of teams evolved over the years, and I had the privilege of starting full DevRel teams for Flutter, Firebase, TensorFlow, and evolving many others, such as Maps, Apps, Search, and Material. Later on, I was able to build Google’s first Internal DevRel team and take on responsibility for the Developer Ecosystem team and the Open Source Programs Office. Throughout all those years, I helped stretch Developer Relations at Google through projects like growing our online video presence, founding the annual internal DevRel Conference, coauthoring the Developer Relations Engineer role profile, evolving the Google I/O online experience and developer keynote, helping reinvent perf, and more recently helping evolve our craft in the age of AI. Together, we helped grow Google from a handful of platforms supporting consumer products to what it is today.

Here I am today, wondering how I was so fortunate to have worked on so many amazing technologies alongside so many extraordinary humans. Thank you to all my Google colleagues for everything you’ve taught me and all the crazy ideas we turned into the state of the DevRel art.

As for what’s next, well, that will have to be a different post.

Timothy Jordan

llms.txt saves an agent real tokens, but it won’t read it unless you ask

Summary

The payoff is real

But the agent won’t take the payoff on its own

This is not just a Claude quirk

What to actually do with this

Your own agents

Agentic tooling you can configure

Future-proofing at near-zero cost

Why keep this in the scorecard

Caveats

Method notes

Which agent-readiness features actually pay off

Summary

The question

Methodology

What each feature is worth (Claude)

Four findings

Markdown mirrors are the biggest single win

A meta description is uniquely irreplaceable

AGENTS.md is redundant once you have the basics

The agent-skills directory is actively distracting

Faster and more efficient, not smarter

Why this is Claude only

What to ship

For site owners

For agent and model builders

For everyone, while this is still a black box

Caveats

The State of Agent Readability on the Web

Summary

The question

Methodology

Results: the web scores low

Results: the agent-era layer is missing

The Ghost of PageRank: AI Spam Will Backfire

Raising an a14y score from 37 to 89 halved an AI agent’s token use

Summary

The question

Methodology

Make your documentation readable by AI agents

Three layers of agent readiness

Layer 1: Discovery

Layer 2: Retrieval

Always serve markdown to agents

Handle 404s with markdown, not HTML

Layer 3: Tool access

Checklist

Further reading

Agent Readability: A Specification for AI-Optimized Websites

Quick-Start Checklist

Site-Level Files

Page-Level HTML

Server Configuration

Content Quality

Scoring

Site-Level Requirements

llms.txt

robots.txt

Sitemap (XML and Markdown)

Skill File (AGENTS.md)

Configuration

Usage

Page Discoverability

Page-Level Requirements

HTTP Response Basics

HTML Meta and Structure

Canonical link

Meta tags

Schema.org / JSON-LD

Section headings

Signal-to-noise ratio

Glossary link

Markdown Mirrors and Content Negotiation

Code and API Documentation

Code blocks

Open API schema

Optional: AI Text Style Analysis

Further Reading