SKILL.md
Simplified Technical English (ASD-STE100)
Write clear, unambiguous technical English. Prefer STE writing rules over clever or idiomatic phrasing.
This skill applies STE writing rules (grammar and style). It does not embed the copyrighted STE dictionary (~900 approved words). Use simple words with one clear meaning; use SuperPlane technical nouns/verbs for product terms. For full dictionary compliance, consult the official standard: ASD-STE100.
Source: ASD-STE100 Issue 9 (January 2025), Standard for technical documentation. ASD owns the STE trademark and standard; this skill is an operational distillation for agents, not a substitute for the official document.
When this applies
| Text | STE mode |
|---|---|
| PR description Summary and Test plan | Descriptive + procedural |
| Commit message body | Descriptive |
| UI labels, buttons, helper text, empty states, errors, confirmations | Procedural / short descriptive |
| Docs, runbooks, onboarding steps | Procedural and/or descriptive |
Exceptions (do not rewrite these into STE):
- Conventional Commits type prefixes (
feat:,fix:, …) - Code identifiers, API paths, proto names, log lines, and quoted error codes
- Proper nouns and product names (
SuperPlane,GitHub,PostgreSQL) - Issue IDs and DCO trailers
Core rules (must follow)
Words
- Prefer plain words with one meaning. Do not use synonyms for the same idea
in the same surface (start vs begin vs initiate — pick one and keep it).
- Keep one technical noun per concept. Use SuperPlane vocabulary
consistently: canvas, organization, integration, component, trigger, run, approval, console. Spell the product SuperPlane.
- Do not use slang, idioms, humor, or jargon that the reader cannot act on.
- Use American English spelling.
- Prefer verbs for actions. Do not hide actions in nouns
(Create a connection, not Perform connection creation).
- Keep multi-word technical nouns to three words or fewer when you invent
a phrase (deploy approval step, not production deploy approval workflow step).
Verbs and voice
- Prefer these forms: infinitive, imperative, simple present, simple past,
simple future (will), past participle as adjective.
- Avoid complex constructions: progressive (
is creating), perfect
(has created), and stacked auxiliaries when a simple form works.
- Use the active voice. Use passive only in descriptive text when the actor
is unknown.
- Instructions and button labels use the imperative (
Connect GitHub,
Delete the canvas).
Sentences
- Write short, clear sentences. Do not omit necessary words or use contractions
to fake brevity (do not, not don't; cannot, not can't).
- Procedures / instructions / test steps: maximum 20 words per sentence.
One instruction per sentence unless two actions occur at the same time.
- Descriptions (PR Summary, explanatory UI, notes): maximum 25 words
per sentence.
- One topic per paragraph; keep paragraphs short (about six sentences or fewer).
- Use a vertical list when a sentence would list many items or steps.
- Give information gradually: problem or goal first, then necessary detail.
Procedural pattern
When the reader must do something (test plan, UI steps, recovery text):
If the condition is true, do the action.- Put the condition first when the reader must know it before acting.
- Separate condition and command with a comma.
- Name the object and the outcome (
Delete "Deploy to production".).
SuperPlane technical nouns (approved for UI and PRs)
Use these as stable technical nouns. Do not invent synonyms for the same thing:
- SuperPlane
- organization
- canvas
- integration
- component
- trigger
- run
- approval
- console
- factory (Factories product surfaces)
- work order (Factories)
Code-only names (package paths, worker names, proto messages, table names) stay out of user-facing copy.
Before / after
Weak (not STE): We've basically reworked how the onboarding bits kinda wire up integrations and stuff so it's nicer.
STE: This change updates the onboarding flow for integrations. The new flow shows connection status and the next required step.
Weak PR test step: Just make sure everything still works when you click around connecting GitHub and then going back.
STE test step: - [ ] Connect GitHub from the onboarding screen. - [ ] Confirm the status shows Connected. - [ ] Go back one step and confirm the status stays Connected.
Weak UI: Oops! Something went wrong on our end.
STE UI: SuperPlane could not connect to GitHub. Check your credentials and try again.
Quality checklist
- Sentences stay within 20 words (instructions) or 25 words (descriptions)
- Active voice; imperative for commands
- No contractions, slang, idioms, or hype
- One term per concept; SuperPlane vocabulary is consistent
- Lists used when steps or items would crowd a sentence
- PR/commit text explains why without narrative filler
- UI text states the action, object, and outcome
Related skills
- PR titles, commit subjects, and PR structure:
[commit-and-pr-messages](../commit-and-pr-messages/SKILL.md)
- UI microcopy patterns:
[ui-copy](../ui-copy/SKILL.md)