Skip to content
Back to search

simple-english

MarketplaceWorks with Claude CodeGitHub

ASD-STE100 Simplified Technical English skill for clear, unambiguous technical writing.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aminblg-simpleenglish/badge.svg)](/listings/aminblg-simpleenglish)

HTML

<a href="/listings/aminblg-simpleenglish"><img src="/api/listings/aminblg-simpleenglish/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Any agent, with the [skills CLI](https://github.com/vercel-labs/skills):

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`](src/hooks/README.md).

No skill support? Paste the rule block of [`prompts/system-prompt.md`](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".

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines
  1. {
  2. "name": "simple-english",
  3. "owner": {
  4. "name": "AminBlg",
  5. "url": "https://github.com/AminBlg"
  6. },
  7. "description": "ASD-STE100 Simplified Technical English skill for clear, unambiguous technical writing.",
  8. "plugins": [
  9. {
  10. "name": "simple-english",
  11. "source": "./",
  12. "displayName": "Simple English",
  13. "description": "Write plain, layman-readable English with the discipline of ASD-STE100 Simplified Technical English: short sentences, one word one meaning, active voice, condition before command, terms defined at first use.",
  14. "version": "2.1.2",
  15. "author": {
  16. "name": "AminBlg"
  17. },
  18. "homepage": "https://github.com/AminBlg/SimpleEnglish",
  19. "repository": "https://github.com/AminBlg/SimpleEnglish",
  20. "license": "MIT",
  21. "keywords": ["technical-writing", "documentation", "ste", "asd-ste100"]
  22. }
  23. ]
  24. }
README.md · README · 164 lines
  1. <p align="center">
  2. <strong>✈️ your AI writes like a LinkedIn post. make it write like a Boeing manual.</strong>
  3. </p>
  4. <p align="center">
  5. An agent skill that makes LLMs write plain English with the discipline of <a href="https://www.asd-ste100.org/">ASD-STE100 Simplified Technical English</a>,<br>
  6. the controlled language aerospace has used since 1983 so that a tired mechanic cannot misread an instruction.<br>
  7. Layman-readable by default, STE-strict on request.
  8. </p>
  9. <p align="center">
  10. <a href="evals/results/rebuild-2026-09-02/RESULTS.md"><img src="https://img.shields.io/badge/reply_defects-%E2%88%9295%25_measured-brightgreen?style=flat" alt="95% fewer visible reply defects, measured"></a>
  11. <a href="evals/results/RESULTS.md"><img src="https://img.shields.io/badge/benchmarked_on-9_Claude_models-blueviolet?style=flat" alt="9 models benchmarked"></a>
  12. <a href="https://agentskills.io"><img src="https://img.shields.io/badge/SKILL.md-open_standard-blue?style=flat" alt="Agent Skills"></a>
  13. <a href="skills/simple-english/SKILL.md"><img src="https://img.shields.io/badge/version-2.1.2-blue?style=flat" alt="version 2.1.2"></a>
  14. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey?style=flat" alt="MIT"></a>
  15. <a href="https://github.com/AminBlg/SimpleEnglish/stargazers"><img src="https://img.shields.io/github/stars/AminBlg/SimpleEnglish?style=flat&logo=github&color=yellow" alt="GitHub stars"></a>
  16. </p>
  17. <p align="center">
  18. <a href="https://trendshift.io/repositories/97933?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-97933" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/97933/daily" alt="AminBlg%2FSimpleEnglish | Trendshift" width="250" height="55"/></a>
  19. </p>
  20. Works in every agent that reads the [Agent Skills standard](https://agentskills.io): Claude Code, Cursor, VS Code Copilot, OpenAI Codex, Gemini CLI, Goose, OpenCode, and about 25 more. One folder, no dependencies, MIT.
  21. ## Install
  22. Any agent, with the [skills CLI](https://github.com/vercel-labs/skills):
  23. ```bash
  24. npx skills add AminBlg/SimpleEnglish
  25. ```
  26. 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.
  27. Claude Code plugin, with the session hook and the output style:
  28. ```bash
  29. claude plugin marketplace add AminBlg/SimpleEnglish && claude plugin install simple-english@simple-english
  30. ```
  31. 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`.
  32. Codex plugin, with the session hook:
  33. ```bash
  34. codex plugin marketplace add AminBlg/SimpleEnglish
  35. codex plugin add simple-english@simple-english
  36. ```
  37. Codex asks you to trust the hook before its first run. The hooks need Node.js. Details in [`src/hooks/README.md`](src/hooks/README.md).
  38. No skill support? Paste the rule block of [`prompts/system-prompt.md`](prompts/system-prompt.md) into your system prompt, `AGENTS.md`, or `.cursorrules`. The page ends with a 60-token version for tight budgets.
  39. Then ask for any technical writing, or say "rewrite this with simple-english".
  40. ## See it
  41. Left is real, unedited Claude output. Right is the same model with the skill loaded.
  42. <table>
  43. <tr>
  44. <th width="50%">Without skill</th>
  45. <th width="50%">With skill</th>
  46. </tr>
  47. <tr>
  48. <td valign="top">
  49. > Leveraging sqlpipe's robust architecture, users can seamlessly synchronize their Postgres tables to S3 with minimal configuration overhead. Before getting started, you should ensure that your AWS credentials have been properly configured — this is crucial for avoiding frustrating permission issues down the line.
  50. </td>
  51. <td valign="top">
  52. > sqlpipe copies your Postgres tables to S3. It needs one configuration file.
  53. >
  54. > Before you start, make sure that your AWS credentials are correct. If they are not, S3 rejects the upload with a permission error.
  55. </td>
  56. </tr>
  57. </table>
  58. More rewrites in [`examples/before-after.md`](examples/before-after.md): READMEs, runbooks, incident reports, error messages, release notes.
  59. ## Benchmarks
  60. 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.
  61. Replies, 8 chat questions with a jargon term each, two runs, [raw files and tables](evals/results/rebuild-2026-09-02/RESULTS.md). 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 or later. A blind judge preferred 2.0.1 over 2.0.0 in 14 of 16 pairs.
  62. | Condition | words | sentences | em-dashes | bold | headers | bullets |
  63. |---|---:|---:|---:|---:|---:|---:|
  64. | no skill | 216 | 16.8 | 62 | 79 | 25 | 52 |
  65. | 2.0.0 | 184 | 14.4 | 43 | 72 | 4 | 52 |
  66. | 2.0.1 | 146 | 7.9 | 5 | 2 | 0 | 4 |
  67. 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.
  68. 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.
  69. | Condition | viol/100w | Reduction |
  70. |---|---:|---:|
  71. | no skill | 4.09 | |
  72. | 1.3.0 | 2.11 | 48% |
  73. | 2.0.0 | 1.70 | 58% |
  74. | 2.0.1 | 0.91 | 78% |
  75. The linter history: 81.3% fewer linter violations across 9 Claude models (144 generations, [RESULTS.md](evals/results/RESULTS.md)), plus Pi, opencode, and OpenAI runs in [`evals/results/`](evals/results/). Those numbers reproduce. A [2026-09-02 audit](evals/results/WHY-USELESS-2026-09-02.md) showed that they measure rule obedience, not what a reader sees, which is why 2.0.1 reports the reply counts above.
  76. ## The rules
  77. Two registers in [`SKILL.md`](skills/simple-english/SKILL.md), about 1,700 tokens. The 53 numbered rules of Issue 9 live in [`rule-catalog.md`](skills/simple-english/references/rule-catalog.md) for check mode and Strict mode.
  78. The reply, every chat answer:
  79. | Rule | What it kills |
  80. |---|---|
  81. | Prose by default: a list or a table only for content of that shape, no bold | The wall of formatting around a one-line answer |
  82. | First sentence answers | The preamble |
  83. | No em-dashes | The spliced half-thought |
  84. | Define a concept term in a few words | Jargon the reader has to look up |
  85. | No contractions, openers, or closers | "Great question!" and "Hope this helps!" |
  86. The document: docs, READMEs, runbooks, error messages, release notes:
  87. | Rule | What it kills |
  88. |---|---|
  89. | Max 20 words per instruction, 25 per description | The run-on sentence |
  90. | Condition before command | Trailing "...if the flag is set" that readers execute too late |
  91. | Simple tenses, active voice | "has been updated", ", making it easy to..." |
  92. | No should/would/may/might | Hedging. `can`, `will`, `must` survive |
  93. | One word = one meaning, whole document | check/verify/confirm/validate roulette |
  94. | Keep articles, keep "that" | Telegraph style. STE is short, not terse |
  95. | No bold lead-ins, no heading over two sentences | Decoration that hides the fact |
  96. | State the fact, not its importance | "crucial", "robust", "not just X, it is Y" |
  97. Two modes. Plain, the default, is all of the above. Strict adds the STE dictionary discipline from [`strict-vocabulary.md`](skills/simple-english/references/strict-vocabulary.md) when you name STE, ASD-STE100, or compliance. The reply stays Plain in every mode.
  98. ## FAQ
  99. 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](https://www.asd-ste100.org/request.html).
  100. 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.
  101. Why not just prompt "write clearly"? "Clearly" is an opinion. "No sentence over 20 words" is a spec. Agents follow specs.
  102. 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.
  103. How was it built? Against the primary Issue 9 text, not summaries. A community audit ([#4](https://github.com/AminBlg/SimpleEnglish/issues/4)) checked the vocabulary tables against the dictionary. Scenarios and recorded results: [`evals/pressure-tests.md`](evals/pressure-tests.md).
  104. ## Star history
  105. [![Star History Chart](https://api.star-history.com/chart?repos=AminBlg/SimpleEnglish&type=date&legend=top-left)](https://www.star-history.com/?repos=AminBlg%2FSimpleEnglish&type=date&legend=top-left)
  106. ## Word-choice linter
  107. `evals/ste_lint.py` measures the mechanical rules and cannot see word choice. [`tools/ste-dictionary/`](tools/ste-dictionary/README.md) 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.
  108. ## Contributing
  109. Open an issue for questions and bug reports. Pull requests are welcome. A change that moves a published number ships the raw files with it, and `python3 evals/check_numbers.py` must pass. Run `python3 evals/ste_lint.py --self-test` before you push. Say in the PR whether an agent wrote the code, and do not add attribution trailers.
  110. ## License
  111. MIT for everything here. The repo paraphrases the rules for teaching and reproduces no spec text or dictionary content. Unofficial project, not affiliated with or endorsed by ASD or STEMG. ASD-STE100 is a registered trademark of ASD.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.