Sharpwork by Chris Fildes

More docs, less clarity: why I'm writing for agents in Simplified Technical English

Chris Fildes · · 7 min read

We have more documentation than ever, and that's mostly good news. An agent can write a README, a spec, a task list or a ticket in seconds. Teams that used to ship with no docs now ship with plenty. This post is about why I think Simplified Technical English can help with what comes next, and about the agent skill I wrote to make agents write in it.

The problem is what that documentation looks like. I see bloat: paragraphs that take three sentences to say one thing. I see verbose text that hides the one instruction someone actually needs. And I see the style change depending on who, or what, wrote the page. One runbook is terse, the next reads like a blog post, and the spec between them was written by a model with its own habits.

That inconsistency costs something every time a person reads it. Now it also costs something every time an agent reads it. The agent loads the README into its context, works through the task list and acts on the spec. It's a reader of our docs too.

A Standard That Already Exists

Simplified Technical English (STE) is a controlled form of English defined in the ASD-STE100 specification. It was developed for aerospace maintenance manuals. In that setting, a technician who may not speak English as a first language has to read a procedure once and carry it out correctly.

STE does this with a few blunt rules:

  • A procedure sentence has at most 20 words. A descriptive sentence has at most 25.
  • Each step has one instruction.
  • Sentences use the active voice.
  • Each word has one meaning.
  • No idioms, no phrasal verbs, and no vague amounts like “soon” or “a few”.

None of those rules is really about aircraft. They're about a reader who has to act on the text and can't always ask the writer what they meant.

The people who maintain the standard have noticed the overlap with AI. In 2026, ASD's STE Maintenance Group published a white paper on STE and AI. The paper says Issue 9 of the standard has already been downloaded more times than Issue 8 was in its whole lifetime. The group credits much of that growth to interest in AI and to new readers from computer science and IT.

The Same Rules Help Agents

That description fits an agent even better than it fits most humans. A colleague who isn't sure what you meant will ask. An agent can pick one meaning and carry on.

Take “should”. In a requirement it can mean “must”, “it would be nice”, or “this is probably true”. A human uses context and judgement to tell which. An agent guesses. STE removes the guess: use a command for an instruction, “must” for a requirement, and “can” for an option.

The same goes for synonyms. Say a doc calls something “the gateway” in one paragraph and “the proxy” in the next. A non-native reader assumes those are two components. A search tool that gives an agent one paragraph only finds one of the two names.

My view is that STE reduces cognitive load for both developers and agents. For a developer, that means fewer rereads. For an agent, it should mean a smaller context and, in theory, less reasoning and fewer tokens before it reaches the right action. I say “in theory” because I haven't measured token usage yet.

That's what my skill, STE-it, is for. It makes an agent apply these rules when it writes documentation.

How the Skill Works

It works mainly as a style layer. You ask for a spec, a plan, a task list or a runbook, and you add “use STE”. The template or skill that defines the document still controls its structure, headings and content. The STE skill only controls how each sentence is written. It can also convert existing text into STE.

It has two levels. The strict level is for text where a misreading leads to a wrong action: procedures, warnings, requirements, API docs, and anything an agent reads, such as system prompts, AGENTS.md and skill files. The light level is for text that explains, such as design rationale, PR descriptions, commit messages and code comments. Light allows a wider vocabulary but keeps the sentence rules. It still bans “should”, idioms and contractions.

It leaves alone anything that must not change. That includes code, commands, paths, identifiers, quoted text, product names, and RFC 2119 keywords in a spec that defines MUST and SHOULD.

It doesn't trust the model to count. Models are bad at counting words, so the skill comes with a Python checker. The checker flags long sentences, passive and modal verbs, paragraphs that start with a pronoun, steps with two instructions, and words from a replacement list. The agent fixes each finding or keeps it for a stated reason. It then rereads for the problems a script can't catch, like using two names for one thing.

Here's an example from the skill.

Before:

When you’re working in the codebase, try to avoid making changes to the generated files since they’ll get overwritten anyway, and it’s probably best to run the tests before committing.

After:

When you work in this codebase, obey these rules:

  • Do not change the generated files. When the files are generated again, your changes are lost.
  • Run the tests before you commit.

I'm not the first person to point STE at AI. There are other STE skills out there, such as danyuchn/asd-ste100-skill and AminBlg/SimpleEnglish, but I wanted to build my own.

What's in the Repo

The skill lives at github.com/iamchrisfildes/ste-it-skill under the MIT license. It's small:

  • SKILL.md holds the instructions the agent follows.
  • references/word-list.md lists words to avoid and what to use instead.
  • scripts/check_ste.py is the checker. It needs Python 3.10 or later and nothing outside the standard library.
  • evals/ holds the six test cases described below, each with a prompt, input files and graders.

It uses the Agent Skills format, so it works with Claude Code, GitHub Copilot in VS Code and other agents that support it. For Claude Code, installing it is one command:

git clone https://github.com/iamchrisfildes/ste-it-skill.git ~/.claude/skills/ste-it

The folder has to be called ste-it to match the skill's name, even though the repo is ste-it-skill. VS Code won't load it otherwise.

You can also run the checker yourself on any Markdown file, without an agent:

python scripts/check_ste.py runbook.md --level strict

It skips code blocks, inline code, tables, headings and quoted text, and it returns exit code 1 when it finds something. That means you could drop it into CI, though I'd treat its findings as prompts to look again rather than hard failures. It can't check meaning.

What the Tests Show, and What They Don't

I tested the skill on six cases:

  • a spec with RFC keywords
  • a messy runbook
  • a PR description
  • a task list in a fixed template
  • instructions for an agent
  • a design rationale

Each case ran three times with the skill and three times without it.

Content was about the same. With the skill, every case passed all of its content checks. Without it, four cases passed all of them, and the other two averaged 97% and 90%.

Form was where they differed. With the skill, every case had zero checker findings. Without it, five cases averaged between 1.3 and 4.3 findings each. The spec case had none either way.

That result is narrower than it looks. The checker encodes the skill's own rules. So zero findings shows the skill does what it says it does. It doesn't show that readers understand the text faster. The models already got the content right, and the skill made the shape consistent. Since inconsistency was my original complaint, that's the part I wanted. Whether it also cuts tokens or downstream errors hasn't been tested yet.

Where I Wouldn't Use It

STE suits READMEs, specs, tasks, tickets and documentation. It doesn't suit an article like this one, where you want the reader to hear a voice. That's why this post isn't written in STE.

It also isn't worth applying to text that's already clear. One recent study (Shi et al., 2026) used an LLM to rewrite software requirements into a controlled language. The rewrite made it easier to trace vague requirements to the code that implements them. For requirements that were already well written, it made tracing worse. STE fixes bad text, and it can damage good text.

Try It on One Document

Agents are going to keep writing more of our documentation, and reading more of it too. The cheapest way to find out whether STE helps your team is to try it on one real runbook or spec. Ask your agent for it in STE, put it next to the version you have now, and see which one you'd rather act on. You can find the skill at github.com/iamchrisfildes/ste-it-skill.