Every Website Should Have an llms.txt

I love llms.txt.

That may be an unreasonable amount of enthusiasm for a text file, but it solves a problem I run into constantly: websites are designed for people to browse, while agents need a fast way to find and consume the right information.

Those are not the same interface.

A person benefits from navigation, responsive layouts, interactive examples, search controls, and visual hierarchy. An agent often has to work backward through all of that presentation to recover the underlying knowledge. Every irrelevant menu item, repeated footer, script, and fragment of page chrome competes for a limited context window.

The llms.txt proposal offers a wonderfully simple alternative: put a concise Markdown directory at a predictable URL and use it to point language models toward clean, detailed Markdown resources.

I think every site with meaningful public information should have one.

The examples I reach for

I regularly use the llms.txt file from Vercel and the Convex documentation index when I am building with an agent.

They turn large documentation sites into navigable maps. Vercel organizes links across its platform and points to a full documentation context file. Convex groups its documentation by areas such as functions, database, authentication, and search, with short descriptions that help an agent choose the right page before reading it.

That choice matters.

Without a map, an agent may search broadly, open the wrong version of a page, infer behavior from an example, or spend several tool calls discovering where the authoritative answer lives. With a good llms.txt, I can direct it to one stable entry point and let it retrieve only the guidance relevant to the problem.

The improvement is not abstract. When I give an agent the right Vercel or Convex documentation, it catches mistakes I made and mistakes it was about to make. It can compare an implementation against current constraints instead of relying on a remembered API or a plausible pattern from its training data.

Proper guidance makes the agent better at its job.

Markdown is an efficiency feature

Markdown is not magical compression. A bad Markdown file can still be enormous, repetitive, and unhelpful. The real advantage is that it makes useful structure inexpensive.

Headings establish hierarchy. Links create an explicit retrieval path. Lists make options easy to scan. Code stays code. The content remains readable without reconstructing a page from a DOM, running client-side JavaScript, or separating the documentation from the interface around it.

For an agent, that can mean:

• fewer tokens spent on navigation and presentation;
• fewer searches and speculative page loads;
• more context-window space for the actual task;
• easier exact-text search across headings, APIs, and constraints; and
• a clearer path from a broad question to an authoritative source.

That efficiency affects cost, latency, and reliability at the same time. A cheaper agent run is useful, but the larger win is that fewer irrelevant tokens leave more room for the code, requirements, and decisions that actually matter.

The best llms.txt is therefore not a dump of everything on the site. It is a retrieval layer. It should help an agent decide what to read next.

My portfolio needed an agent interface

That idea became more interesting when I applied it to this portfolio.

The human version of the site is designed to be explored. It introduces who I am, shows selected work, explains how I think, traces my career, and includes longer-form writing. The layout and pacing are part of that experience.

But someone evaluating me with Claude, ChatGPT, Codex, or another agent may want something different. They may want to compare my experience with a job description, identify evidence for a particular skill, or ask where my background does and does not match a role.

Making an agent crawl the visual site or parse a PDF résumé is possible, but it is wasteful. The information already exists as structured content. I can give the agent a cleaner path.

My current approach uses three layers:

1. /llms.txt is the map. It describes the portfolio and links to the most useful agent-readable resources.
2. /resume.md is the focused candidate packet. It contains my professional summary, skills, experience, selected work, education, writing, and guidance for evaluating the evidence responsibly.
3. /llms-full.txt is the deep-context option. It combines the résumé with the full text of my published writing when the extra context is relevant.

This lets an agent start small and expand deliberately. A basic candidate assessment does not need every essay I have written. A question about how I approach documentation, design systems, or AI evaluation might.

That is the same principle behind a well-designed API: make the common path obvious, and make deeper capability available without forcing every consumer to pay for it.

resume.md is a convention, not a standard

I did not invent the idea of writing a résumé in Markdown, and resume.md is a natural filename that plenty of people have used. It is not, however, a formal résumé specification.

The shared convention I am following is the shape of llms.txt. The proposal defines a Markdown document with a title, an optional summary and guidance, and sections containing described links to other resources. It also recommends clean Markdown versions of useful pages and explicitly identifies personal sites answering questions about someone’s CV as a use case.

resume.md is my application of that pattern.

I like that balance. The predictable /llms.txt entry point supports discovery, while the resource behind it can be designed for the site’s actual purpose. A software framework needs API references and examples. A store might expose product and policy information. A university might expose courses and admissions guidance. A personal site can expose a focused professional record.

The filename is less important than the contract: concise, current, attributable information that an agent can retrieve without guessing.

This does not replace the website

An agent-readable layer should not become an excuse to neglect the human experience.

llms.txt does not replace accessible HTML, useful navigation, structured metadata, a sitemap, or a well-written page. It also does not guarantee that every model or crawler will discover and use it automatically. In many workflows, the user or agent still has to request the file explicitly.

It is also only as trustworthy as the content behind it. If the Markdown drifts from the product, omits important constraints, or points to stale pages, it gives an agent a faster route to the wrong answer.

The durable implementation is generated from the same sources as the website wherever possible. On this portfolio, the Markdown résumé and context files are built from the same typed profile, project, career, skills, and blog content that powers the human-facing pages. Updating the source updates both interfaces.

That matters more than the extension.

A small file can change the whole workflow

What excites me about llms.txt is how little machinery it requires.

There is no mandatory vector database, ingestion pipeline, embedding model, or proprietary protocol. A site can begin with one well-structured Markdown file, a handful of described links, and clean text versions of its most useful content.

That is enough to make an agent’s search space smaller and its source material better.

For me, the idea combines two things I care about: building with AI and making systems more efficient. I want agents to spend their context on the problem, not on reverse-engineering the website that explains it. I want the guidance that prevents a mistake to be easier to retrieve than the example that causes one. I want a candidate evaluation to use the actual evidence on my site without paying the token cost of scraping every page.

llms.txt is a small interface for that future.

Every site should have one.