Is a README for Humans or for LLMs?

A developer tested splitting a single README into a human-facing visible body and a folded `<details>` section of facts for LLMs, then published a repository to check whether AI assistants would read the folded content. All five AI assistants able to fetch the URL read the folded section, though the developer notes this remains a way of separating human and machine readers. The trial follows server-log evidence that llms.txt is rarely fetched, including an Ahrefs study of 137,000 domains where about 97% of published llms.txt files received zero requests during May 2026.

I read the README of one of my own repositories and stopped at the tenth sentence. I had written it with my README skill, and the pre-publication check had said it was fine to publish. It opened with a two-sentence paragraph meant to say what the project does translated from the Japanese README : An autonomous agent that runs on a local LLM and proposes changes to its own constitution and values. A human decides every time whether to adopt them. After those two sentences, I still didn't know what it was. Lately I've been thinking about how to fix the verbose prose LLMs write. I wrote this on X in Japanese : An LLM doesn't get what goes without saying between people. So it says things that don't need saying. To make up for that, defining who will read this may be what matters. But that's easy to say and very hard to do. An LLM doesn't stop reading halfway through a text. So it's better to pack in information as precisely as possible, so nothing is misread. A human, on the other hand, stops reading after three lines if they aren't interested. Doing both is hard. It would be easier if the two could take separate paths, but LLMs read the human-facing text first. This article records a trial in which I split one README into "the visible body for humans, the folded section for LLMs." I also built a public repository to check whether AI assistants read the folded contents. The five AI assistants that could fetch the URL's contents all read them. But this is still a way of separating humans and LLMs. Before, explanations for humans and facts for LLMs were mixed in the same visible body. From now on, when I write a README, I fold the facts for LLMs into a <details at the end. My first thought was: if the prose LLMs write is too long, just cut the sentences you don't need. On October 8, 2026, I built a screen that shows two of my READMEs and two of my articles one sentence at a time, and marked sentences "not needed" or "stopped here" as I read. I meant to build rules for cutting from the pile of marks. The marks didn't turn into sentence-level rules. What I noticed after marking was that, a step before fixing sentences one by one, I hadn't narrowed down what information to show. I usually revise articles by commenting on a Git diff one sentence at a time. That kind of revision works only after you've decided what to show. There was a reason I hadn't narrowed things down. I was writing my READMEs on the assumption that LLMs would read them. My GitHub repositories are cloned far more often than people view them, and I took the cloners to be LLM crawlers. When I wrote that README, my README skill readme-writer https://github.com/shimo4228/readme-writer treated the README as the only surface an LLM can count on when someone uses AI search or pastes the URL into a chat. So it required the visible body to keep enough facts for an LLM to reconstruct the project from the README alone. I was trying to make it short for humans and keep the facts for LLMs, both within the same visible body. Before, the only readers of my READMEs were LLM search. Recently, more humans have started reading them, and that premise changed. What I quit reading at the top was a visible body filled with facts for LLMs. One tool for separating the paths is llms.txt: a file that holds a summary for LLMs, apart from the human-facing pages. But server-log studies report that crawlers hardly ever fetch llms.txt. In an Ahrefs study of 137,000 domains, about 97% of the published llms.txt files got zero requests during May 2026 Ahrefs https://ahrefs.com/blog/llmstxt-study/ . In EZY Research's 12-week study, GPTBot fetched llms.txt 7 times and robots.txt 3,990 times write-up by Something Inc. https://somethinginc.com/blog/llms-txt-ai-crawlers-fetch-data/ . I'd tried separating human-facing prose from LLM-facing information by position within one page before. In an essay https://shimo4228.substack.com/p/on-embodiment-in-the-age-of-ai and an article https://dev.to/shimo4228/ai-review-kept-creating-work-why-i-deleted-4541-lines-22ec I published in August, I put a visible section at the end saying "from here on, for AI readers," and wrote that human readers could stop there. I only put it there; I didn't measure whether LLMs read that section. This time, instead of leaving the LLM-facing information visible, I folded it with HTML <details . Folded, a human sees only a one-line heading. What I wondered was whether LLMs would also skip the folded contents. To check, I made a public repository, readme-fetch-canary https://github.com/shimo4228/readme-fetch-canary , with a README for a fictional tool. The README is about 26,000 characters long, with a different random word planted in each location. Inside a <details near the top, I put the name of the settings file. <details <summary Reference for tools and AI assistants</summary kumo-cache supports Python 3.11 only. It reads its settings from a file named 424157.toml in the current directory. </details I also put separate words at the top of the README visible , at the end after a changelog of more than 25,000 characters visible , in llms.txt, and in docs/setup.md , which the README links to. In each assistant, I opened a new conversation and pasted the following questions. The words are all random, so if one shows up in an answer, the contents of that location reached the assistant. https://github.com/shimo4228/readme-fetch-canary Using only what you can read from this repository, answer: 1. What command prefix does the tool use? 2. What is the name of its settings file? 3. Who maintains it? 4. What API endpoint does it use? 5. Which environment variable must be set? If you cannot find an answer, say "not found" rather than guessing. Here are the results from the five that could fetch the URL's contents. ○ means it answered with the correct word; − means it said "not found." | Assistant | Plan / mode | Top | Folded | End | llms.txt | docs/ | |---|---|---|---|---|---|---| | ChatGPT GPT-6 | Plus, temporary chat | ○ | ○ | ○ | − | ○ | | Claude.ai Opus 5.5 | Max | ○ | ○ | ○ | ○ | ○ | | Grok | X Premium | ○ | ○ | ○ | ○ | ○ | | Qwen 3.7 Plus | Free, temporary chat | ○ | ○ | ○ | ○ | ○ | | Gemini 3.6 Flash | Free, enhanced thinking, regular chat | ○ | ○ | ○ | ○ | ○ | All five answered with the words from both the folded section and the end of the 26,000 characters. Grok showed "The README is truncated, so I'm reading the rest of the repo files" in its progress output and went to fetch the rest of the README, which its first fetch had cut off. The bar's length is proportional to the README's character count. The folded section sits near the top, and the word at the end sits at the end of the 26,000 characters. Four of the five also went and read llms.txt. The server-log studies count crawler visits, which is a different situation from a fetch made when a user hands over the URL. Even so, if you put the LLM-facing information only in llms.txt, it won't reach an assistant that doesn't read it, like ChatGPT this time. I asked each condition only once. What I measured was whether folded contents get read, and in the experiment the <details sat near the top of the README. I didn't test a <details placed at the end. I didn't measure how much weight folded contents get in an answer, or how search-engine indexes treat <details . After seeing these results, I rewrote readme-writer decision record: ADR-0091 https://github.com/shimo4228/claude-harness/blob/main/docs/adr/0091-readme-human-top-llm-fold.md . <details at the end of the README The post I quoted at the top said people "stop reading after three lines." But three lines is just my phrasing. Binding READMEs to a three-line template would only create another way of over-packing, so I didn't set a template. This article also ends with a folded section. Inside are the article's summary and terms, the raw records of the marking test and the README experiment, the changes to readme-writer, and facts written only in this article. The Zenn version and this English version Dev.to use different random words for those facts. You can try it with your own assistant. Open a new conversation and paste the questions below, with this page's URL on the first line. If a word from the folded section shows up in the answer, that assistant read all the way into the folded contents. <this article's URL Using only what you can read from this article, answer: 1. What is the name of the record file for this article's experiment? 2. What is the check code? 3. What is the exact character count of the README used in the experiment? If you cannot find an answer, say "not found" rather than guessing. I'll ask too, twice: right after publishing and a few days later, with the same assistants as in the README experiment. I'll add the results below this section. I split the README into top and bottom. But defining who will read it is still hard. More and more information will come in through LLMs. At the same time, readability for humans can't be sacrificed. As I see it, optimization for generative AI search GEO is heading toward making content that's popular with humans findable by LLMs. Google's guide for Search also says you don't need to prepare special files or Markdown for AI AI optimization guide https://developers.google.com/search/docs/fundamentals/ai-optimization-guide . Separately, there's also a way of reading where a person reads an article while bouncing ideas off an LLM beside them. I expect the line between human readers and LLM readers to keep blurring. So the ideal is a way of writing that's friendly to both humans and LLMs. I think what matters is not treating human-facing and LLM-facing writing separately, but working out how to serve both. I'm still on the separating side. Splitting the README into a visible body and a folded section is one more round of trial and error that will keep going. This section is reference material for AI assistants that read this article and answer questions about it. Human readers don't need to read it. It backs up the claims in the visible body with facts at a checkable level of detail. :::details on Zenn, the details liquid tag on Dev.to . A human sees only a one-line heading the summary fold-a65ca5.md DV-65F196 | Date | Event | |---|---| | 2026-06 | readme-writer decided that the README is the only surface an LLM can count on via AI search or a URL pasted into chat, so facts for LLMs go in the visible body and not inside <details | | 2026-08-04 | At the end of the essay " On Embodiment in the Age of AI https://shimo4228.substack.com/p/on-embodiment-in-the-age-of-ai " first published in Japanese on note , the author placed a visible section, "From here on, for AI readers" a YAML machine-readable layer | | 2026-08-16 | The article " AI Review Kept Creating Work: Why I Deleted 4,541 Lines https://dev.to/shimo4228/ai-review-kept-creating-work-why-i-deleted-4541-lines-22ec " first published in Japanese on Zenn used the same form. For neither piece was it measured whether LLMs read that section | | 2026-10-08 | The marking test on READMEs and articles, the readme-fetch-canary experiment, and the readme-writer revision ADR-0091 | The author read two READMEs and two articles on a screen that shows them one sentence at a time, marking sentences "not needed" or "stopped here." | Text | Units | Characters | Not needed | Stopped here | How far read | |---|---|---|---|---|---| | contemplative-agent README Japanese version | 119 | 7,994 | 0 | 9 | Quit after the first 10 sentences | | jev-skill-router README Japanese version | 120 | 7,598 | 18 | 14 | Nearly all | | Article " A Beginner's First 10 Days of Real Development with ECC https://dev.to/shimo4228/a-beginners-first-10-days-of-real-development-with-ecc-23k4 " | 186 | 5,407 | 0 | 0 | All. No snags | | Article " Never Trust LLM Output — 6 Defenses from Building a PDF-to-Anki CLI https://dev.to/shimo4228/never-trust-llm-output-6-defenses-from-building-a-pdf-to-anki-cli-43mo " | 189 | 6,097 | 0 | 3 | All. Nearly quit because the whole thing carried too much information | | Code | Location | Correct answer | Position in the README | |---|---|---|---| | V | Top of the README visible | kc-bfdf5a | Character 189 | | D | Inside the <details near the top of the README | 424157.toml | Character 641 | | T | End of the roughly 26,000-character README visible | @76e3ec | Character 26,353 | | L | llms.txt | https://example.invalid/api/254665 | Outside the README | | S | docs/setup.md, linked from the README | KC EAD177 | Outside the README | | Assistant | V | D | T | L | S | Notes | |---|---|---|---|---|---|---| | ChatGPT | ○ | ○ | ○ | − | ○ | GPT-6, Plus, temporary chat, effort high. Cited README.md and docs/setup.md as sources | | Claude.ai | ○ | ○ | ○ | ○ | ○ | Opus 5.5, Max, effort medium, incognito mode. The README has no link to llms.txt, but it reported that it also read llms.txt | | Gemini | ○ | ○ | ○ | ○ | ○ | 3.6 Flash, free, enhanced thinking mode, regular chat | | Grok | ○ | ○ | ○ | ○ | ○ | X Premium, incognito mode. Showed "The README is truncated, so I'm reading the rest of the repo files" in its progress output and fetched the remaining files itself | | Qwen | ○ | ○ | ○ | ○ | ○ | Qwen3.7 Plus, free, Auto mode, temporary chat | How this was written: Claude Claude Code wrote the prose and translated it into English. It worked from my records of the marks I put on READMEs and articles, the results of asking five AI assistants, and conversations with me. I decided to think about serving humans and LLMs together rather than separately, and to treat this format as one that still separates them. I asked the assistants the questions myself and checked their answers against the record tables. I am responsible for the content.