Write for Your Readers... Even If They Are Agents

Coding agents are here to stay. That may be a double-edged sword, but even if the “AI bubble” pops, agents will still be available. Personally, I am starting to experiment with locally-run models, like Devstral Small 2, to see how well they work in the role. Of course, plenty are using Claude Code and OpenAI Codex and JetBrains Junie and so on, whether tied to hosted frontier models or others.

If coding agents are here to stay, we need to look at adapting our ecosystem to accommodate them.

Historically, our documentation has been designed around human readers. The bigger the project, the more likely it is that is has nicely-formatted documentation, spread over many pages. Or the project uses a Wiki, CMS, or other tool for documentation. Heck, some crazy people even write books about programming, distributed as PDFs and EPUBs and the like.

LLMs like text. Plain text. Maybe a bit of Markdown for spice. But, in the end, it’s text, text, text.

Some LLMs will include some projects’ documentation as part of a training set. That’s all well and good, but the LLM’s knowledge base (such as it is) will only be as up to date as the training set that was used to train the model. Pointing an agent to ordinary well-formatted documentation, in the hopes that it will understand and incorporate it, is a hit-or-miss proposition, as the LLM needs to fight through all of the formatting. Formatting is important for human readers, but it is cruft to an agent.

If your project’s documentation is already in Markdown or other forms of plain text, consider ensuring that the documentation is discoverable in raw Markdown, as opposed to having been rendered by MkDocs or GitHub Pages or whatever. Linking to that from the project README, perhaps with some notes for agents to help them find it, may help the agents leverage your library or tool.

Better yet is to create something designed specifically for agents. Some folks are experimenting with custom text files, for example.

Personally, I expect that skills will be the better option, at least in the near term. Many agents already support skills, either from locally-installed files or via some form of import mechanism (e.g., Claude Code’s plugin system).

For example, Ben Oberkfell recently published a plugin that packages up some skills for popular Jetpack Compose libraries like Showkase and Haze, plus Kotlin Multiplatform libraries like Metro. Whether it’s a one-line git clone or a one-line /plugin command in Claude Code, developers can add these skills that their agents can use.

My guess is that there will be fairly rapid iteration and “ideation” in this area, so if you want to sit tight for a bit and “wait for the dust to settle”, that’s reasonable. But, one way or another, my guess is that we need to start thinking about how agents will learn how to use our stuff, not just ordinary human developers.