Writing for Machines

Jul 20, 2026

2857 words 15 min read Reading ease: …

DISCLAIMER: The views and opinions expressed in this blog are solely my own and do not reflect those of my employer, or any of its affiliates.

TL;DR; There is a new way people write for machines, a SKILL.md voice that is harder, terser, and all orders. If you write these files, you have picked up that style without being taught it. I measured where it came from and whether it holds up, and the answer should change how you write the next one.

The same instruction, written for humans and for machines

Here are two ways to tell someone how to run a project’s test suite.

The first is the sort of thing you find in a README, written for a person who has just shown up:

Once the dependencies are installed you can run the tests with pytest. Most contributors run the fast subset while they work and save the full suite for just before opening a pull request.

The second is the sort of thing that shows up in a SKILL.md, one of the files people now write to instruct an AI coding agent:

Run pytest -q. If it fails, read the first failure, fix the root cause, and run it again. Do not continue until the suite is green.

Same task, and roughly the same information. The voice is not the same. The second version is shorter and more clipped, and it gives orders. It does not hedge¹, it does not explain itself to a newcomer, and it assumes a reader who will do what the words say and nothing they merely imply.

That gap is the subject of this post. A README and a SKILL.md are both documentation, but they are aimed at two different readers. The README is written for a person deciding whether to use your project: someone who skims, forms a quick impression, and leaves if it looks like work. The SKILL.md is written for a machine that will execute the instructions literally, never skim, and never forgive a sentence with room left in it. Over the past two years people have started writing differently for that second reader. I like to call it SKILL-speak, after the file where it shows up and I wanted to know whether it is something you can measure, or just a feeling.

I read each file three ways: its language (the words and how they are used), its structure (how the page is laid out), and its place in time (when it was written). The sections ahead take each in turn.

It is real. Before I get to how large it is, a word on where the numbers come from, and why they are in a blog post to begin with.

Why it is not a paper

This started as a paper. I built a corpus of a bit over 672,000 SKILL.md files, together with human-written READMEs to compare them against, and measured all of it.² It is a blog post rather than a paper for a bitter reason. Out of everything I found, exactly one result is confirmatory, and everything else is a lead. Some of the leads are surprising, and I will show them, but a lead is not a finding³, and I have argued before that dressing weak results up as strong ones is most of what is wrong with how we publish⁴.

The register is real, and you can measure it

On every linguistic measure I looked at⁵, instructions written for agents differ from instructions written for humans, and they differ in the same direction across all of them.

Specifically, in each document, I counted five things: (i) how many of its sentences are commands (imperative mood), (ii) how much it hedges (words like might, could, probably), (iii) its reading-grade level, (iv) how deeply its sentences nest grammatically, (v) and how tightly neighbouring sentences reuse words (a rough proxy for how well the text hangs together). The same document always produces the same five numbers.

Two things could make agent files look different from human files: the reader they are aimed at, and the year they were written. These are separate axes, and they are easy to confuse. Writing drifts over time on its own, so comparing old human READMEs against new agent files would blend the two, and I could not say how much of the gap comes from the reader. So I hold the year fixed and compare human docs and agent docs from the same stretch, both written after 2023.⁶ Whatever separates them now is down to the reader, not the decade. Held that way, agent and human writing pull apart on all five measures, and the widest gap is readability:

Measure	For agents, the writing is	Effect size (Cohen’s d)
Reading grade (Flesch-Kincaid)	about 4 grades harder	0.40
Sentence depth	more deeply nested	0.26
Commands (imperative)	roughly 50% more of them	0.25
Hedging	about half as much	0.09
Word-reuse cohesion	slightly tighter	0.06

Every measure pulls agent-directed and human-directed writing apart, all in the same direction. Effect sizes are Cohen’s d⁷. N = 242,159 documents, all post-2023.

When we consider readability, agent instructions land about four grade levels higher on the Flesch-Kincaid⁸ scale than human instructions from the same period. Four grade levels is roughly the jump from a general-audience newspaper to a dense university handout. People write harder, denser prose when the reader is a machine. The commands go up by about half, the sentences nest deeper, and the hedging falls. If you have written one of these files, none of this will surprise you: you were writing for something that does not get bored and does not need to be eased in, so you cut the throat-clearing and started giving orders.

