Force LLMs to write technical docs in ASD-STE100 English

✈️ your AI writes like a LinkedIn post. make it write like a Boeing manual.

An agent skill that makes LLMs write plain English with the discipline of ASD-STE100 Simplified Technical English,
the controlled language aerospace has used since 1983 so that a tired mechanic cannot misread an instruction.
Layman-readable by default, STE-strict on request.

Works in every agent that reads the Agent Skills standard: Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose, OpenCode, and about 25 more. One folder, no dependencies, MIT.

Install

Any agent, with the skills CLI:

npx skills add AminBlg/SimpleEnglish

This installs the skill only. It does not install the session hook or the output style below, so setting outputStyle to simple-english:simple-english without the plugin does nothing. Use the Claude Code plugin for those.

Claude Code plugin, with the session hook and the output style:

claude plugin marketplace add AminBlg/SimpleEnglish && claude plugin install simple-english@simple-english

The output style is named simple-english:simple-english. The short name does not resolve. Select it with /config under Output style, or put {"outputStyle": "simple-english:simple-english"} in ~/.claude/settings.json.

Codex plugin, with the session hook:

codex plugin marketplace add AminBlg/SimpleEnglish
codex plugin add simple-english@simple-english

Codex asks you to trust the hook before its first run. The hooks need Node.js. Details in src/hooks/README.md.

No skill support? Paste the rule block of prompts/system-prompt.md into your system prompt, AGENTS.md, or .cursorrules. The page ends with a 60-token version for tight budgets.

Then ask for any technical writing, or say "rewrite this with simple-english".

See it

Left is real, unedited Claude output. Right is the same model with the skill loaded.

More rewrites in examples/before-after.md: READMEs, runbooks, incident reports, error messages, release notes.

Benchmarks

Every number below is recomputed from the committed raw files by python3 evals/check_numbers.py, which CI runs on every push. All Claude runs: claude-sonnet-4-6, low effort, no settings loaded. Judges are Claude models on Claude text, so family bias is possible.

Replies, 8 chat questions with a jargon term each, two runs, raw files and tables. Counts are totals over the 16 replies. 95% fewer visible defects (em-dashes, bold, headers, bullets) with 2.0.1 than with no skill (218 → 11). These counts come from the 2026-09-02 runs of 2.0.1, which still had the five-sentence reply cap that 2.1.0 removed. No run exists yet for 2.1.0. A blind judge preferred 2.0.1 over 2.0.0 in 14 of 16 pairs.

On gpt-4.1-mini the same 8 questions went from 23 sentences, 64 bold spans, and 101 bullets per 8 replies. With 2.0.1 they went to 5.2 sentences and zero formatting.

Documents, the 8 sqlpipe writing tasks scored with the STE linter, one run per cell. One run moves by about 0.5 on this model, so read the rows as parity or better, not as a ranking.

The linter history: 81.3% fewer linter violations across 9 Claude models (144 generations, RESULTS.md), plus Pi, opencode, and OpenAI runs in evals/results/. Those numbers reproduce. A 2026-09-02 audit showed that they measure rule obedience, not what a reader sees, which is why 2.0.1 reports the reply counts above.

The rules

Two registers in SKILL.md, about 1,700 tokens. The 53 numbered rules of Issue 9 live in rule-catalog.md for check mode and Strict mode.

The reply, every chat answer:

The document: docs, READMEs, runbooks, error messages, release notes:

Two modes. Plain, the default, is all of the above. Strict adds the STE dictionary discipline from strict-vocabulary.md when you name STE, ASD-STE100, or compliance. The reply stays Plain in every mode.

FAQ

Does this make output STE-certified? No. Nothing does, because ASD certifies no tool. Strict mode gets close. Word-level rulings live in the official standard, a free download.

Will my docs sound robotic? They will sound like Airbus manuals: flat and impossible to misread. For docs that is the whole point. Keep your voice for your blog.

Why not just prompt "write clearly"? "Clearly" is an opinion. "No sentence over 20 words" is a spec. Agents follow specs.

Why a 40-year-old aerospace standard? It is maintained (Issue 9, January 2025), numbered, and testable. It is also a near-perfect negative of every AI writing tell.

