SimpleEnglish

What It Does

SimpleEnglish is an agent skill that makes LLMs write and rewrite technical text under ASD-STE100 Simplified Technical English, the controlled language aerospace manufacturers have used since 1983 for maintenance documentation. The skill paraphrases all 53 numbered rules of Issue 9 (January 2025) with software examples: 20-word procedural and 25-word descriptive sentence limits, one word one meaning, simple tenses, approved modals only, condition before command. It targets developers and doc teams whose agents produce READMEs, runbooks, error messages, incident reports, and release notes. The repo ships the skill plus a deterministic regex linter, a benchmark harness with 176 committed raw generations across 11 models, a Claude Code plugin and output style, and a standalone prompt for hosts without skill support.

The Good

The benchmark is recomputable offline and the number holds. We re-linted all 168 baseline and skill generations in evals/results/raw/ with the repo's own ste_lint.py and got a mean reduction of 74.7% versus the claimed 74.6%, with per-model rows matching the published table within 0.3 percentage points. No API key, no model calls, just the committed artifacts. Almost no skill in this genre publishes raw evidence at all; this one lets you audit the headline claim yourself.

The effect is not a Claude-family artifact. The main matrix covers 7 Claude models (41.3% to 85.2% reduction), and a separate Pi run covers GLM-5.2 max (84.4%) and three GPT-5.6 variants (67.2% to 88.0%). Eleven models total, two providers beyond Anthropic, all showing the same direction. A blind pairwise judge preferred the skill output in 45 of 56 pairs with both text orders run to cancel position bias.

The eval harness has hygiene most vendor packs lack. A unit test asserts the baseline prompt cannot contain the skill text (a contamination guard), the judge pass runs both orders with no labels, and evals/results/RESULTS.md carries an "honest number warnings" section that names its own weaknesses: single judge model from the same family as the texts, one generation per cell, uneven reasoning-effort pinning (8 of 56 judge files record the setting). The skill itself states no tool can guarantee STE compliance.