How much of this is just AI writing?

A large share of these SKILL.md files were not written by people. They were written by AI, since asking a model to draft the instructions for another model is the easy way to produce one. If agent files read harder and more commanding, maybe no human adapted anything, and we are only measuring how models write when left to themselves.

So I checked. I took several hundred files I could confidently attribute to a model, measured them the same way, and asked whether they differ from human writing in the same direction as the full agent corpus. On four of the five measures they do. The reading grade, the sentence depth, the imperative commands, and the cohesion all push the same way whether a person or a model wrote the file. So on four of the five measures, the difference could just be models writing in their own hand, with no human adapting anything.

The fifth measure breaks the pattern, and it breaks it backwards. When a model writes the file, hedging goes up. A model trained to be cautious keeps the mights and the coulds rather than cutting them, while humans prefer to remove them. So the drop in hedging cannot be an artifact of machines drafting the docs, because when machines draft the docs the hedging rises. People cut the hedges deliberately in the SKILL.md.

That makes hedging the one part of SKILL-speak I can tie to human hands rather than to models. It is the smallest of the five effects and the cleanest, and it is why I think there is a real story here and not just a portrait of how AI writes. The next signal is larger, and it lives in the layout.

Layout matters more

A SKILL.md and a README differ in more than diction; they are built differently on the page. I measured thirteen layout features the same mechanical way as the rest, things like the share of text in bullet lists, the number of section headings, the amount of code, and how many links point off the page. Eight of the thirteen show a wider agent-versus-human gap than the largest word-level gap.

Agent files are rich on sections, bullets, and code blocks, and go light on links.

A README flows as prose for a reader who skims and decides; a SKILL.md breaks into headings, bullets, and code for a reader that runs it top to bottom.

The same question I asked of the words applies to the layout: is this gap people writing for a machine, or just models drafting files in their own style? I ran the authorship check again, splitting the agent files into the ones a human wrote and the ones a model wrote, and the layout splits in two. Models have their own layout habits, they love bullet lists and bold text, and that bullet-and-bold density does show up in the model-written files. What does not reproduce when a model writes the file is the deep sectioning and the heavy use of code. Human-written SKILL.md are more deeply structured than anything the models produce on their own. So the layout gap comes from two places. Part of it is models writing like models. The rest is people deliberately rebuilding the document for the agent that will run it, and only that second part holds up once I account for who wrote the file.

By now SKILL-speak has a shape we can state. Next to a README, a SKILL.md reads about four grades harder, gives roughly 50% more commands, hedges less, and nests its sentences deeper; on the page it leans on deep sections and code blocks and points to few links off the page. Some of that is models writing like models, but cutting the hedges and building the deep structure are human. This is the register. Whether any of it is worth writing is the next question.

Does any of it predict which skills people use?

If SKILL-speak is real, is there a right way to write it? Everyone who maintains a SKILL.md wants the same thing from it, that it works and that people adopt it. I could not measure whether the writing makes an agent succeed, but I could measure adoption, because alongside the text I had a record of how often each skill was installed.

SKILL-speak barely predicts adoption, and where it predicts anything it points the wrong way. Recall we have two families of measures: the word measures (commands, hedging, reading grade, and so on) and the layout measures (bullets, headings, code, links).

Of the five word measures, exactly one has any durable link to installs, imperative density. More commands, a little more adoption. The other four predict nothing.

The layout measures carry most of SKILL-speak, and they point the opposite way from what you would guess. The more bullet-heavy and code-heavy a skill’s file, the fewer installs it got, not more. The one layout feature that went with more installs was links, and links are the one thing agent files use least of. So adoption rewards the opposite of SKILL-speak. A skill is installed by a person who reads the file first, and a wall of bullets and code gives that person less to grab onto while skimming than a few links and some prose.

So I am left with a strange pair of facts. SKILL-speak is real and measurable. And the one outcome I can measure, whether people install a skill, says nothing about whether writing in SKILL-speak makes the skill better.

A dialect spreading by imitation

So the register is real but nobody can show it works. What I think is happening is imitation. People are converging on a way of writing for machines, and the thing driving the convergence is copying, each new file modelled on the last popular one. No one has shown the style works; it spread because it was copied.