How was it built? Against the primary Issue 9 text, not summaries. A community audit (#4) checked the vocabulary tables against the dictionary. Scenarios and recorded results: evals/pressure-tests.md.

Star history

Word-choice linter

evals/ste_lint.py measures the mechanical rules and cannot see word choice. tools/ste-dictionary/ holds an extractor that builds the word lists from your own copy of the free Issue 9 PDF. A linter reads them. The repository ships the tool and no dictionary content, because the standard forbids reproduction without written authority from ASD.

examples/before-after.md

Before / after

Every "before" below is genuine unedited AI output (Claude Sonnet, July 2026, no skill loaded). Every "after" is the same content with the skill applied.

1. README introduction (descriptive)

Before - 1 sentence of 30 words, one of 33, a dangling "-ing" clause:

sqlpipe is a command-line tool for syncing PostgreSQL tables to Amazon S3 as Parquet files. It's built for teams who need a lightweight way to move data out of Postgres into a data lake without standing up a full ETL platform. sqlpipe connects directly to your database, reads table data in batches, converts it to columnar Parquet, and writes the result to an S3 bucket of your choosing. It supports full table snapshots as well as incremental syncs based on a watermark column, so you can run it once for a backfill or schedule it to run continuously. Configuration lives in a single YAML file, making it easy to version-control your sync definitions alongside the rest of your infrastructure code.

After - max sentence 21 words, one topic per paragraph:

sqlpipe is a command-line tool that copies PostgreSQL tables to Amazon S3 as Parquet files. It moves data into a data lake without a full ETL platform.

sqlpipe connects to your database and reads each table in batches. It converts the batches to Parquet and writes them to your S3 bucket. It can copy a full table, or only the new rows after a watermark column. Run it once for a backfill, or on a schedule.

The configuration is one YAML file. You can keep this file in version control with your infrastructure code.

2. Troubleshooting section (procedural)

Before - 40-word sentences, contractions, conditions after commands:

Connection timeouts. If sqlpipe hangs or fails with dial tcp: i/o timeout, check that the host running sqlpipe can reach the Postgres port (usually 5432) - this is often a security group or firewall rule blocking the connection. If you're connecting to a managed database (RDS, Cloud SQL, etc.), confirm the instance allows connections from sqlpipe's IP. You can also try increasing source.connect_timeout_seconds in your config, since a slow network path can trip the default timeout even when the connection eventually succeeds.

After - one instruction per sentence, condition first, one verb for "check":

Connection timeouts. sqlpipe stops with dial tcp: i/o timeout when it cannot reach the Postgres port (5432 by default).

1. Make sure that the host that runs sqlpipe can reach the Postgres port. A firewall or security group usually blocks it.
2. If the database is managed (RDS, Cloud SQL), make sure that the instance accepts connections from the IP of sqlpipe.
3. If the network is slow, increase source.connect_timeout_seconds in the configuration.

3. Error message

Before:

Oops! Something went wrong while attempting to establish a connection to the database. Please ensure your credentials have been properly configured and try again, or reach out to your administrator if the issue persists.

After:

Connection to the database failed: the password for user app was not correct.
Set DB_PASSWORD to the correct value, then connect again.
If the error continues, ask your database administrator for access.

4. Incident report (descriptive, simple past)

Before:

We have identified an issue that may have impacted some users' ability to access the service. Our team has been working diligently to resolve this and services have now been fully restored. We sincerely apologize for any inconvenience this may have caused.

After:

Between 14:02 and 14:31 UTC, 12% of requests to the API failed with HTTP 502. A deploy at 14:00 removed the cache warmup step, and the cache nodes overloaded. We reverted the deploy at 14:27. All requests succeeded from 14:31. We will add a warmup check to the deploy pipeline this week.

5. Breaking change in release notes

Before:

Please note that we've made some changes to the users endpoint that may require updates to your integration. The name field has been deprecated in favor of separate first_name and last_name fields, so you'll want to update your code accordingly.

After:

Breaking: Update your calls to /v2/users. The name field split into first_name and last_name. The name field will return null after 2026-09-01.

tools/ste-dictionary/README.md

ASD-STE100 word lists, made on your machine

This directory holds an extractor and a word-choice linter. It holds no
dictionary content. ASD-STE100 Issue 9 states on page 2 that no reproduction
of the standard, in whole or in part, is permitted without written authority
from ASD. So the repository ships the tool, and you make the word lists from
your own copy of the free PDF.

Make the word lists

1. Request the free PDF at https://www.asd-ste100.org/request.html.
2. Convert it to text: pdftotext -layout ASD-STE100_ISSUE9.pdf ste9.txt.
3. Parse the dictionary: python3 parse_dict.py ste9.txt. This writes dict.json.
4. Emit the lists: python3 emit.py .. This writes approved.txt (841 rows) and not-approved.tsv (1,297 rows).

The output is deterministic. On 2026-09-04 the two files matched the reference
run byte for byte. All four generated files are in .gitignore. Do not commit
them.

Lint word choice

evals/ste_lint.py measures the mechanical rules. It does not see word choice.
This linter reads not-approved.tsv and reports each word that the standard
does not approve, with the approved alternatives. It also counts the LLM-tell
words from evals/slop.tsv as a separate number.

python3 ste_dict_lint.py file.md
python3 ste_dict_lint.py --self-test

Known limit: the match is on the base form and simple inflections, with no
part-of-speech disambiguation. Numbers from this tool compare two texts run
through the same version. They are not a compliance verdict.

COMPRESSION-RESEARCH.md records why the lists are plain text and not a
symbolic notation: symbolic schemes did not transfer across model families in
the surveyed studies.