ste-writing
Skill62 starsChanged 2 months agoMITView on GitHub
Write or rewrite prose that a reader must act on, such as reports to the user, PR descriptions, and documentation, with ASD-STE100-derived rules that give each sentence one reading.
13 other projects use a version of this.
Adopted by
Most recently taken up by
- tonkeeper/tonkeeper-webtheir own version, first seen Nov 9, 2026
- LeonardiFranco/skillstheir own version, first seen Nov 8, 2026
- xiduzo/wtftheir own version, first seen Nov 8, 2026
- vstorm-co/agenticostheir own version, first seen Oct 16, 2026
- norton77930/understanding-ai-outputstheir own version, first seen Oct 11, 2026
- berkeley-humanoids/skillstheir own version, first seen Oct 9, 2026
Other versions13 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 13
- tonkeeper/tonkeeper-web★ 448same name
- vstorm-co/agenticos★ 241same name
- xiduzo/wtf★ 7same name
- berkeley-humanoids/skills★ 4same name
- berkeley-humanoids/Skills★ 4same name
- norton77930/understanding-ai-outputs★ 3same name
- 1fc0nfig/ste-writing★ 2same name
- joshua-noel/skills★ 2same name
- TrimVis/skills★ 2same name
- HarveyZgit/agents★ 1same name
3 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/AGENTS.mdAGENTS.md
- animation-vocabularySkill
- apple-designSkill
- branchSkill
- codebase-designSkill
- code-qualitySkill
- commitSkill
- emil-design-engSkill
- english-modeSkill
- find-animation-opportunitiesSkill
- find-skillsSkill
- grillingSkill
- handoffSkill
- improve-animationsSkill
- investigateSkill
- ios-app-designSkill
- nix-darwinSkill
- no-useeffectSkill
- prototypeSkill
- react-best-practicesSkill
- resolving-merge-conflictsSkill
- review-animationsSkill
- rust-design-patternsSkill
- self-reviewSkill
- seo-audit-fullSkill
- seo-auditSkill
- skill-creatorSkill
- slow-is-fastSkill
- tddSkill
- thermo-nuclear-code-quality-reviewSkill
- thermo-nuclear-reviewSkill
- thermosSkill
The file
We split this skill into the rules it gives an agent
12 rules. 0 are common, 11 are distinctive, and 1 is very specific to this project.
0
Common
Most of the 13 edited versions we read keep these.
11
Distinctive
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 37
Do not change or remove a fact, a number, a condition, or a scope qualifier.
- Distinctive: line 38
Do not remove or strengthen a hedge.
- Distinctive: line 39
Do not invent an actor to remove a passive.
- Distinctive: line 40
Do not replace a precise term with a plain word that has a different meaning.
- Distinctive: line 41
Do not add a cause, a number, or a mechanism that you did not observe.
- Distinctive: line 43
When a rule and precision conflict, keep the precise wording.
- Distinctive: line 65
Do not make a text shorter than its meaning permits.
- Distinctive: line 107
Before you write a section, classify it as a procedure or a description.
- Distinctive: line 109
If the reader cannot see that a step succeeded, state the expected result.
- Distinctive: line 119
Read the text one time for its meaning.
- Very specific: line 122
If you kept wording that breaks a rule, add a line that starts with Kept: and gives the reason.
- Distinctive: line 128
Before you deliver a PR description or documentation, run the linter.
“Common” is measured: kept by at least 6 in 10 of the 13 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
STE Writing
ASD-STE100 (Simplified Technical English) is the controlled language of aircraft maintenance manuals. It removes the two main causes of misreading: a word with more than one meaning, and a sentence with more than one structure.
This skill applies that discipline to two readers. The user reads a report and must decide or act on it. An external reader of a PR or a document does not have the conversation and cannot ask the author.
The rules are derived from STE. They do not make a text STE-compliant, because compliance needs the official dictionary from asd-ste100.org. Do not claim compliance.
Scope
| Text | Apply |
| Report, finding, summary, plan, or explanation for the user | Core rules, report order |
| PR description, commit body, issue, review comment | Core rules, PR order |
| README, guide, reference page | Core rules, documentation order |
| Procedure, runbook, migration steps, error message, warning | Core rules in strict mode |
| Code, identifiers, commands, log output, quoted text | No change |
| Marketing copy, blog post, text where voice is the point | Out of scope |
This skill does not select the language. Before you draft, read the reference for the language of the text:
- English: references/english.md
- Chinese: references/chinese.md
The user's instructions, a repository template, a project style guide, and a required format take precedence over this skill. Apply the skill to what they leave open.
Meaning Comes First
A text that obeys each rule and changes the meaning is a failure. Do not do these things to satisfy a rule:
- Do not change or remove a fact, a number, a condition, or a scope qualifier.
- Do not remove or strengthen a hedge. "The request may have failed" does not mean "The request failed".
- Do not invent an actor to remove a passive.
- Do not replace a precise term with a plain word that has a different meaning.
- Do not add a cause, a number, or a mechanism that you did not observe.
When a rule and precision conflict, keep the precise wording.
The rules correct the form of a text. They do not supply content. If a paragraph has nothing to say, delete the paragraph.
Core Rules
| Rule | Do | Do not |
| One name for one thing | Select one term and use it each time | Rotate "check", "verify", and "validate" for one action |
| One idea in each sentence | "Open the file. Read line 3." | "Open the file and read line 3, then compare it." |
| Name the actor | "The server deletes the file." | "The file is deleted." |
| Verb, not noun | "Analyze the log." | "Perform an analysis of the log." |
| Keep the structure words | Keep the subject, the connective, and the condition | Fragments, arrows in place of verbs, labels that the reader never saw |
| One hedge at most | "The cache is probably stale. I did not confirm this." | "It may potentially be possible that the cache could be stale." |
| Measurement, not praise | "The build time decreases from 42 s to 18 s." | "The build is significantly faster." |
| Condition before instruction | "If the test fails, run the test again." | "Run the test again if it fails." |
| One topic in each paragraph | A maximum of 6 sentences | One paragraph for the cause, the fix, and the follow-up |
| List for a sequence | A numbered list for 3 or more steps | A sequence in one sentence |
| No frame around the content | Start with the content. Stop when it is complete. | A preamble, a recap, a closing offer |
A passive is correct when the actor is unknown or not important.
Do not make a text shorter than its meaning permits. The goal is one reading, not the minimum number of words.
Modes and Limits
Prose mode is the default. Use strict mode for a procedure, an error message, or a warning. Strict mode adds these requirements:
- Each sentence gives one instruction.
- Each instruction uses the imperative.
- The word rules in the language reference are mandatory, not advisory.
| Limit | English | Chinese |
| Sentence, prose mode | 25 words | 40 units |
| Sentence, strict mode | 20 words | 32 units |
| Clauses in a sentence | No limit | 3 |
| Sentences in a paragraph | 6 | 6 |
| Semicolons | 0 | 0 |
One unit is one Chinese character, or one Latin word, number, or code span. The Chinese limits are a scaled equivalent of the English limits. STE does not define them.
Order
Each list gives an order, not a template. Do not add headings to a short text.
Report to the user:
- The conclusion, or the decision that the user must make.
- The evidence: what you observed, with the path, the command, or the output.
- What you verified and what you did not verify.
- The next action, if there is one.
PR description. If the repository has a PR template, follow the template.
- What changes for the caller or the user, and why.
- The decisions that a reviewer cannot infer from the diff.
- The verification: each command and its result.
- What you did not verify, and the known risks.
Describe the change. Do not tell the story of the session that made it.
Documentation:
- Before you write a section, classify it as a procedure or a description.
- For a procedure, write numbered steps with one action in each step. Put a warning before the step that it applies to.
- If the reader cannot see that a step succeeded, state the expected result.
- For a description, use the present tense.
- Define a term where it first occurs. Then keep that term.
Workflow
For new text, apply the rules while you draft. Do not write a dense draft and then clean it.
For a rewrite of existing text:
- Read the text one time for its meaning.
- Rewrite one sentence at a time.
- Return only the rewritten text.
- If you kept wording that breaks a rule, add a line that starts with
Kept:and gives the reason.
Show a table of the changes only when the user asks for one. If the text already obeys the rules, say so and change nothing.
Check
Before you deliver a PR description or documentation, run the linter. For a chat reply, apply the limits by inspection.
python3 scripts/ste_lint.py FILE # prose mode, or read stdin without FILE
python3 scripts/ste_lint.py --strict FILE # procedures and error messagesThe linter counts. It reports sentence length, semicolons, dashes that join clauses, comma chains in Chinese, and paragraph length. It does not check code blocks, tables, headings, or block quotes. It reports the line where the paragraph starts. It cannot judge word choice, voice, or hedges.
Correct each reported sentence directly. Do not repeat the full rewrite, because a second pass replaces correct terms with synonyms.
Then ask these questions:
- Can a reader who has only this text act on it?
- Does each thing have one name?
- Does the text show which claims you verified?
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.