Skip to content
Back to search

simplified-technical-english

An Agent Skill that makes an LLM write in ASD-STE100 Simplified Technical English. Rules, approved word list, and a check tool.

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/0xpili--simplified-technical-english/badge.svg)](/listings/0xpili--simplified-technical-english)

HTML

<a href="/listings/0xpili--simplified-technical-english"><img src="/api/listings/0xpili--simplified-technical-english/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

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

1. Clone this repository into your skills folder:

git clone https://github.com/0xpili/simplified-technical-english.git ~/.claude/skills/simplified-technical-english

2. Tell Claude to write or examine technical text in STE. 3. Claude finds the skill and obeys the rules.

You can also start the skill directly. Type `/simplified-technical-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.

SKILL.md · Manifest · 124 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: simplified-technical-english
  3. description: Writes and rewrites text in Simplified Technical English (ASD-STE100), a controlled language for clear technical documentation. Use when the user asks for STE, Simplified Technical English, controlled language, or plain technical writing, and when the user asks to write, rewrite, review, or check technical documentation, procedures, manuals, instructions, warnings, or reports.
  4. license: MIT for the text of this skill. The word list in references/word-list.md comes from the ASD-STE100 dictionary, which is the property of ASD. Refer to NOTICE.md.
  5. metadata:
  6. source-specification: ASD-STE100 Issue 7 (2017-01-25)
  7. ---
  8. # Simplified Technical English
  9. This skill makes you write in Simplified Technical English (STE).
  10. STE is a controlled language for technical documentation.
  11. The specification ASD-STE100 gives 53 writing rules and a dictionary of approved words.
  12. Text in STE is clear to readers who do not know much English.
  13. Obey the rules in this file for all the technical text that you write.
  14. The rules in this file are the most important rules.
  15. The full set of rules is in `references/writing-rules.md`.
  16. The approved words are in `references/word-list.md`.
  17. ## Scope
  18. Apply STE to technical output: documentation, procedures, manuals, instructions, reports, error messages, and answers about technical subjects.
  19. Do not apply STE to:
  20. - Marketing text or brand text
  21. - Poems, stories, or conversation
  22. - Code blocks, identifiers, commands, file paths, and quoted error messages
  23. - Quoted text and official names of products, parts, and documents.
  24. If the user asks for a different style, the request of the user wins.
  25. ## Step 1: Classify the text
  26. Before you write, classify each part of the text:
  27. - **Procedural text** tells the reader to do something. Example: "Remove the four bolts."
  28. - **Descriptive text** gives information. Example: "The pump supplies fuel to the engine."
  29. The two types have different limits. Do not mix the two types in one paragraph.
  30. ## Step 2: Obey the verb rules
  31. - Use only these verb forms: infinitive, imperative, simple present, simple past, future with "will", and past participle as an adjective.
  32. - Do not use the "-ing" form of a verb. Approved "-ing" words are only: mating, missing, remaining, lighting, opening, routing, servicing, during.
  33. - Do not use a helping verb with a past participle. Write "the operator adjusted the linkage", not "the operator has adjusted the linkage".
  34. - Use the active voice. Write "a relay connects the circuits", not "the circuits are connected by a relay".
  35. - In procedures, use the imperative. Write "Set the switch to ON."
  36. - If there is no agent, use "you" or "we" as the subject.
  37. - Use only "can", "must", and "will" as helping verbs. Do not use "should", "would", "may", "might", or "shall".
  38. - A past participle after "is" or "are" shows a condition and is permitted. "The wires are disconnected."
  39. ## Step 3: Obey the sentence rules
  40. - Procedural sentences: maximum 20 words.
  41. - Descriptive sentences: maximum 25 words.
  42. - Paragraphs: maximum 6 sentences, and only one topic.
  43. - Write only one instruction in each sentence. Two actions are permitted only when they occur at the same time.
  44. - Write only one topic in each sentence.
  45. - When a condition comes before a command, put a comma after the condition. "If the light comes on, stop the engine."
  46. - Keep the articles, the subjects, the verbs, and the conjunction "that". Write "make sure that the file exists".
  47. - Do not use contractions. Write "do not", not "don't".
  48. - Do not use semicolons. Write two sentences.
  49. - Use a vertical list for complex text. In a list of commands with "not", write "not" again in each item.
  50. ## Step 4: Obey the word rules
  51. - Use only: approved words from `references/word-list.md`, technical names, and technical verbs.
  52. - A technical name is the official name of a part, tool, material, system, document, or term of your subject. Examples: "engine", "firewall", "torque wrench", "SKILL.md".
  53. - Use an approved word only as its given part of speech. "Test" is a noun, not a verb. Write "do a test", not "test the system".
  54. - Use one name for one item in the full text. Do not change between names for the same item.
  55. - Write noun clusters of maximum three words. Break long clusters with "of", "on", "in", or "for".
  56. - Do not make phrasal verbs. Write "extinguish the fire", not "put out the fire".
  57. - Do not use vague words. Write the specific quantity, name, or action.
  58. - Use American English spelling.
  59. - Common replacements are in `references/substitutions.md`.
  60. ## Step 5: Write safety instructions correctly
  61. - Use "WARNING" for a risk of injury or death to persons.
  62. - Use "CAUTION" for a risk of damage to objects.
  63. - Start with a simple command or condition. Then give the risk.
  64. - Example: "WARNING: Do not touch the connector. The connector can have a dangerous voltage."
  65. ## Step 6: Check your text
  66. After you write, check your text. Do these steps:
  67. 1. If you can run scripts, run: `python3 scripts/ste_check.py --mode <procedural|descriptive> <file>`.
  68. 2. If you cannot run scripts, do a manual scan of the checklist below.
  69. 3. Correct each error.
  70. 4. Check the text again. Stop only when the text has no errors.
  71. Manual scan checklist:
  72. - Find semicolons and contractions. Remove them.
  73. - Find "has", "have", and "had" before a past participle. Use the simple past tense.
  74. - Find "should", "would", "may", "might", and "shall". Replace them or remove them.
  75. - Find "-ing" words that are not approved and are not in technical names. Rewrite them.
  76. - Find passive voice. Make the agent the subject, or use the imperative.
  77. - Count the words in the longest sentences. Divide sentences that are too long.
  78. - Count the sentences in each paragraph. Divide paragraphs that have more than 6 sentences.
  79. - Find words that are not approved and are not technical names. Replace them.
  80. The check tool cannot find all the errors.
  81. The tool cannot know if a word has its approved meaning.
  82. You must also compare your words with `references/word-list.md`.
  83. ## Reference files
  84. - `references/writing-rules.md` — all 53 rules and 4 recommendations, with examples. Read this file when you rewrite a document or when a rule is not clear.
  85. - `references/word-list.md` — the 869 approved words with their parts of speech and forms.
  86. - `references/substitutions.md` — replacements for frequent unapproved words, and the categories of technical names and technical verbs.
  87. - `examples/before-after.md` — examples of text before and after the change to STE.
  88. ## Basis
  89. The source of this skill is ASD-STE100 Issue 7 (2017).
  90. ASD releases new issues of the specification.
  91. You can get the specification free of charge from https://www.asd-ste100.org.
  92. This skill is not an official ASD document.
  93. This skill cannot make sure that your text obeys the official specification fully.
  94. Refer to NOTICE.md for the copyright information.
README.md · README · 83 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Simplified Technical English skill
  2. This skill makes an LLM write in Simplified Technical English (STE).
  3. STE is a controlled language for technical documentation.
  4. The specification ASD-STE100 gives the rules of STE and its dictionary.
  5. The aerospace and defense industries use STE for their manuals.
  6. Text in STE is clear, short, and easy to translate.
  7. The skill obeys the rules that it gives. This README is in STE.
  8. ## Example
  9. Text before the change:
  10. > Prior to commencing the installation, it should be ensured that all
  11. > components have been thoroughly inspected for damage.
  12. Text after the change:
  13. > Before you start the installation, examine all the components for damage.
  14. ## Contents of this repository
  15. | File | Function |
  16. |---|---|
  17. | `SKILL.md` | The primary instructions for the LLM |
  18. | `references/writing-rules.md` | The 53 writing rules, with examples |
  19. | `references/word-list.md` | The 869 approved words |
  20. | `references/substitutions.md` | Replacements for frequent unapproved words |
  21. | `examples/before-after.md` | Examples of text before and after the change |
  22. | `scripts/ste_check.py` | A check tool for the STE rules |
  23. | `NOTICE.md` | Copyright information |
  24. ## How to install the skill for Claude
  25. 1. Clone this repository into your skills folder:
  26. git clone https://github.com/0xpili/simplified-technical-english.git ~/.claude/skills/simplified-technical-english
  27. 2. Tell Claude to write or examine technical text in STE.
  28. 3. Claude finds the skill and obeys the rules.
  29. You can also start the skill directly. Type `/simplified-technical-english`.
  30. ## How to use the skill with a different LLM
  31. 1. Open `SKILL.md`. Copy its text into the system prompt of the LLM.
  32. 2. If the LLM accepts more text, add the text of `references/substitutions.md`.
  33. 3. For the best results, also add the text of `references/word-list.md`.
  34. 4. Tell the LLM to write technical text.
  35. ## How to do a check of a text
  36. Run the check tool on a file or on standard input:
  37. python3 scripts/ste_check.py --mode procedural draft.txt
  38. python3 scripts/ste_check.py --mode descriptive chapter.md
  39. The tool finds these errors:
  40. - Sentences that have too many words
  41. - Paragraphs that have more than six sentences
  42. - Verb forms that are not approved, and the passive voice
  43. - Semicolons, contractions, and unapproved helping verbs
  44. - Words that are not in the approved word list.
  45. The tool uses only Python 3. The tool shows each error and its rule number.
  46. ## Limits of the skill
  47. The tool cannot find all the errors.
  48. The tool cannot know if a word has its approved meaning.
  49. A person who knows STE must also examine an important text.
  50. This skill is not an official ASD document.
  51. This skill cannot make sure that your text obeys the official specification fully.
  52. ## Source and copyright
  53. The source of this skill is ASD-STE100 Issue 7 (2017).
  54. ASD releases new issues of the specification.
  55. You can get the specification free of charge from https://www.asd-ste100.org.
  56. The dictionary of ASD-STE100 is the property of ASD. Refer to `NOTICE.md`.
  57. The text of this skill and its scripts have the MIT license. Refer to `LICENSE`.

Ratings and comments

Sign in to rate this skill.

Sign in

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