Most advice for fixing AI writing is vague: "be concise," "sound human," "avoid fluff." ASD-STE100 Simplified Technical English is the opposite. It is a controlled-English standard, written for aerospace maintenance manuals, with concrete rules a model can follow and a script can check. This guide shows how to apply it to AI output in practice, whether you use an agent skill, a one-line prompt, or a rule block in your project files.
If you want the background, benchmark and Hacker News debate, read our analysis of the SimpleEnglish skill. This post is the how-to: what to install, what to type, and how to tell whether it worked.
What you need before you start
- An AI agent or chat tool that accepts instructions: Claude Code, Cursor, Codex, Gemini CLI or similar.
- A document type where clarity beats style: a README, runbook, error message, incident report or release note.
- Optional: Node.js, if you want to install the agent skill, and Python, if you want the checker script below.
STE is not a skill you apply to everything. Decide per document type, and keep your normal voice for blogs and marketing.
TL;DR: three ways to apply it
| Method | Effort | Best for | Weakness |
|---|---|---|---|
| Install the SimpleEnglish skill | A few minutes | Teams that want shared, tested rules | Extra dependency; check what it loads |
| One-line prompt | 30 seconds | Trying it today | You rely on the model's memory of the standard |
| Rule block in AGENTS.md or CLAUDE.md | 10 minutes | Per-project consistency | You maintain the rules yourself |
Method 1: install the SimpleEnglish agent skill
AminBlg/SimpleEnglish is an open-source, unofficial agent skill that paraphrases the standard's rules for software writing. It is not affiliated with ASD or the STE maintenance group, and nothing certifies a tool as STE compliant. Install it with:
npx skills add AminBlg/SimpleEnglish
The repository lists support for Claude Code, Cursor, Codex, Gemini CLI and many other harnesses. After installing, start a new session so the agent picks up the skill, then ask for a document by name:
Write the README setup section for this project. Use the SimpleEnglish skill.
Before you trust any skill, open its files and read what it tells the agent to do. A skill is instructions that run with your agent's permissions. For background on how skills load and where they live, see our complete guide to agent skills.
Method 2: the one-line prompt
If you only want to try the idea, add one line to your system prompt or the start of a chat:
Use ASD-STE100 Simplified Technical English. Keep sentences short, use active voice, and give one instruction per sentence.
Models know the standard well enough that this alone changes the output. The cost is consistency: the model may drift on long documents or forget the rule halfway through. Treat the one-liner as a quick test, and move to Method 3 if you like the results.
Method 3: a rule block in AGENTS.md or CLAUDE.md
For project work, put the rules where every session reads them. Paste this into your AGENTS.md, CLAUDE.md or equivalent file:
## Writing rules for documentation and messages
Apply these rules to READMEs, runbooks, error messages, incident reports and release notes. Do not apply them to marketing copy or blog posts.
- Write sentences of about 20 words or fewer.
- Use active voice.
- Give one instruction per sentence.
- State the condition before the command. Write "If the flag is set, run X", not "Run X if the flag is set".
- Do not use -ing verb forms where a plain verb works.
- Do not use should, would, may or might. Use must for requirements and can for options.
- Keep articles (a, an, the) and the word "that". Do not write telegraph-style fragments.
- Use one word for one meaning. Do not swap "start", "launch" and "kick off" for the same action.
This is our summary of the main ideas, not the official standard. The real specification has more rules and a controlled dictionary. If you need formal compliance for regulated documentation, work from the published standard and a qualified technical writer, not from a prompt.
For help choosing between a skill, a project file and a hook, see CLAUDE.md vs SKILL.md vs MCP.
The rules that matter most
You do not need all of the standard to see a benefit. These rules remove most of the typical AI-writing tells.
| Rule | Why it helps | Weak example | Better example |
|---|---|---|---|
| Short sentences | Readers do not lose the subject | "It is important to note that the service, which runs on port 8080, needs the config file before it starts" | "The service runs on port 8080. It needs the config file before it starts." |
| Active voice | Names who does what | "The file should be saved by the user" | "Save the file." |
| One instruction per sentence | Steps cannot be half-done | "Open the file and edit the key and restart" | "Open the file. Edit the key. Restart the service." |
| Condition before command | Reader checks before acting | "Restart the service if the config changed" | "If the config changed, restart the service." |
| No hedging verbs | Requirements stay clear | "You should back up the database" | "Back up the database." |
| No -ing filler | Removes vague clauses | "...making it easy to deploy" | "Deploy with one command." |
| Consistent terms | One word, one meaning | "Launch, start, boot, kick off" | "Start" every time |
Step-by-step: rewrite a document with STE
Use this workflow on any draft, human or AI.
- Pick the document. Choose one with a clear reader and task, such as a setup guide.
- Ask for a rewrite, not a new draft. Give the model your text and say: "Rewrite this in ASD-STE100. Do not add facts. Do not remove steps."
- Read the diff. Make sure steps, numbers and warnings are intact. Controlled writing should not change meaning.
- Run the checker (below) to catch leftovers.
- Test it on a person. Ask someone unfamiliar with the project to follow the steps. Where they hesitate, the text is still ambiguous.
The line "Do not add facts" matters. When models shorten text, they sometimes invent a missing detail to make a sentence feel complete.
Recipes by document type
Error messages
Order the message as what happened, why, and what to do.
Before: We encountered an issue while processing your request. Please try again later.
After: The upload failed. The file is larger than 25 MB. Choose a smaller file and try again.
Runbooks
A runbook is the closest modern relative of a maintenance manual. Number the steps, and keep each step to one action and one expected result.
1. Open the dashboard.
2. Find the failing job.
3. Select Restart. The status changes to Running within 30 seconds.
Incident reports
Use simple past tense and real times. Avoid soft language that hides the facts.
Before: We have identified an issue that may have impacted some users.
After: Between 14:02 and 14:31 UTC, 12% of requests failed. A deploy at 14:00 caused it. We reverted the deploy at 14:27.
Release notes
Put the action first and the risk second. Make breaking changes read like warnings.
Before: This release introduces some changes to how configuration is handled.
After: Rename `config.yml` to `settings.yml` before you upgrade. The old name no longer works.
AGENTS.md and system prompts
A model reads "should" as optional. Replace it with a direct command so the rule has force.
Before: You should try to keep functions small.
After: Keep each function under 40 lines.
A small checker script
Rules are easier to follow when something checks them. This short Python script is our own sketch, not the SimpleEnglish repository's linter. It flags long sentences, hedging words and -ing forms.
import re, sys
HEDGES = {"should", "would", "may", "might", "could"}
def sentences(text):
return [s.strip() for s in re.split(r"(?<=[.!?])\s+", text) if s.strip()]
def check(text):
issues = []
for s in sentences(text):
words = re.findall(r"[A-Za-z0-9'-]+", s)
if len(words) > 20:
issues.append((s, f"{len(words)} words (limit about 20)"))
low = [w.lower() for w in words]
bad = sorted(HEDGES.intersection(low))
if bad:
issues.append((s, "hedge word: " + ", ".join(bad)))
ing = [w for w in low if w.endswith("ing") and len(w) > 4]
if ing:
issues.append((s, "-ing form: " + ", ".join(ing)))
return issues
if __name__ == "__main__":
text = open(sys.argv[1]).read() if len(sys.argv) > 1 else sys.stdin.read()
for s, why in check(text):
print(f"- {why}\n {s}")
Save it as ste_check.py and run python3 ste_check.py README.md. Expect false positives: nouns such as "string" or "setting" end in -ing and are fine. Treat the output as prompts for review, not errors. It also cannot tell whether a step is missing or wrong.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| Output is clipped and hard to read | The model treated STE as "be terse" | Add "keep articles and the word that" to the instruction |
| The model forgets the rules in long documents | Instruction was only in chat | Move the rules to AGENTS.md or CLAUDE.md |
| Facts changed during the rewrite | The model filled gaps | Add "Do not add or remove facts" and review the diff |
| Marketing text sounds dead | Wrong tool for the job | Do not apply STE to persuasive writing |
| Skill does nothing | Session did not reload it | Start a new session and name the skill in your request |
| Steps still bundle several actions | Rule not strict enough | Add "one instruction per sentence; one action per step" |
When not to use STE
STE removes personality on purpose. Skip it for blog posts, landing pages, brand stories, speeches and fiction. It also does not make a document correct. A flat sentence can still be wrong, so keep a human review step for anything safety-relevant, legal or regulated.
Measuring whether it works
Do not judge by feel. Pick five documents, run them through your setup with and without the rules, and compare three numbers: average sentence length, count of hedge words, and how many readers complete the task on the first try. The SimpleEnglish repository publishes its own benchmark method for violation counts, and you can run its evals yourself before relying on the reported figures. For the reported results and their limits, see our skill analysis.
Where STE fits in a wider workflow
Controlled writing is one tool among several for reading and checking model output. Andrej Karpathy has argued that controlled text is the first rung of a ladder that runs up to diagrams, HTML pages and videos, covered in his four-format ladder. Used alone, STE cuts hedging and padding. Combined with review and tests, it makes AI-written documentation easier to trust. If your wider goal is cleaner AI prose, our piece on AI slop and the internet explains why the defaults drift toward filler in the first place.
Quick-start checklist
- Choose one document type to start with, such as error messages.
- Add the rule block to your project file, or install the skill.
- Rewrite one real document and read the diff for lost facts.
- Run the checker and fix what it flags.
- Ask one person to follow the steps cold.
- Keep the setup if it helps. Remove it where voice matters.
Related reading
- ASD-STE100 and the SimpleEnglish skill: benchmark and debate
- Agent skills: the complete guide
- CLAUDE.md vs SKILL.md vs MCP
- Skills vs hooks vs prompts: when to use each
- Karpathy's four formats for reading LLM output
- Slopocalypse: AI slop and the internet
This guide describes ideas from ASD-STE100 in our own words and is not the official standard. The SimpleEnglish skill is an unofficial, open-source project. Check its repository for current install steps before you rely on them.