Simplified Technical English

What job it is for, and why this one

Use it where ambiguity is the failure mode: procedures, safety-relevant instructions, setup steps and reference documentation read by people who are not native speakers. Its value is that its rules are countable. Sentences have numeric ceilings, a substitution table names the words to replace, and there is a list of phrases to delete outright. A reviewer can check the output against the rules instead of arguing about taste.

It also takes a position most rewriting prompts avoid: it refuses to shorten by dropping facts, refuses to touch quoted text, code, commands and error messages, and marks a missing value rather than inventing one. That stance is why it is a reasonable thing to put in front of documentation that has to stay true.

When it is the wrong tool

Do not point it at marketing copy, landing pages, essays or anything where voice is part of the job. The skill says this itself: taken in full, the rule set strips personality by design, and it offers a reduced mode for text that has a voice worth keeping. If you run the full pass on a page whose whole purpose is persuasion, you get correct sentences that no longer sell anything.

It is the wrong instrument for literature, legal wording with operative force, or anything where a phrase is binding rather than descriptive. A controlled language exists to remove interpretation, and a contract sometimes depends on exactly the interpretation it would remove.

Finally, do not treat the name as a guarantee. Its own text states that it is inspired by the standard and is not the official specification, and the front matter names the technique rather than claiming certification. If a deliverable has to be compliant with the actual standard, this is not evidence of that, and no number of passing rules changes it.

What it needs, and what comes back

The input is text, a file path, or the word audit followed by text. That is the whole interface, and it produces two different things depending on which you ask for. In rewrite mode it returns the rewritten text first and then a short list of the rule violations it found. In audit mode it returns only the violation report, one line per finding with the offending text and a suggested fix.

Two behaviours matter for planning. The instructions ask the assistant to identify violations during review, but the final response must show the rewrite first and the violation list afterward. Compare both with the original before accepting a change. The instructions also exclude quoted material, code, commands and error messages from simplification. Check that those exact strings survived: this is an instruction to the assistant, not an enforced protection. A document built around them may change less than you expect.

There is no prerequisite beyond the text itself: no network access, no script, no project layout. The one structural prerequisite is a reader who understands the domain, because the skill preserves facts but cannot tell you that a sentence was describing the wrong fact in the first place.

Tool support, permissions and dependencies

The published record labels the source check of this project as verified, and the entry file carries the technique name in its own front matter rather than a compatibility list. It is a single instruction document with no scripts, no commands and no packages, so the tool question reduces to whether your agent reads a skill folder at all.

Its permission footprint is among the smallest in this directory, and that is the point of mentioning it: the skill needs to read the text you give it and write the replacement. It does not need to run anything, reach the network, or touch files outside whatever you point it at. The one thing to watch is the same as for any rewrite: if you hand it a file path, the agent is acting on a real file, so decide whether the rewrite lands in place or beside the original before you start.

Compared with editing it yourself

A competent editor does more than this skill: they notice that a paragraph is answering a question the reader never asked, and they will tell you to delete it. The skill cannot do that, because deleting a paragraph would delete facts, which its own rules forbid. So if your document is too long because it says too much, a controlled-language pass will make it tighter sentence by sentence and leave it just as long.

For a long document, a shared rule list gives you a reference for checking terminology and sentence patterns across procedures. That is a reason to try the skill, not evidence that it outperforms a human editor or stays consistent automatically. An assistant may miss a rule or apply it unevenly. Use your own judgement for structure and cuts, then compare the suggested edits across sections before accepting them.

It also helps to ask for the audit rather than the rewrite on text you care about. The audit gives you the rule violations with your own sentences quoted back, which is a review you can accept or reject line by line. The rewrite asks you to trust a whole new document at once.

How to check the result yourself

A controlled-language rewrite fails in a specific way: it reads beautifully and has quietly lost a number, a condition or a warning. So check the facts, not the prose.

• Count the facts before and after. Put the original and the rewrite side by side and mark every number, unit, condition and negation. A lost negation is the failure with the worst consequences.
• Check that quoted material, code, commands and error messages are identical character for character. They were supposed to be untouched, so any difference is a defect rather than a style choice.
• Re-run the skill on its own output in audit mode. If it reports violations in text it just produced under the same rules, the pass was not finished.
• Where a warning or an instruction was reordered, check that it still comes before the action it guards. Putting the command first is a rule, and getting it backwards is how a safety instruction becomes a hazard.
• Have one person who did not write the source read only the result, and ask them to restate what to do. Comprehension is the thing being bought here, and it is the only measure that is not a proxy.

Source, version and what was actually read

The judgements above were made against the single commit this page shows. If that record moves to another commit, this guide stops being displayed rather than describing a version nobody re-read.

What was read: the entry file of the project at that commit, which contains the rule set, the substitution table, the modes, the refusal list and the attribution note. The licence file of the repository was read as part of the publication review, and the source check of the record is labelled verified. Nothing was installed or executed, no text was put through the skill, and no output was compared against a real document. The claims above about how a rewrite behaves are read from the instructions, not observed from a run.