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.