The copying is literal. When I clustered the corpus looking for styles, the tightest clusters were template farms: single repositories that stamp out thousands of near-identical skill files by swapping a noun here and there.⁹ Twenty-three thousand documents sat in nine such farms, tight dense knots against a diffuse cloud of everything else. SKILL-speak spreads the way conventions spread online, by copying whatever the last popular example did.

Every SKILL.md file placed by its measured features (PCA projection). Organic files spread into a diffuse grey cloud; the 23,711 template-farm files (blue) collapse into a few tight knots, each a single repository stamping out near-identical copies.

Something clicked for me partway through the analysis: a SKILL.md has two readers, not one. One is the agent that runs the file. The other is the person who reads it first and decides whether to install it at all. Writers shape the style for the agent, harder and terser and more commanding, but it is the person who decides, and the dense bullets and code piled on for the agent are the very thing that went with fewer installs. So the convention spreads a style tuned for the reader that runs the file, when the one deciding its fate is the human skimming it. If you are going to follow it, write for the reader whose choice you actually depend on.

I have built enough agent systems to be wary of this move, adopting a practice because it looks right and everyone else does it, with no external check that it works.¹⁰ A convention that spreads by imitation is not automatically wrong, and it might turn out to be right. For now it is a convention wearing the costume of a best practice, and the two are different things.

How to write one today

There is no style guide to hand out, because the evidence does not support one. But the experiment that would earn one is clear. Hold a skill’s content fixed, rewrite only its register, and measure whether the agent completes the task more often. That is the test that separates a real effect from a convention. Adoption cannot do it, tangled as it is with popularity and platform and luck.

Until someone runs that, here is where I would leave anyone writing these files today. SKILL-speak is real, so you are not imagining that a SKILL.md should sound different from a README. Write for the reader that executes: drop the throat-clearing, give direct instructions, lay the document out so a machine can walk it top to bottom. But hold the confidence loosely. That everyone is converging on the harder, denser, more commanding style is the one thing I can prove. It is also, on its own, no evidence that the style works.

We started writing for a reader that never skims and never forgives a vague sentence, and it shows. Whether we write for it well, we have not yet answered.

Footnotes

1. In linguistics, hedging is language that softens a claim or signals the writer is not fully committed to it: might, could, seems, in some cases, roughly. I count hedge terms per thousand words, so a lower number means flatter, more direct assertion. ↩

2. The corpus, the measures, and the code behind every number here are open on the paper branch of timbro. This started as that project’s paper before it became a post. ↩

3. A finding has been stress-tested. A lead is a just pattern, so it might be real or it might be an artifact of how it was found. ↩

4. I argued in The SOTA Trap that without its code and data, a paper is a press release wearing the costume of a contribution. Holding myself to that here means I will not dress a nice-looking correlation up as a finding. ↩

5. A program computes each metric the same way every time, so anyone can rerun the exact computation and get the same number back. ↩

6. To pull audience apart from time, I compared three groups rather than two: human documentation from before 2023, human documentation from after 2023, and agent documentation from after 2023. The gap between the two human groups measures what changed with time alone; the gap between the post-2023 humans and the post-2023 agents measures what changed because the reader is a machine. This three-way split was fixed before I looked at the results. ↩

7. Cohen’s d measures a gap in standard deviations, so it does not depend on the units of any one measure and the five stay comparable. As a rough guide, 0.2 is a small effect, 0.5 medium, 0.8 large. The readability gap at 0.40 is small-to-medium; the rest are smaller still. ↩

8. The Flesch-Kincaid grade level is a standard readability formula that turns sentence length and syllables per word into a US school grade; a higher number means denser prose. Background: Wikipedia. ↩

9. A handful of repositories account for most of the nine farms: zwright8/OpenClaw-Code (about 8,200 files across two clusters), Sandeeprdy1729/skill_galaxy (about 7,500 across three), NeuralBlitz/Agent-Gateway (about 3,100), and membranedev/application-skills (about 2,600). Open any one and the files are the same scaffold with a noun swapped. I am pointing at the pattern, not the people; these repositories were public when I built the corpus. ↩

10. I have argued that orchestrating agents well is mostly an exercise in saying no: no self-grading, no scores you cannot compare against a baseline. The same caution applies to how we write for them, and to trusting a text-to-installs model before it replicates. ↩

If you like my work, consider buying me a coffee to support future posts.