Skip to main content
skill CX Codex

writing-simplified-technical-english — Claude Code skill

writing-simplified-technical-english rewrites English prose to the ASD-STE100 controlled-language standard: one meaning per word, active voice, short sentences. Built for reports, PR descriptions and prompts.

MIT 138 installs ★ 80 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add PostHog/skills --skill writing-simplified-technical-english -a claude-code
Open on GitHub

What writing-simplified-technical-english does

ASD-STE100 is a controlled language that aerospace engineers created so a technician cannot misread a maintenance step. This skill hands those rules to the agent: one verb per action, active voice, simple tenses, one idea per sentence, at most 20 words in an instruction and 25 in a description. Cutting length is not the point. If a shorter sentence drops a condition or a number, the longer one stays.

The skill carries a rule table with do and don't pairs, a four-step rewrite order, and a self-check list for the last pass. Two reference files come with it: references/writing-rules.md for detail and references/before-after.md for worked rewrites. PostHog house style sits on top and overrides the rules where the two disagree.

Skip it for marketing copy or blog posts, where voice matters. Quoted text stays untouched.

What it helps with

  • rewrite an agent report so no sentence reads two ways
  • split a long PR description into one instruction per sentence
  • give error messages and empty states a single verb per action
  • check a handoff prompt for ambiguous wording
  • turn passive instructions into active steps

Example prompts for the agent

  • Simplify this report to simplified technical english — one idea per sentence.
  • This PR description is too dense, rewrite it in STE.
  • Rewrite the error strings in errors.ts with ASD-STE100 rules.

How to install writing-simplified-technical-english

1Skills CLI (Vercel)

npx skills add PostHog/skills --skill writing-simplified-technical-english -a claude-code

2Manually: put the files in place

~/.claude/skills/writing-simplified-technical-english/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/writing-simplified-technical-english/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about writing-simplified-technical-english

How do I install writing-simplified-technical-english in Claude Code?

Run npx skills add PostHog/skills --skill writing-simplified-technical-english -a claude-code. The skill lands in ~/.claude/skills/writing-simplified-technical-english/SKILL.md.

What does writing-simplified-technical-english do?

It makes the agent write English to ASD-STE100: one meaning per word, active voice, simple tenses, short sentences that carry one idea. It also rewrites text you already have.

Where should I not use this skill?

Marketing copy, blog posts and anything persuasive, where a flat tone works against you. Quoted logs and documents are left as they are.

Source text

SKILL.md · MIT
---
name: writing-simplified-technical-english
description: 'Write English that a reader cannot misread: one meaning per word, active voice, simple tenses, one idea per sentence, short sentences. Based on ASD-STE100 (Simplified Technical English), the controlled-language standard written for aircraft maintenance manuals. Use it for any prose an agent produces that someone else acts on. That covers reports and findings, PR descriptions and commit messages, instructions handed to another agent, tool descriptions, error messages, status summaries, and prompts. Also use it on request, with triggers like "simplify this", "make this readable", "too dense", "rewrite in STE", "simplified technical english", "ASD-STE100".'
---

# Writing simplified technical English

ASD-STE100 is a controlled-language standard.
The aerospace and defense industry wrote it so that a technician cannot misread a maintenance instruction.
It removes the two biggest sources of misreading: words that carry more than one meaning, and sentences that support more than one structure.

The same discipline fixes the usual failure of agent-written prose.
Agent output is often correct and unreadable: long sentences, stacked hedges, passive voice, and a synonym rotation that makes one action look like three.
The reader has no author to ask, so ambiguity costs them a re-read at best and a wrong action at worst.

Apply the rules below as you write.
Do not write a dense draft and clean it up afterward.

## When to use this

Use it for text that a person or another agent must act on:

- Reports, findings, and summaries.
- PR descriptions, commit messages, and code comments.
- Instructions passed to another agent, and prompts.
- Tool descriptions, error messages, empty states, and log lines.

Do not use it where voice is the point: marketing copy, blog posts, or anything persuasive.
STE is deliberately flat.
Also leave quoted text alone.
If you quote a user, a log, or a document, quote it as it is.

