--- title: "Writing for Agents" url: "https://www.dariuszparys.com/writing-for-agents" author: "Dariusz Parys" published: 2026-11-06T09:50:50.000Z updated: 2026-11-06T09:50:50.000Z description: "What would a blog post look like if only agents read it? I worked out the format, decided against it, and added a second layer for agents instead." tags: - "Context Engineering" - "AI Tools" - "Cloudflare" - "Blogging" applies_to: - "Personal blogs built as static sites" - "Astro content collections deployed to Cloudflare Pages" tested: "2026-11, dariuszparys.com, Astro 7, Cloudflare Pages Free plan" findings: - id: "F1" claim: "Turning the ADR post's claims into findings showed that one figure, about 50K tokens for 40 ADRs, was an estimate. The first draft of the findings had labelled it as measured." evidence: "Observed in 1 of 1 post converted so far." cite: "https://www.dariuszparys.com/writing-for-agents#finding-F1" - id: "F2" claim: "A static Astro site on the Cloudflare Pages Free plan can serve a Markdown copy of every post at /.md. Cloudflare serves it as text/markdown without a Content-Type rule in _headers." evidence: "Verified on production, 2026-11-06." cite: "https://www.dariuszparys.com/writing-for-agents#finding-F2" - id: "F3" claim: "Cloudflare's \"Markdown for Agents\", which answers Accept text/markdown requests on the normal URL, needs the Pro plan." evidence: "Seen in the Cloudflare dashboard, 2026-11." cite: "https://www.dariuszparys.com/writing-for-agents#finding-F3" --- # Writing for Agents ## Who reads this blog now? I barely publish nowadays posts on this blog. I barely published posts at all on this blog. From time to time I think this might be worth to keep but who really visits blogs for technical content or tutorials. No one does. You usually ask for that kind of stuff your agent and discuss with them what is possible. Opinions, Findings are still worth to post, but pure technical explanations are not. At least not without findings out of real projects. Most of the traffic on my blog is not people. In the last 30 days Cloudflare counted about 150,000 requests but only 15,400 visits. 38% of all requests ended in a 404, probably scanners looking for paths that don't exist, and for 39% Cloudflare could not name a browser at all. What the free dashboard does not tell me is how much of this comes from AI agents. Crawling sites is common for agents, to refresh information for their next iteration of training or for post training. I think there is value in providing blog content for agents as well. But how would an agent benefit from the prose? Wouldn't it be better to prepare a shadowed page with the information they can get without the prose they don't need? ## A post for agents only I decided to turn my posts for agents into findings if there are any. Including the conditions these findings occured and evidence if there is some. Here is what that looks like for my post [Your ADRs Are Costing You Tokens](/your-adrs-are-costing-you-tokens). The post has about 1,000 words. The version for agents keeps four findings, where they apply, and when I tested them: ```yaml --- title: "Your ADRs Are Costing You Tokens" url: "https://www.dariuszparys.com/your-adrs-are-costing-you-tokens" published: 2026-03-02T06:06:36.000Z applies_to: - "Repositories whose architecture decision records are loaded into a coding agent's context" - "Claude Code projects that use rules files in .claude/rules/" tested: "2026-03, one client project with 40 ADRs, Claude Code" findings: - id: "F1" claim: "Loading all 40 ADRs costs about 50K tokens, a quarter of a 200K context window." evidence: "Estimated for one project." - id: "F2" claim: "After the project switched its primary database from Cosmos DB to Azure SQL, the agent kept assuming Cosmos DB was primary. The switch was recorded in ADRs, but not in a form the agent used reliably." evidence: "Observed in one project." - id: "F3" claim: "An audit of 40 ADRs found 3 status problems. One superseded ADR was still marked proposed, one used the non-standard status approved, and one lacked a partial-supersession note." evidence: "Observed in one project." - id: "F4" claim: "A rules-file index of active ADRs (about 1K tokens) with a map from superseded ADRs to their replacements tells the agent which full ADR to load, instead of loading all of them." evidence: "Used in one project; no before-and-after measurement." --- ``` `applies_to` and `tested` tell an agent whether the post fits its user's problem before it reads anything else. Each finding is one claim plus how I know it. "Observed in one project" is weaker than "measured in three projects", and an agent can tell the difference. The story of how we noticed the Cosmos DB problem is gone. It survives only as F2. You can see the full version at [/your-adrs-are-costing-you-tokens.md](/your-adrs-are-costing-you-tokens.md). No hook, no story, just like TL;DR thing. Optimised for agents. Two things get added. A `does_not_apply_to` list says where the findings don't hold, and every finding gets a stable id with its own URL, like [`#finding-F2`](/your-adrs-are-costing-you-tokens#finding-F2), so it can be cited on its own. The findings are facts, not instructions. An agent reading my post works for someone else, and text on a web page that tells it what to do looks like prompt injection. A fact it can check and pass on to its user. ## Why I still write for people I write this blog for people. I want them to read a post, disagree with it, or ask me about it. An agent does none of that. Agents use what they read, but they don't always say where it came from. If an answer uses my F2, the person who asked may never know it came from here. And someone who follows a link would land on a list of findings. They would see what I found, but not how I got there or why I think it matters. Some posts lose almost everything in this format. A post about why I decided against an approach, or about building a side project in public, has no list of findings. The decision and the story are the post. ## What I built instead: two layers So I kept the post for people and added a layer for agents next to it. The human post stays the main one. The agent layer is generated from the same Markdown file when the site is built, so I don't write the post twice. The only extra work is the findings in the frontmatter. The agent layer has four parts: - A Markdown copy of every post at the post's URL plus `.md`, for example [/your-adrs-are-costing-you-tokens.md](/your-adrs-are-costing-you-tokens.md). It starts with the title, URL, author and dates, plus the scope and findings when the post has them, followed by the post itself. - `/llms.txt`, a plain list of all posts with a one-line description each, linking to the Markdown copies. It starts with a short section about me, so an agent knows who wrote what it reads. - Structured data on every post page: JSON-LD that names me as the author, links my GitHub, LinkedIn and X profiles, and points to the Markdown copy. - A "Scope and findings" box on posts that have findings. It shows where the post applies, when I tested it, and each finding with its own link, so people see the same information agents get. ![The Scope and findings box on the ADR post, with four findings and their evidence](./assets/scope-box.png "The box on the ADR post, opened through a link to F2, which is why F2 is highlighted") ## What writing findings exposed I let Claude Code write the first version of the findings for the ADR post. F1 came back as "Loading all 40 ADRs costs about 50K tokens", with the evidence "Measured in one project." That's not what my post says. The post says "A typical project with 40 ADRs weighs in at ~50K tokens." That number is an estimate. In prose the difference is easy to miss: the sentence reads like a fact, and the reader can't tell how I got the number. The agent couldn't tell either, and picked the stronger label. A finding needs an evidence label, so I had to decide: measured or estimated? I changed it to "Estimated for one project." That's the most useful thing I learned from this. Writing for agents forces me to say how I know something, and my posts for people would get better from that too. ## Decisions along the way A few smaller decisions came up while building this. I thought about putting a tip link into `llms.txt`, and left it out. Agents don't tip, and a request for money aimed at an agent is the kind of text a careful agent ignores, for the same reason as the instructions above. Instead, `llms.txt` starts with a short section about me, the same description as on my About page. If someone asks their agent who wrote a post, the agent can find the answer there. Cloudflare has a feature called Markdown for Agents. When an agent asks for a page with an `Accept: text/markdown` header, Cloudflare converts the page to Markdown on the normal URL. It needs the Pro plan, and this blog runs on the Free plan. That's why the Markdown copies have their own URLs. The Markdown copies shouldn't compete with the HTML pages in search results. They aren't in the sitemap, and each one sends a canonical header that points to its HTML page. On Cloudflare Pages that's a single rule in the `_headers` file, because Cloudflare can put the matched part of the path into the header value: ```text /*.md Link: ; rel="canonical" ``` ## What I don't know yet I built the agent layer without knowing whether agents use it. These are the open questions: - Does any agent fetch `/llms.txt` or the Markdown copies at all? The Cloudflare dashboard can filter requests by path and shows user agents, so this is the first thing I'll check. - Do the big AI providers read `llms.txt`, or do they only fetch the HTML pages? - Does any agent ever cite a finding by its id or URL? I don't know yet how I would even notice. - Does the author information in the JSON-LD change how AI answers name their sources? - Do search engines respect the canonical header, or do they treat the Markdown copies as duplicate content? - Is it worth writing findings for every post, or only for experiments and reports from real projects? I'll look at the numbers again in about two months and write a follow-up with what I find.