From 06e9e4ee7580a72c1ead1d760fb41c979a2579de Mon Sep 17 00:00:00 2001 From: Sam Rolfe Date: Mon, 27 Jul 2026 20:40:03 +1000 Subject: [PATCH] Add ste-writing skill (STE100 Simplified Technical English) --- skills/ste-writing/SKILL.md | 53 +++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 skills/ste-writing/SKILL.md diff --git a/skills/ste-writing/SKILL.md b/skills/ste-writing/SKILL.md new file mode 100644 index 0000000..dbd17ca --- /dev/null +++ b/skills/ste-writing/SKILL.md @@ -0,0 +1,53 @@ +--- +name: ste-writing +description: Rewrite prose (docs, READMEs, PR descriptions, error messages, release notes, comments — never code) into ASD-STE100 Simplified Technical English to remove "AI slop". Use when asked to make writing not sound like AI, make docs clear or plain, enforce a controlled writing style, or write technical documentation that reads human. Two modes — strict (procedures/safety) and STE-flavored (general prose). +--- + +# ste-writing + +Write prose in ASD-STE100 Simplified Technical English. This applies to documentation, READMEs, pull-request text, error messages, release notes, and comments. It does not apply to code, identifiers, or command syntax. It is not for marketing copy, essays, or anything that needs a voice — STE strips voice on purpose. + +## Rules + +WORDS +- Use one name for one thing. Do not call the same item by two different names. +- Use the short common word: start (not begin/commence/initiate), use (not utilize/leverage), help (not facilitate), make sure (not ensure), before (not prior to), after (not subsequent to), about (not regarding/concerning), get (not obtain/acquire), show (not demonstrate), also (not additionally/furthermore/moreover). +- Give each word one meaning. "fall" means to move down, not to decrease. +- No marketing adjectives: seamless, robust, powerful, cutting-edge, effortless, world-class, next-generation, revolutionary. +- American spelling. + +VERBS +- Active voice. "the parser reads the file", not "the file is read by the parser". +- Use a verb for an action. "analyze the log", not "perform an analysis of the log". +- No stacked auxiliaries. Not "it is important to note that this may help to improve". Write "this improves X". +- No "-ing" main verb where a simple tense works. + +SENTENCES +- One instruction per sentence. Max 20 words (instruction), max 25 (descriptive). +- No contractions. Use articles: a, an, the, this, these. + +PUNCTUATION +- No semicolons. Write two sentences. (Note: the em dash is not banned by STE, only the semicolon is — add "no em dash" yourself if you want it gone.) + +STRUCTURE +- One topic per paragraph, max six sentences. For steps, use a numbered vertical list, one action per item, imperative form. Put a condition before its command. + +Write only the requested text. No preamble, no summary, no closing remarks. + +## Modes + +- **strict** — procedures, runbooks, safety text, error messages: apply every rule and both length caps. +- **STE-flavored** — general prose (READMEs, PR descriptions, docs): apply the sentence, paragraph, active-voice, and no-phrasal-verb discipline; relax the ~900-word dictionary lockdown so the text keeps enough range to read naturally. + +## Self-lint (run before returning text) + +1. Any sentence over 20 words? Split it. +2. Any semicolon? Replace with a period. +3. Any contraction? Expand it. +4. Any passive voice with a known actor? Make it active. +5. Any "-ing" main verb, nominalization ("perform an analysis"), or phrasal verb ("spin up")? Replace with a plain verb. +6. Same thing named two ways? Pick one name. + +The mechanical rules above are lintable and are what removes slop. Full STE also needs human judgment (the right technical noun, whether a sentence "makes good sense") — a checker cannot certify that, and slop is not about that. This skill fixes the FORM of slop. It cannot make a hollow paragraph true. + +Free official standard (do not paste it in full; it is copyrighted): https://asd-ste100.org