## The rules

| Rule                        | Do                                                                   | Do not                                                      |
| --------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
| One meaning per word        | Pick one verb per action and reuse it every time                     | Rotate "check", "verify", and "confirm" for the same action |
| One part of speech per word | "Apply oil to the valve"                                             | "Oil the valve"                                             |
| Active voice                | "The worker deletes the file."                                       | "The file is deleted."                                      |
| Simple tenses               | "We received the report."                                            | "We have received the report."                              |
| One idea per sentence       | "Open the file. Read line 3."                                        | "Open the file and read line 3, then check it matches."     |
| Sentence length             | 20 words or fewer for instructions, 25 or fewer for descriptions     | Chains of subordinate clauses                               |
| Noun clusters               | 3 words or fewer ("fuel pump valve")                                 | "high pressure fuel pump inlet valve assembly"              |
| No missing words            | Keep the subject, the verb, and the article, even if it reads longer | "Files not backed up will be lost", which hides which files |
| One hedge, at most          | "The client version is probably out of date."                        | "An error may have occurred which could be caused by..."    |
| Paragraphs                  | One topic, 6 sentences or fewer                                      | Multi-topic paragraphs                                      |
| Lists                       | Use a list for 3 or more steps or conditions                         | A sequence buried in one sentence                           |
| Jargon                      | Keep the technical term you need, and define it once                 | Use an internal name the reader has never seen              |

PostHog house style sits on top of these rules and wins where the two disagree.
We use American English, sentence case, and the Oxford comma.
We do not use the em-dash.

## How to rewrite

1. Read the text once for meaning. Do not start rewriting before you know what it must still say.
2. Go sentence by sentence. Name the rule each sentence breaks.
3. Rewrite the sentence to fix that break. Keep every fact, number, condition, and qualifier.
4. Check the result against the rules again. A rewrite often introduces a new long sentence.

Precision beats brevity.
If a shorter sentence would drop a safety condition, a scope qualifier, or a number, keep the longer sentence and say why.

If the text already follows the rules, say so.
Do not change compliant text.

## Self-check

Before you send the text, read it once and ask:

- Does any sentence run past 25 words?
- Does any sentence carry two instructions?
- Does the same action appear under two different verbs?
- Can a passive sentence name its actor?
- Would a reader who joins here, with no context, know what to do next?

## References

- `references/writing-rules.md`: the detail behind the table, plus sources.
- `references/before-after.md`: worked examples of the rewrite, including agent output.

© PostHog · MIT · PostHog/skills

Similar skills

All skills for Writing and docs →

From the same set112

The whole set →
workload-analysis The workload-analysis skill turns PostHog billing and account data into a React view of spend by product, workload, and team. Use it to inspect SDK usage, growth opportunities, and account risks. CX Codex +1 203installs posthog-pls-transition-leads posthog-pls-transition-leads sorts PostHog product-led leads that are about to meet a real bill, then writes the first outreach email. Built for TAEs working startup rolloffs and high first invoices. CX Codex +1 199installs account-handover account-handover drafts structured handover briefings when transferring PostHog accounts between TAMs or CSMs. CX Codex +1 193installs feature-flags-nextjs feature-flags-nextjs puts PostHog feature flags into a Next.js app: checks inside components, evaluation on the server, and flag management from chat when the PostHog MCP server is connected. CX Codex +1 140installs integration-javascript_node integration-javascript_node adds PostHog analytics to a server-side Node.js app with posthog-node: events in route handlers, user identification, exception tracking. CX Codex +1 131installs integration-javascript_web integration-javascript_web guides client-side PostHog setup in browser JavaScript apps using posthog-js. CX Codex +1 125installs llm-analytics-setup llm-analytics-setup adds PostHog LLM analytics to an app running on any supported provider, tracking tokens, latency and cost for every generation. CX Codex +1 120installs experiment-audit The experiment-audit Claude Code skill checks a PostHog experiment's setup, variant data, attribution, and metrics. It runs on requests to review or validate an A/B test. CX Codex +1 118installs

Project sponsors

Companies that keep this analytics open