Real standards work with a correction loop. Version 1.3.0 came from a full audit against the Issue 9 primary text, not blog summaries. Community audits were filed as issues and fixed: the fall part-of-speech bug (issue #3), the consistency pass grouping words with incompatible dictionary statuses (issue #4), and five wrong rulings (issue #13). Six external contributors have landed code. We verified the rule catalog contains exactly 53 numbered rules and that all 15 rule numbers cited in checklist.md exist in the catalog; the old "cites a nonexistent rules.md" bug (issues #2 and #7) has stayed fixed.

The documented contracts are implemented, not just promised. A 9-flag CLI command wrapped in backticks counts as one word under Rule 8.6 in the linter (a 21-word-looking sentence measured 8 words, correctly under the limit). Trailing conditions are flagged while condition-first forms are not (Rule 5.4). The 581-character description field stays under the 1024 limit with trigger phrases included.

Four distribution surfaces, all current. The skills.sh registry blob matches repo HEAD exactly (we installed for claude-code and hermes-agent in isolated HOMEs and both landed byte-identical copies plus a lock file with a content hash), the Claude plugin marketplace manifest passes claude plugin validate, an always-on output style ships for Claude Code, and prompts/system-prompt.md covers ChatGPT, Gemini, and .cursorrules users, with a roughly 60-token budget variant for tight prompts.

The Bad

No CI at all. The repo has no .github directory. The 7-test suite and the linter self-test exist and pass, but nothing runs them on push or pull request. Six issues and pull requests have sat unmerged since 2026-08-21, which is also the last commit; a test-enforcing CI gate is exactly what would make that queue safe to work through.

Release hygiene lags the content. The only git tag is v1.2.0 while every surface (SKILL.md metadata, plugin.json, marketplace.json, README badge) reads 1.3.0. There is no CHANGELOG file, so the version history lives only in commit messages. Anyone pinning "the latest release" gets a version two minors stale.

The package/ directory is undocumented. It holds 128 KB of raw ablation results (a "core" versus "core+dict" comparison on two models) and is mentioned nowhere: not in the README, not in RESULTS.md, not in the eval code. A cloner cannot tell what produced it or what it concluded. The open pull request #17 that would document it also flags a deeper tension: shipping a compressed dictionary-derived word list would falsify the README's claim that the repo "reproduces zero spec text or dictionary content", and the redistribution question is unresolved.

The linter has known blind spots. It does not flag em dashes (open issue #19) or passive voice, both admitted in the file header. Em dash overuse is one of the most reliable AI-writing tells, which makes the gap visible: the README's own "before" example contains one that the linter scores zero for.

The two condensed surfaces teach different rulings. prompts/system-prompt.md mandates make sure that for the check/verify/confirm set, while output-styles/simple-english.md says "pick one and keep it". Both are defensible readings of pragmatic versus strict mode, but a user who installs both the prompt and the output style gets contradictory instructions from the same project.

The benchmark matrix is Anthropic-heavy. Seven of the eleven tested models are Claude, the judge is Claude scoring Claude output, and there is no Gemini or open-weight model in either run. The Pi cross-check mitigates this, and the caveats own it, but the headline badges still say "benchmarked on 7 Claude models".

Smoke Test Results

We tested on the host (macOS 26.5.2, aarch64, Python 3.12.13, Node 24) after the sbx sandbox daemon reported it was not authenticated. Three runs: a clean-room registry install, a structural validation suite, and a functional pass over the linter, the unit tests, and the committed benchmark evidence.

Run A. Fresh clone and clean-room registry install

$ git clone --depth 1 https://github.com/AminBlg/SimpleEnglish /tmp/simpleenglish-fresh
✅ 31 commits, 8 contributors, 1.6 MB total, skills/ 40 KB
$ npx -y skills add AminBlg/SimpleEnglish --agent claude-code --skill simple-english --copy --yes
✅ lands SKILL.md + 3 references in ./.claude/skills/simple-english/ plus skills-lock.json (computedHash present)
$ diff -r .claude/skills/simple-english /tmp/simpleenglish-fresh/skills/simple-english
✅ byte-identical: the registry serves current HEAD, no stale blob
$ python3 evals/ste_lint.py --self-test
✅ "self-test OK: 12 violations in slop fixture, 0 in clean" with bare python3, zero pip installs

Pass rate: 4 of 4. The skill installs in one command with no dependencies beyond Node for the installer; the eval tooling is pure standard library.

Full fresh log ->

Run B. Sandbox with deps preinstalled (structural validation)

$ frontmatter check (name matches dir, description 581 chars, limit 1024)
✅ PASS
$ all 3 routed references exist (checklist.md, word-swaps.md, use-cases.md)
✅ PASS
$ rule catalog contains exactly 53 numbered rules (SKILL.md claims 53)
✅ PASS
$ all 15 checklist.md rule citations exist in the catalog
✅ PASS (old rules.md bug from issues #2/#7 stays fixed)
$ version consistency across SKILL.md, plugin.json, marketplace.json, README badge
✅ PASS (1.3.0 on all four surfaces)
$ release tag matches current version
❌ FAIL: only tag is v1.2.0, every surface reads 1.3.0
$ plugin.json and marketplace.json parse; claude plugin validate .
✅ PASS
$ README headline row matches RESULTS.md committed numbers
✅ PASS
$ raw generation count matches the claimed matrix
✅ PASS (56 baseline + 56 skill = 112)
$ npx skills add --agent hermes-agent (isolated HOME)
✅ PASS (lands in .hermes/skills/, byte-identical to HEAD)
$ npx skills use AminBlg/SimpleEnglish@simple-english
✅ PASS (emits the SKILL.md prompt envelope, 341 lines)
$ condensed surfaces ship and agree on the 20-word limit
✅ PASS

Pass rate: 16 of 17. The single failure is real: the release tag is a minor version behind the code. Everything structural passes, including both install targets and the plugin manifest.

Full with-deps log ->

Run C. Functional verification (linter, tests, benchmark reproduction)

$ python3 -m unittest evals.test_run_pi_bench -v
✅ Ran 7 tests in 0.003s, OK (includes the contamination guard: baseline prompt must not include the skill)
$ python3 evals/ste_lint.py --type descriptive <README's real "before" slop example>
✅ violations_total: 7, 16.28 per 100 words, longest sentence 26 words
$ python3 evals/ste_lint.py --type descriptive <README's "after" STE rewrite>
✅ violations_total: 0, 0.0 per 100 words, longest sentence 12 words
$ python3 evals/ste_lint.py --type procedural <edge cases: 9-flag code command + trailing conditions>
✅ sentence_over_limit: 0 (command counted as 8 words, Rule 8.6 honored), trailing_condition: 2 (Rule 5.4 honored)
$ python3 reproduce-headline.py (re-lint all 168 committed generations)
✅ mean reduction 74.7% vs claimed 74.6%; per-model rows match within 0.3 pp

Functional pass rate: 5 of 5. The linter discriminates correctly on inputs it has never seen, implements the Untouchables and condition-order contracts, and the headline benchmark number reproduces from committed artifacts alone.

Full functional log ->

What the runs tell you

Install integrity is flawless across two agent targets and the registry blob is current. The one structural failure is release hygiene, not content. Functionally, everything testable without live model generations passed, including an offline reproduction of the benchmark's core claim; what no run can tell you is how the skill behaves in your agent on your docs, and the repo's own 176-generation evidence is the best proxy for that in the genre.

Setup Walkthrough

1. Run npx skills add AminBlg/SimpleEnglish in your project. The installer detects installed agents and copies the skill folder (4 files, 40 KB) plus a skills-lock.json with a content hash.
2. For Claude Code, alternatively run claude plugin marketplace add AminBlg/SimpleEnglish then claude plugin install simple-english@simple-english. The plugin also ships an always-on output style: run /config, open Output style, pick simple-english.
3. For hosts with no skill support (ChatGPT, Gemini, .cursorrules), paste prompts/system-prompt.md into your system prompt or custom instructions; a roughly 60-token condensed version is included at the bottom of that file.
4. Hermes and OpenClaw users: the README does not name them, but the same installer handles --agent hermes-agent and we verified it lands a byte-identical copy in ./.hermes/skills/.
5. Optional verification: python3 evals/ste_lint.py --self-test inside a clone confirms the eval tooling with zero dependencies.

One transparency note: the recommended npx skills add path reports install counts to the skills.sh registry. A user flagged this as unexpected network activity in issue #1 ("README command invokes malware", closed as the CLI's telemetry, cross-referenced at vercel-labs/skills#1817). If you object to that beacon, clone and copy the skills/simple-english/ folder manually.

Alternatives

1. JuliusBrussee/caveman - output-style compression for token cost rather than clarity; different goal, opposite direction on grammar completeness.
2. A bare "write clearly" prompt - free and zero-install, but as the SimpleEnglish README argues, "clearly" is an opinion while "no sentence over 20 words" is a spec; only one of those is checkable.
3. Anthropic's writing and best-practices skills (reviewed here as anthropics/skills, agents-best-practices) - broader authoring guidance without a controlled-language rule set or a measurable compliance instrument.