danyuchn/asd-ste100-skill已通過檢查
SKILL DETAIL
asd-ste100
danyuchn/asd-ste100-skill/asd-ste100
Use when English text must be parsed without a human to resolve ambiguity — tool descriptions, error messages, inter-agent instructions, system prompts, status reports — and misreading has a real cost, or when text reads as dense, hedged, or easy to misparse. Triggers: disambiguate, STE100 rewrite, apply Simplified Technical English, plain-language rewrite, controlled-language rewrite, rewrite so an agent cannot misread this. Not for creative or marketing copy.
安裝量 · 299查看來源
Installation
npx skills add https://github.com/danyuchn/asd-ste100-skill --skill asd-ste100
技能檔案
SKILL.md
最近同步 · 2026年10月8日
examples/before-after.md›
# Before / After Examples
## Part 1 — Official STE Examples
These illustrate real ASD-STE100 rules, drawn from public secondary sources (see `references/writing-rules.md`). They are paraphrased illustrations of the rule, not quotes from the standard itself.
| Rule | Before | After | Why |
|---|---|---|---|
| One meaning per word | "Verify the system." / "Check the connections." / "Confirm receipt." | "Make sure the system is correct." (one approved term used consistently) | Three near-synonyms force the reader to guess whether they mean the same action. |
| One part of speech per word | "Oil the valve." | "Apply oil to the valve." | If "oil" is approved only as a noun, using it as a verb breaks the one-word-one-role guarantee. |
| Precise verb meaning | "Follow the safety instructions." | "Obey the safety instructions." | "Follow" can mean "come after" or "obey" — STE picks the unambiguous one. |
| Simple tense only | "We have received the technical reports from HQ." | "We received the technical reports from HQ." | Present perfect adds a second parse ("received, and still relevant now?") that simple past avoids. |
| Verb, not noun | "Perform an inspection of the filter." | "Inspect the filter." | The noun form hides the action and adds a filler verb that carries no meaning. |
| No phrasal verbs | "Take off the access panel." | "Remove the access panel." | "Take off" also means "depart" and "deduct" — the two words together do not predict the meaning. |
## Part 2 — Applied to Agent Output
These are original examples built for this skill's actual use case: rewriting AI agent output so another agent, a translation layer, or a non-native reader can parse it without ambiguity. They are illustrations, not quotes from any real system.
Word counts below are whitespace-separated tokens (`text.split()`), punctuation not counted separately. A different tokenizer will produce a different number.
### Example A — Tool description
**Before:**
> This tool will attempt to synchronize state across the various backends that have been configured, and if a conflict is detected it may resolve it automatically depending on the strategy that has been set, or otherwise it will surface the conflict for manual review.
**Violations flagged:**
- Two instructions in one sentence (sync + resolve/surface).
- Present perfect in the relative clauses ("have been configured", "has been set").
- 44 words, far over the 25-word descriptive cap.
Note what is *not* flagged: "will attempt to" and "may resolve". Those are hedges, not violations. The tool is not promised to succeed, and the rewrite must not promise it either.
**After:**
> The tool tries to synchronize state across the configured backends. If it finds a conflict, it reads the configured strategy. If the strategy allows automatic resolution, the tool may resolve the conflict without a user. If the tool does not resolve the conflict, it reports the conflict for manual review.
The last sentence branches on whether the conflict was resolved, not on what the strategy allows. That is what "or otherwise" meant in the original: the fallback covers a permitted resolution that still did not happen.
### Example B — Error message
**Before:**
> An error may have occurred while processing your request due to a possible mismatch in the expected data format, which could be caused by an outdated client version.
**Violations flagged:**
- One sentence carrying three separate claims (an error occurred, a format mismatch, a client version).
- 28 words, over the descriptive cap.
Not flagged: "may have occurred" and "could be caused by". The message is written by a system that does not know what went wrong. Both hedges are accurate reporting of that ignorance.
**After:**
> Your request may have failed. The cause may be a data format that does not match what the server expects. An outdated client can cause this mismatch. Check your client version.
**This example is the reason the modality rule exists.** An earlier version of this file rewrote the first sentence as "The request failed", and the third as "an outdated client **is the most common cause**". Both read better. Both are wrong: the first asserts a failure the system only suspects, and the second invents a frequency claim that appears nowhere in the input. A rewrite that supplies a cause, a frequency, or a mechanism has stopped being a rewrite.
Note also that "may have failed" keeps a compound verb form that the simple-tense rule would otherwise remove. **When the tense rule and the modality rule conflict, modality wins** — dropping the auxiliary here would delete the uncertainty along with the tense.
### Example C — Inter-agent instruction
**Before:**
> Once the upstream job has completed and assuming no errors were raised, the downstream agent should proceed to consume the output artifact, though it is worth noting that partial artifacts are sometimes produced under timeout conditions.
**Violations flagged:**
- Present perfect ("has completed") and subordinate-clause stacking ("assuming...", "though it is worth noting...").
- One sentence, three separate facts (completion condition, next action, edge-case warning).
- 36 words, over the 20-word instruction cap.
**After:**
> Wait for the upstream job to finish with no errors. Then read the output artifact. Warning: a timeout can produce a partial artifact. Check that the artifact is complete before you use it.
Two deliberate calls worth stating rather than hiding:
- "should proceed to consume" became the imperative "read". STE permits this for instructions, where a recommendation addressed to the executing agent is a command. Do not make the same move in descriptive text.
- The final sentence is **new**. The original warned about partial artifacts without saying what to do about it. Adding the check makes the warning actionable, but it is added content, so it is called out here rather than passed off as a rewrite. If the source's silence was deliberate, drop the sentence.
### Example D — README prose (STE-flavored mode)
**Before:**
> Our caching layer is designed to slot seamlessly into your existing stack with minimal friction and no vendor lock-in; it leverages semantic similarity to dramatically reduce the cache misses that traditionally plague LLM workloads.
**Violations flagged:**
- Marketing adjectives and claims without measurement ("seamlessly", "minimal friction", "dramatically").
- Semicolon joining two separate ideas.
- Nominalization and soft phrasing ("is designed to slot into", "leverages").
- 34 words, over the 25-word descriptive cap.
**After:**
> A normal cache matches requests by exact text, so a small change in wording causes a cache miss. This cache compares the meaning of a new prompt against the prompts it already holds. It runs alongside your current stack and stores no data outside it.
Flavored mode kept the explanatory rhythm and did not force one fixed term per concept. It still cut the marketing adjectives, the semicolon, and the length.
## How to Read These Examples
Part 1 shows the actual rules this skill is built on. Part 2 shows the transfer: the same discipline — one meaning per word, active voice, simple tense, one instruction per sentence, explicit conditions instead of buried subordinate clauses — makes machine-to-machine and cross-language text safer to parse, not just aircraft manuals.
examples/linter-edge-cases.md›
# Linter Edge Cases
This file has intentional structural violations. Use it to test the linter.
## Incomplete list items
- Set the target and
- Record the result or
## Fenced code
~~~text
- This line ends with and
~~~
LICENSE›
MIT License
Copyright (c) 2026 Dustin Yuchen Teng
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md›
# ASD-STE100 Skill — Simplified Technical English for Agent Output
A Claude Code skill that rewrites dense, ambiguous English into [ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/) (STE) — the controlled-language standard the aerospace and defense industry built so aircraft maintenance instructions cannot be misread.
This skill repurposes that same discipline for a different reader: an **AI agent** parsing another agent's output, a tool description, an error message, or an inter-agent instruction, with no human in the loop to resolve ambiguity.
## Why STE, and Why for Agents
STE exists because a misread instruction on an aircraft can kill people, and the intended readers were often not native English speakers with no author to call for clarification. The standard's fix: one meaning per word, active voice, simple tenses, one instruction per sentence, short sentences, no dropped words.
An LLM agent parsing another agent's output is in a strikingly similar position — no back-channel, no way to ask "did you mean X or Y?" The same rules that keep a mechanic from misreading a torque spec keep a downstream agent from misreading a tool description or an inter-agent message.
## Before / After
| Before | After |
|---|---|
| "This tool will attempt to synchronize state across the various backends that have been configured, and if a conflict is detected it may resolve it automatically depending on the strategy that has been set, or otherwise it will surface the conflict for manual review." | "The tool tries to synchronize state across the configured backends. If it finds a conflict, it reads the configured strategy. If the strategy allows automatic resolution, the tool may resolve the conflict without a user. If the tool does not resolve the conflict, it reports the conflict for manual review." |
| "An error may have occurred while processing your request due to a possible mismatch in the expected data format, which could be caused by an outdated client version." | "Your request may have failed. The cause may be a data format that does not match what the server expects. An outdated client can cause this mismatch. Check your client version." |
More examples, including illustrations of the official STE rules themselves, in [`examples/before-after.md`](examples/before-after.md).
## What This Skill Does
1. Picks a mode. **Strict** covers procedures, error messages, and tool descriptions. **STE-flavored** covers READMEs, PR descriptions, and explanatory prose. STE-flavored keeps the sentence discipline but not the fixed-vocabulary lockdown.
2. Reads the input English text for meaning.
3. Flags every rule violation sentence-by-sentence: ambiguous word choice, present-perfect/complex tense, passive voice with an unclear actor, multi-instruction sentences, oversized noun clusters, dropped words, sentences over length, phrasal verbs, nominalized actions, semicolons, hedge stacks, and marketing adjectives.
4. Rewrites each flagged sentence — without dropping any fact, condition, or scope qualifier from the original. If a shorter phrasing would lose required precision, it keeps the longer phrasing and flags the trade-off instead of silently simplifying.
5. Outputs the rewritten text on its own — no preamble, no mode announcement, no change summary — plus a one-line `Kept as-is:` note when it deliberately left something unsimplified.
Ask for the reasoning ("show the diff", "which rules did it break") and it outputs a before/after table naming each rule instead.
The structural rules it checks are mechanical — you can point at the word or punctuation mark that breaks each one. The rules that depend on ASD's dictionary are flagged as advisory rather than enforced, and the rules that need taste are left to you.
The linter checks structural patterns only. It does not compare an original text with a rewrite, verify that requirement strength stayed the same, or prove that the rewrite preserved meaning. A zero-violation result means that the configured structural checks found no problems.
The deterministic linter checks semicolons, a short list of soft phrasal verbs (spin up, reach out, dive into, kick off, circle back, touch base), nominalizations, marketing adjectives, passive voice, present-perfect forms (including irregular participles such as "has run"), long sentences, synonym rotation, and dangling conjunctions in supported list items. It does not check noun-cluster length (that needs part-of-speech tagging) and it does not know phrasal verbs outside its list, so "take off the panel" passes. It never flags hedges or modality.
The repo's own prose does not lint clean: the rule tables quote the patterns they forbid, and some sentences run long. Lint it with `python scripts/ste-lint.py --baseline 41 SKILL.md` and read the findings as examples, not defects.
The dangling-conjunction rule checks list markers at the start of a line with zero to three leading spaces and ASCII spaces after the marker. It supports unordered markers `-`, `*`, and `+`, and ordered numeric markers that end in `.` or `)`, such as `1.` or `1)`. It checks indented continuation lines up to the final meaningful line. It does not parse list syntax inside blockquotes, lazy continuation, or full nested-list semantics. A standalone line with four or more leading spaces is not treated as a list marker. Within an active list item, indentation at the computed content column is treated as continuation text. Fence detection follows the linter's existing simple rule: a stripped line beginning with three backticks or three tildes toggles the fence state.
The intentionally invalid examples/linter-edge-cases.md file demonstrates incomplete Markdown list items. Run python scripts/ste-lint.py examples/linter-edge-cases.md to confirm that the linter reports the two expected findings. The file is a test fixture and should not be used as compliant STE prose.
It does **not** reproduce ASD's official ~900-word approved dictionary. The standard is free to obtain but not free to redistribute: Issue 9 permits reproduction only with ASD's written authority, or by eight listed categories of organisation that this project does not belong to. This skill applies the underlying *principle* (plainest available word, used the same way every time) rather than checking against a fixed word list. For certified STE-compliant documentation, use the real standard.
Full rule summary and citations: [`references/writing-rules.md`](references/writing-rules.md).
## Installation
### Quick Install (npx skills)
The fastest way to install this skill is the [skills CLI](https://skills.sh/) — no clone, no path setup. Run it from your project root:
```bash
npx skills add danyuchn/asd-ste100-skill
```
This pulls the skill from the GitHub repo and installs it for the current project. The CLI sends anonymous install telemetry (skill name and timestamp, no personal or device information) to help rank skills on the skills.sh leaderboard. Set `DISABLE_TELEMETRY=1` to opt out.
Update later with `npx skills update`.
### Clone
```bash
git clone https://github.com/danyuchn/asd-ste100-skill ~/.claude/skills/asd-ste100
```
This clones the repo into `~/.claude/skills/`, making the skill available in every Claude Code project. Best for contributors and anyone who wants a live checkout that updates with `git pull`.
## Usage
Trigger with a request to simplify or clarify English text:
```
Disambiguate this tool description
Rewrite this error message so an agent can't misparse it
Apply ASD-STE100 to this instruction
```
Or paste text and ask Claude to "disambiguate this" / "apply STE100 to this" / "reduce ambiguity in this output."
You get the rewritten text back and nothing else. To see which rules were applied, add "show the diff" or "explain the changes" to the request.
## Scope
Built for: agent-to-agent messages, tool/function descriptions, error messages, system prompts, inter-agent instructions — any English text a machine or non-native reader has to parse without a human to ask.
Not built for: creative writing, marketing copy, or anything where voice and nuance are the point — STE is deliberately flat and literal by design.
One limit worth stating up front: this fixes the form of a text, not its substance. A paragraph with nothing to say comes out short, clean, and still empty.
## Sources
- [ASD-STE100 official site](https://www.asd-ste100.org/)
- [ASD-STE100 — About STE](https://www.asd-ste100.org/about_STE.html)
- [ASD Europe — Simplified Technical English](https://www.asd-europe.org/standards-specifications/simplified-technical-english/)
- [Simplified Technical English — Wikipedia](https://en.wikipedia.org/wiki/Simplified_Technical_English)
- [TechScribe — ASD-STE100 Simplified Technical English](https://www.techscribe.co.uk/techw/asd-simplified-technical-english.htm)
## License
MIT — see [LICENSE](LICENSE).
references/writing-rules.md›
# ASD-STE100 Writing Rules — Summary and Sources
This file summarizes the public, official description of ASD-STE100 (Simplified Technical English). It paraphrases rule *categories*. It does not reproduce the standard's text or its ~900-word dictionary verbatim. For the authoritative document, request the free download at the official site.
## What ASD-STE100 Is
ASD-STE100 is a controlled natural language, first released in 1986 (as AECMA Document PSC-85-16598) by what is now ASD (the AeroSpace and Defense Industries Association of Europe). It was built at the request of European airlines — most staffed by non-native English speakers — who needed maintenance documentation that could not be misread, because a misread instruction on an aircraft can kill people. The standard is maintained by the Simplified Technical English Maintenance Group (STEMG) and has been free to download since Issue 6 (2013). The current edition is Issue 9 (January 2025).
## Structure
- **53 writing rules across 9 sections** covering word choice, grammar, sentence structure, and style.
- **A dictionary** of roughly 900 approved words, each restricted to one meaning and one part of speech, plus roughly 1,200 words to avoid with suggested replacements.
- **A terminology allowance**: organizations may define their own dictionary of approved technical nouns and verbs beyond the base ~900 words, for domain-specific vocabulary the base dictionary can't cover.
## Rule Categories (Paraphrased)
**Word choice**
- Use approved words only in their approved meaning and part of speech.
- Each word maps to exactly one meaning — don't rely on context to disambiguate a word that has several dictionary senses.
- Prefer the plainer, shorter, more common word over a formal or rare synonym.
- Use an approved verb for an action, not a noun derived from that verb (Rule 3.7).
- Do not make phrasal verbs by putting a verb and a preposition together (Rule 9.3). Their meaning is not predictable from the parts, and non-native readers and translation systems both mishandle them.
**Verb forms**
- Permitted forms: infinitive, imperative, simple present, simple past, simple future, and past participle used only as an adjective.
- No present perfect, past perfect, or other compound/auxiliary constructions. "We have received" is not allowed. "We received" is allowed.
- "-ing" forms are permitted only as a technical noun or as part of a technical noun, not as a verb form.
**Voice**
- Active voice is required for procedures and instructions.
- Passive voice is allowed only in descriptive text, and only when the actor performing the action is genuinely unknown or irrelevant to the reader.
**Sentence structure**
- One instruction per sentence.
- Maximum ~20 words per sentence for procedures and instructions. Maximum ~25 words for descriptive text.
- Do not omit sentence parts (verb, subject, article) just to shorten the sentence — the standard explicitly warns that this creates ambiguity rather than clarity.
- Noun clusters (strings of nouns stacked as a modifier) are capped at 3 words.
- Semicolons are not permitted at all (Rule 8.1): "You can use all standard English punctuation marks but not the semicolon (;)." Write separate sentences instead. Every other standard mark, including the em dash, remains permitted.
**Paragraph and document structure**
- One topic per paragraph.
- Maximum ~6 sentences per paragraph.
- Use vertical (numbered or bulleted) lists for sequences, conditions, or complex enumerations instead of burying them in prose.
**Safety instructions**
- Safety-critical instructions must open with a clear command or condition, not be buried mid-sentence.
## Why This Skill Repurposes STE for Agent Output
STE was designed to eliminate ambiguity for a reader who cannot ask a follow-up question — a technician on a tarmac, working from a manual, with no author to call. An AI agent parsing another agent's output, a tool description, or a system message is in the same position: no back-channel to resolve "does this passive-voice sentence mean the caller does X, or the callee does X?" The same rule set that protects an airline mechanic from a misread torque spec protects a downstream agent from a misread instruction.
## Sources
- [ASD-STE100 official site](https://www.asd-ste100.org/)
- [ASD-STE100 — About STE](https://www.asd-ste100.org/about_STE.html)
- [ASD Europe — Simplified Technical English](https://www.asd-europe.org/standards-specifications/simplified-technical-english/)
- [Simplified Technical English — Wikipedia](https://en.wikipedia.org/wiki/Simplified_Technical_English)
- [TechScribe — ASD-STE100 Simplified Technical English](https://www.techscribe.co.uk/techw/asd-simplified-technical-english.htm)
- [SKYbrary — Simplified Technical English (STE)](https://skybrary.aero/articles/simplified-technical-english-ste)
scripts/ste-lint.py›
#!/usr/bin/env python3
"""Deterministic linter for the structural STE rules in SKILL.md.
Checks only rules verifiable without ASD's dictionary. Deliberately never
flags hedges or modality (may/might/could): the skill treats confidence as
content, and a linter that pressures hedges out would rewrite claims.
Usage:
ste-lint.py FILE [FILE ...]
echo "text" | ste-lint.py [--json]
ste-lint.py --baseline 5 FILE # pass unless hard violations exceed 5
ste-lint.py --disable passive-voice,present-perfect FILE
ste-lint.py --selftest
Exit 1 when hard ("advisory-free") violations exceed the baseline (default 0).
Advisory findings (passive voice, compound tenses) never fail the run.
"""
import json
import re
import sys
# ponytail: regex heuristics, not a parser. No noun-cluster rule — needs POS
# tagging to avoid constant false positives; add spaCy-backed rule if ever needed.
# No ellipsis rule by owner's choice: technical writing sometimes earns one.
# Irregular past participles used by the present-perfect heuristic.
IRREGULAR_PARTICIPLES = "given|taken|made|done|found|seen|known|shown|written|built|sent|set|run|read|kept|held|left|put|cut|hit|let|shut|split|spread|begun|become|come|gone|got|gotten|lost|met|paid|said|sold|told|thought|brought|bought|caught|taught|won|worn|torn|born|drawn|grown|thrown|flown|driven|risen|chosen|broken|spoken|frozen|hidden|ridden|forgotten|fallen|eaten|beaten|understood|stood|struck|stuck|swung|hung|led|fed|bled|fled|sped|bound|wound|dug|spun|slid|bit|lit|quit"
# Preserve the original passive heuristic; perfects also include intransitive verbs.
PASSIVE_PARTICIPLES = "given|taken|made|done|found|seen|known|shown|written|built|sent|set|run|read|kept|held|left|put"
MODAL_PERFECT_PREFIX = re.compile(
r"\b(?:may|might|could|should|would|must|can|will|shall)"
r"(?:\s+not|n['’]t)?\s+$", re.I,
)
RULES = [
("semicolon", "advisory-free",
re.compile(r";"),
"STE bans the semicolon (Rule 8.1). Split into separate sentences."),
("phrasal-verb", "advisory-free",
re.compile(r"\b(spin(?:ning|s)? up|spun up|reach(?:ing|es|ed)? out|div(?:e|es|ing|ed) into|dove into|kick(?:ing|s|ed)? off|circl(?:e|es|ing|ed) back|touch(?:ing|es|ed)? base)\b", re.I),
"Soft phrasal verb. Use the single plain verb (start, contact, read, begin)."),
("marketing-adjective", "advisory-free",
re.compile(r"\b(seamless(?:ly)?|robust(?:ly)?|cutting-edge|effortless(?:ly)?|blazing[- ]fast|world-class|state-of-the-art|game-chang(?:ing|er))\b", re.I),
"Marketing adjective. Delete, or replace with the measurement that earns the claim."),
("nominalization", "advisory-free",
re.compile(r"\b(perform|performs|performed|conduct|conducts|conducted|carry out|carries out|carried out)\s+(?:a|an|the)\s+\w+(?:tion|sion|ment|ance|ence|ysis)\b", re.I),
"Action frozen into a noun. Use the verb (analyze, not perform an analysis of)."),
("passive-voice", "advisory",
re.compile(r"\b(is|are|was|were|been|being)\s+(\w+ed|" + PASSIVE_PARTICIPLES + r")\b(?!\s+(?:to|for|by)\s+\w+ing)", re.I),
"Possible passive voice. Name the actor and use an active verb, unless the actor is unknown or irrelevant."),
("present-perfect", "advisory",
# modal + perfect infinitive ("may have failed") is a protected hedge, not present perfect
re.compile(r"(?<!\bmay )(?<!\bmight )(?<!\bcould )(?<!\bshould )(?<!\bwould )(?<!\bmust )\b(has|have|had)\s+(?:been\s+)?(?:\w+(?:ed|en)|" + IRREGULAR_PARTICIPLES + r")\b", re.I),
"Compound tense. Use simple past/present unless current relevance is the point (then keep and flag)."),
]
# One word, one meaning: groups of verbs commonly rotated for the same action.
# Only pairs where the members are genuinely interchangeable — error/fault/failure
# are distinct concepts and stay out.
SYNONYM_GROUPS = [
("check", "verify", "confirm", "validate"),
("delete", "remove", "erase"),
("start", "launch", "begin", "initiate"),
("stop", "halt", "terminate"),
("show", "display"),
("use", "utilize", "employ"),
("fix", "repair", "correct"),
("send", "transmit"),
("get", "retrieve", "fetch", "obtain"),
("change", "modify", "alter"),
]
MAX_WORDS = 25 # descriptions cap; instructions cap is 20 but undetectable without context
CODE_FENCE = re.compile(r"^(```|~~~)")
INLINE_CODE = re.compile(r"`[^`]*`")
LIST_ITEM_START = re.compile(
r"^(?P<indent> {0,3})(?P<marker>[-*+]|[0-9]+[.)])(?P<gap> +)(?P<body>.*)$"
)
CONJUNCTION_END = re.compile(r"\b(?:and|or)\s*$", re.I)
TABLE_SEPARATOR_CELL = re.compile(r"^:?-{3,}:?$")
def _word_re(base):
return re.compile(r"\b" + base + r"(?:s|es|ed|d|ing)?\b", re.I)
def _leading_spaces(line):
return len(line) - len(line.lstrip(" "))
def _is_list_continuation(line, content_indent):
if not line.strip():
return True
if LIST_ITEM_START.match(line):
return False
return _leading_spaces(line) >= content_indent
def _split_table_row(line):
"""Return trimmed table cells and their zero-based source columns.
A pipe must separate at least two cells. Escaped pipes stay in their cell.
This deliberately implements only the ordinary Markdown table shape; it is
enough to distinguish a table from prose that happens to contain a pipe.
"""
left = len(line) - len(line.lstrip())
right = len(line.rstrip())
content = line[left:right]
if "|" not in content:
return None
if content.startswith("|"):
content = content[1:]
left += 1
if content.endswith("|"):
content = content[:-1]
raw_cells = re.split(r"(?<!\\)\|", content)
if len(raw_cells) < 2:
return None
cells = []
column = left
for raw_cell in raw_cells:
leading = len(raw_cell) - len(raw_cell.lstrip())
cells.append((raw_cell.strip(), column + leading))
column += len(raw_cell) + 1
return cells
def _markdown_table_cells(lines):
"""Map ordinary Markdown table rows to their prose cells.
The separator row anchors detection, so pipe-containing prose is not
treated as a table. Both leading-pipe and no-leading-pipe table styles are
accepted when their header and body use the same number of cells.
"""
table_cells = {}
index = 1
while index < len(lines):
separator = _split_table_row(lines[index])
header = _split_table_row(lines[index - 1])
if (not separator or not header or len(separator) != len(header)
or not all(TABLE_SEPARATOR_CELL.fullmatch(cell)
for cell, _ in separator)):
index += 1
continue
table_cells[index - 1] = header
table_cells[index] = []
index += 1
while index < len(lines):
row = _split_table_row(lines[index])
if not row or len(row) != len(separator):
break
table_cells[index] = row
index += 1
return table_cells
def _dangling_conjunction_findings(text, filename):
lines = text.splitlines()
findings = []
in_fence = False
index = 0
while index < len(lines):
line = lines[index]
stripped = line.strip()
if CODE_FENCE.match(stripped):
in_fence = not in_fence
index += 1
continue
if in_fence:
index += 1
continue
start = LIST_ITEM_START.match(line)
if not start:
index += 1
continue
content_indent = (len(start.group("indent"))
+ len(start.group("marker"))
+ len(start.group("gap")))
item_lines = [(index, start.group("body"))]
next_index = index + 1
item_fence = False
while next_index < len(lines):
candidate = lines[next_index]
candidate_stripped = candidate.strip()
if CODE_FENCE.match(candidate_stripped):
# Fence delimiters are state markers, not meaningful item lines.
item_fence = not item_fence
next_index += 1
continue
if item_fence:
next_index += 1
continue
if not _is_list_continuation(candidate, content_indent):
break
item_lines.append((next_index, candidate))
next_index += 1
meaningful = []
for line_index, item_line in item_lines:
# Preserve code spans as neutral operands while ignoring their contents.
cleaned = INLINE_CODE.sub(" CODE ", item_line).strip()
if cleaned:
meaningful.append((line_index, cleaned))
if meaningful:
end_line_index, end_line = meaningful[-1]
conjunction = CONJUNCTION_END.search(end_line)
else:
end_line_index, end_line, conjunction = None, None, None
if conjunction:
if end_line_index == index:
finding_line = index + 1
finding_col = start.start("marker") + 1
else:
raw_end_line = next(
raw for line_index, raw in item_lines
if line_index == end_line_index
)
masked_end_line = INLINE_CODE.sub(
lambda match: " " * len(match.group(0)), raw_end_line
)
raw_conjunction = CONJUNCTION_END.search(masked_end_line)
finding_line = end_line_index + 1
finding_col = raw_conjunction.start() + 1 if raw_conjunction else 1
findings.append({
"file": filename,
"line": finding_line,
"col": finding_col,
"rule": "dangling-conjunction",
"level": "advisory-free",
"match": end_line,
"message": "List item ends with a coordinating conjunction. Complete the item or join it with the next item.",
})
index = next_index
return findings
def lint(text, filename="<stdin>"):
findings = []
words_total = 0
in_fence = False
lines = text.splitlines()
table_cells = _markdown_table_cells(lines)
# first occurrence of each synonym-group member: (group_idx, base) -> (line, col, match)
seen_synonyms = {}
for lineno, raw_line in enumerate(lines, 1):
if CODE_FENCE.match(raw_line.strip()):
in_fence = not in_fence
continue
if in_fence:
continue
segments = table_cells.get(lineno - 1, [(raw_line, 0)])
for segment, source_column in segments:
line = INLINE_CODE.sub("", segment)
words_total += len(line.split())
for rule_id, level, pattern, msg in RULES:
for m in pattern.finditer(line):
if rule_id == "present-perfect" and MODAL_PERFECT_PREFIX.search(
line[:m.start()]
):
continue
findings.append({"file": filename, "line": lineno,
"col": source_column + m.start() + 1,
"rule": rule_id, "level": level,
"match": m.group(0), "message": msg})
for gi, group in enumerate(SYNONYM_GROUPS):
for base in group:
if (gi, base) in seen_synonyms:
continue
m = _word_re(base).search(line)
if m:
seen_synonyms[(gi, base)] = (
lineno, source_column + m.start() + 1, m.group(0)
)
for sent in re.split(r"(?<=[.!?])\s+", line):
n = len(sent.split())
if n > MAX_WORDS:
findings.append({"file": filename, "line": lineno,
"col": source_column + 1,
"rule": "long-sentence", "level": "advisory-free",
"match": f"{n} words",
"message": f"Sentence has {n} words (cap {MAX_WORDS}). Split it."})
# synonym rotation: flag each member after the first, at its first occurrence
for gi, group in enumerate(SYNONYM_GROUPS):
present = [(seen_synonyms[(gi, b)], b) for b in group if (gi, b) in seen_synonyms]
if len(present) > 1:
present.sort() # document order
first_base = present[0][1]
for (lineno, col, match), base in present[1:]:
findings.append({"file": filename, "line": lineno, "col": col,
"rule": "synonym-rotation", "level": "advisory-free",
"match": match,
"message": f"'{base}' and '{first_base}' name the same action. Pick one and use it every time."})
findings.extend(_dangling_conjunction_findings(text, filename))
findings.sort(key=lambda f: (f["line"], f["col"]))
return findings, words_total
def report(findings, words_total, as_json, hard_count, baseline):
rate = round(len(findings) * 100 / words_total, 1) if words_total else 0.0
if as_json:
print(json.dumps({"violations": findings, "count": len(findings),
"hard_count": hard_count, "baseline": baseline,
"words": words_total, "per_100_words": rate}, indent=2))
return
for f in findings:
print(f"{f['file']}:{f['line']}:{f['col']} {f['rule']}: {f['message']} [{f['match']}]")
print(f"\n{len(findings)} violations ({hard_count} hard, baseline {baseline}), "
f"{words_total} words, {rate} per 100 words")
print("Hedges/modality (may, might, could) are never flagged: confidence is content.")
def selftest():
bad = ("The panel is removed; spin up the job. "
"Perform an analysis of the seamless log. "
"We have received the report.")
findings, _ = lint(bad)
rules = {f["rule"] for f in findings}
for expected in ("semicolon", "phrasal-verb", "nominalization",
"marketing-adjective", "passive-voice", "present-perfect"):
assert expected in rules, expected
# hedges must never be flagged, including modal + perfect infinitive
findings, _ = lint("The request may have failed. It could be a timeout. "
"The disk might have filled.")
assert findings == [], findings
# irregular participles: "has run" is a compound tense as much as "has failed"
findings, _ = lint("The task has run. The job has set the flag. We have begun.")
assert sum(1 for f in findings if f["rule"] == "present-perfect") == 3, findings
findings, _ = lint("The job may have run.")
assert not any(f["rule"] == "present-perfect" for f in findings), findings
# Modal perfects remain protected across negation and variable whitespace.
for modal in ("may", "might", "could", "should", "would", "must"):
for gap in (" ", " ", "\t", " not "):
findings, _ = lint(f"The task {modal}{gap}have run.")
assert not any(f["rule"] == "present-perfect" for f in findings), findings
findings, _ = lint("The task couldn't have run. The task MAY NOT HAVE RUN.")
assert not any(f["rule"] == "present-perfect" for f in findings), findings
findings, _ = lint("The task has run. We have begun. The flag is set.")
assert sum(f["rule"] == "present-perfect" for f in findings) == 2, findings
assert any(f["rule"] == "passive-voice" for f in findings), findings
findings, _ = lint("The task is gone.")
assert not any(f["rule"] == "passive-voice" for f in findings), findings
# code blocks skipped
findings, _ = lint("```\nx = a; y = b\n```")
assert findings == []
# all supported list markers, case variants, and trailing whitespace
findings, _ = lint(
"- Confirm the target and\n"
"* Record the result OR \n"
"+ Close the panel\n"
"1. Start the task and\n"
"2) Stop the task OR"
)
dangling = [f for f in findings if f["rule"] == "dangling-conjunction"]
assert len(dangling) == 4, dangling
assert [f["line"] for f in dangling] == [1, 2, 4, 5], dangling
assert [f["col"] for f in dangling] == [1, 1, 1, 1], dangling
assert all(f["level"] == "advisory-free" for f in dangling), dangling
# valid continuation lines and standalone four-space code are ignored
findings, _ = lint(" - Confirm the target and\n record the result.")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint("- Confirm the target\n and")
dangling = [f for f in findings if f["rule"] == "dangling-conjunction"]
assert len(dangling) == 1 and dangling[0]["line"] == 2, dangling
assert dangling[0]["col"] == 3, dangling
findings, _ = lint(" - code and")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint("> - Confirm the target and\n> - Record the result or")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint("- Do this and\n~~~\ncode and\n~~~")
dangling = [f for f in findings if f["rule"] == "dangling-conjunction"]
assert len(dangling) == 1 and dangling[0]["line"] == 1, dangling
findings, _ = lint("```text\n- code and\n```")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
# one- and three-space markers and ordered continuation width
findings, _ = lint(" - Start the task and\n record the result.")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint("- Start the task and\n record the result.")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint("-\tStart the task and")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint(" - Start the task and", filename="fixture.md")
dangling = [f for f in findings if f["rule"] == "dangling-conjunction"]
assert len(dangling) == 1 and dangling[0]["col"] == 4, dangling
assert dangling[0]["file"] == "fixture.md"
assert dangling[0]["match"].endswith("and")
assert "Complete the item" in dangling[0]["message"]
findings, _ = lint("100. Start the task and\n unrelated text")
dangling = [f for f in findings if f["rule"] == "dangling-conjunction"]
assert len(dangling) == 1, dangling
findings, _ = lint("- Start the task and.\n- Stop the task or,")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint("- Start the task and\n\n record the result.")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint("- Parent item and\n - Nested item or")
dangling = [f for f in findings if f["rule"] == "dangling-conjunction"]
assert [f["line"] for f in dangling] == [1, 2], dangling
# ordinary prose, inline code, and fenced code are ignored
findings, _ = lint("The process may include steps and")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint("- Use `and` as a label")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint("- Combine `left` and `right`")
assert not any(f["rule"] == "dangling-conjunction" for f in findings), findings
findings, _ = lint("~~~\n- code and\n~~~")
assert not any(f["rule"] == "dangling-conjunction" for f in findings)
findings, _ = lint(("word " * 30).strip() + ".")
assert any(f["rule"] == "long-sentence" for f in findings)
# Markdown table syntax is layout, not prose. Each cell stays lintable.
short_cell = " ".join(f"term{number}" for number in range(1, 25)) + "."
for table in (
"| Label | Detail |\n"
"| --- | --- |\n"
f"| Clear | {short_cell} |",
"Label | Detail\n"
"--- | ---\n"
f"Clear | {short_cell}"):
findings, words_total = lint(table)
assert not any(f["rule"] == "long-sentence" for f in findings), findings
assert words_total == 27, words_total
long_cell = " ".join(f"term{number}" for number in range(1, 27)) + "."
findings, _ = lint(
"| Label | Detail |\n"
"| --- | --- |\n"
f"| Clear | {long_cell} |"
)
long_sentences = [f for f in findings if f["rule"] == "long-sentence"]
assert len(long_sentences) == 1, long_sentences
assert long_sentences[0]["match"] == "26 words", long_sentences
# synonym rotation: second member flagged, first named as the keeper
findings, _ = lint("Check the config file. Then verify the output. Verify twice.")
rot = [f for f in findings if f["rule"] == "synonym-rotation"]
assert len(rot) == 1 and "'verify' and 'check'" in rot[0]["message"], rot
# single consistent term: no flag
findings, _ = lint("Check the config. Check the output.")
assert not any(f["rule"] == "synonym-rotation" for f in findings)
# per-file labels
findings, _ = lint("a; b", filename="x.md")
assert findings[0]["file"] == "x.md"
print("selftest OK")
def main(argv):
if "--selftest" in argv:
selftest()
return 0
as_json = "--json" in argv
baseline = 0
disabled = set()
paths = []
i = 0
while i < len(argv):
a = argv[i]
if a == "--baseline":
i += 1
baseline = int(argv[i])
elif a == "--disable":
i += 1
disabled = set(argv[i].split(","))
elif not a.startswith("--"):
paths.append(a)
i += 1
findings, words_total = [], 0
if paths:
for p in paths:
f, w = lint(open(p, encoding="utf-8").read(), filename=p)
findings.extend(f)
words_total += w
else:
findings, words_total = lint(sys.stdin.read())
findings = [f for f in findings if f["rule"] not in disabled]
hard_count = sum(1 for f in findings if f["level"] == "advisory-free")
report(findings, words_total, as_json, hard_count, baseline)
return 1 if hard_count > baseline else 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
SKILL.md›
---
name: asd-ste100
description: "Use when English text must be parsed without a human to resolve ambiguity — tool descriptions, error messages, inter-agent instructions, system prompts, status reports — and misreading has a real cost, or when text reads as dense, hedged, or easy to misparse. Triggers: disambiguate, STE100 rewrite, apply Simplified Technical English, plain-language rewrite, controlled-language rewrite, rewrite so an agent cannot misread this. Not for creative or marketing copy."
version: 0.4.0
---
# Simplified Technical English (ASD-STE100)
ASD-STE100 is a controlled-language standard built by the aerospace and defense industry (ASD, the AeroSpace and Defense Industries Association of Europe) to stop maintenance technicians from misreading English instructions. The standard removes the two biggest sources of misreading: words with more than one meaning, and sentences with more than one possible structure.
This skill borrows that same discipline for a different reader: an **AI agent or a downstream system** that has to parse an English string — an error message, a tool description, an inter-agent instruction, a status report — without a human in the loop to resolve ambiguity. If a maintenance technician can misread "close the valve" as an adjective ("the valve that is near") instead of a command, so can a language model.
## When to Use This Skill
- An agent's output (explanation, instruction, log message, tool description) reads as dense, jargon-heavy, or ambiguous.
- Text will be consumed by another agent, a translation pipeline, or a non-native English reader, and misparsing has a real cost.
- You are writing a prompt, system message, or tool description and want to remove ambiguity before a model ever sees it.
- You want a **before/after** comparison showing exactly which rule was violated and how the rewrite fixes it. Ask for it — the default output is the rewritten text alone (see Output Format).
This skill is not for creative or marketing copy — STE is deliberately flat and literal. Do not apply it to text where voice, nuance, or persuasion is the point.
## Two Modes
Pick a mode before rewriting. If the user does not say which, infer it from the text type. Keep the choice internal unless the user asks for the rule table (see Output Format).
**Strict** — procedures, error messages, tool and function descriptions, inter-agent instructions, safety text. Anywhere a wrong reading has a cost. Apply every rule below, including the hard length caps and one-word-one-meaning discipline.
**STE-flavored** — READMEs, PR descriptions, changelogs, explanatory prose. Apply the structural rules in full and treat the lexical rules as advisory (see Core Rewrite Rules for that split). In practice that means keeping the sentence length caps, active voice, simple tenses, no phrasal verbs, no semicolons, no nominalization and no marketing adjectives, while dropping the one-word-one-meaning lockdown: prose needs some range, and a strict rewrite of prose reads as a personality transplant rather than a clarification.
The two modes and the structural/lexical split are the same distinction seen from two directions. The split says which rules this skill can verify without ASD's dictionary. The modes say which of them to enforce for a given kind of text.
## Source and Scope
This skill encodes the **rule categories** of ASD-STE100 Issue 9 (Jan 2025): 53 writing rules across 9 sections covering word choice, grammar, sentence structure, and style, backed by a dictionary of ~900 approved words (one meaning, one part of speech each) and ~1,200 words to avoid with suggested replacements. See `references/writing-rules.md` for the full rule summary and citations.
It does **not** reproduce ASD's ~900-word approved dictionary verbatim. ASD-STE100 is free to obtain, but it is not free to redistribute: Issue 9, page 2 states that "no reproduction or publication of it, in whole or in part, shall be made without the written authority of an officer of ASD," and grants free reproduction rights only to eight listed categories (ASD/AIA/AIAC member associations and their member companies and customers, member-state defence ministries, A4A, airworthiness authorities, and universities and research institutes for educational purposes). This project is in none of them, so the dictionary stays out of this repo.
Instead, this skill applies the *underlying principle* (pick the plainest, most common word available and use it the same way every time) rather than checking against a fixed word list. When exact ASD-approved wording matters (e.g. actual aircraft maintenance documentation), get the standard and check word-by-word against the real dictionary. Request it from the [official downloads page](https://www.asd-ste100.org/STE_downloads.html) — note that this is a request form that emails you a link, not a direct download.
## Core Rewrite Rules
STE's rules divide into two kinds, and this skill can only fully deliver one of them. **Structural rules** are self-contained: they describe sentence shape, and you can apply them from the description alone. **Lexical rules** are defined entirely by the official ~900-word dictionary, which this skill deliberately does not reproduce (see Source and Scope). Without that dictionary, the lexical rules degrade from a checkable standard into a preference for plain words.
Apply the structural rules with confidence. Apply the lexical rules as a direction of travel, and say so in your output rather than implying dictionary compliance you cannot verify.
### Structural rules — apply these
| Rule | Do | Don't |
|---|---|---|
| Active voice | "The agent deletes the file." | "The file is deleted (by the agent)." — unless the actor is genuinely unknown or irrelevant |
| No phrasal verbs (Rule 9.3) | "Remove the panel." / "Start the job." | "Take off the panel." / "Spin up the job." — a two-word verb has meanings the parts do not predict |
| One instruction per sentence | "Open the file. Read line 3." | "Open the file and read line 3, then check if it matches." |
| Sentence length | ≤20 words for instructions/procedures, ≤25 words for descriptions | Long compound/subordinate-clause sentences |
| No semicolons (Rule 8.1) | Split into separate sentences | Any semicolon at all — STE bans the mark outright, not only as a clause join. (Rule 8.1 permits every other standard punctuation mark. The em dash is *not* banned by STE, though it often signals a sentence that should be split.) |
| Noun clusters | ≤3 words stacked as a noun phrase ("fuel pump valve") | 4+ word noun stacks ("high pressure fuel pump inlet valve assembly") |
| No ellipsis | Keep the subject, verb, and article explicit even if it reads longer | Drop words to save space ("Files not backed up will be lost" → ambiguous which files) |
| Keep modality | "The request **may have** failed." stays "may have" | Promote a hedge to a fact ("The request failed.") or invent a certainty the source did not state |
| Paragraph limits | One topic per paragraph, ≤6 sentences | Multi-topic paragraphs |
| Lists for sequences | Use a numbered or bulleted list for 3+ steps or conditions | Bury a sequence inside one prose sentence |
### Lexical rules — direction of travel only
| Rule | Do | Don't | Why it is weaker here |
|---|---|---|---|
| One word, one meaning | Pick one verb for one action and reuse it every time (e.g. always "check", never mix "check"/"verify"/"confirm" for the same action) | Rotate synonyms for the same idea across a document | Consistency within a document is checkable. Which word is the *approved* one is not, without the dictionary. |
| One part of speech per word | "Apply oil to the valve" (oil = noun) | "Oil the valve" (oil = verb) | Whether "oil" is approved as a noun only is a dictionary fact. Prefer the noun form when both read equally well. Do not claim compliance. |
| Verb, not noun (Rule 3.7) | "Analyze the log." | "Perform an analysis of the log." — a noun form of an action makes the sentence longer and hides who acts | Rule 3.7 says "use an **approved** verb to describe an action." Preferring the verb form is safe to apply anywhere. Knowing which verb is the approved one needs the dictionary. |
| Domain terms | Keep necessary technical nouns/verbs, but define them once if not common English (STE allows a project-specific glossary beyond its base dictionary) | Use jargon without ever defining it | The glossary allowance is real STE, but the base dictionary it extends is absent. |
### Simple tenses — apply with one exception
STE permits infinitive, imperative, simple present, simple past, simple future, and past participle as adjective. It excludes present perfect and other compound forms: "we received the report", not "we have received the report".
Aircraft manuals never need present perfect, so the exclusion costs the standard nothing. Other text is not always so lucky. "The job has completed" (and its output is available now) and "the job completed" (at some past point) are different statements, and status text frequently needs the first. **Where the compound form carries information the simple form cannot — current relevance, or a hedge as in "may have failed" — keep it and flag the departure.** Elsewhere, follow the rule.
## Scan Checklist
These six habits cover most of what makes machine-written English hard to parse. Each one is mechanical: you can point at the exact word or punctuation mark that breaks the rule, with no judgment call. Scan for all six before you rewrite anything.
1. **Synonym rotation** — the same thing gets several names in one document ("the user", "the customer", "the client"). The reader cannot tell whether they are one thing or three. Fix: pick one name, use it every time.
2. **Hedge stacking** — helper verbs and qualifiers pile up until the sentence asserts nothing ("it is important to note that this may potentially help to improve"). Fix: state the claim, or delete it.
3. **Nominalization** — an action frozen into a noun ("perform an analysis of", "provides assistance to"). Fix: use the verb ("analyze", "helps").
4. **Marketing adjectives** — words that claim quality instead of showing it: seamless, robust, powerful, cutting-edge, effortless, blazing-fast. Fix: delete, or replace with the measurement that earns the claim.
5. **Run-on sentences** — several ideas joined by semicolons or em dashes. Fix: one idea per sentence.
6. **Soft phrasal verbs** — spin up, reach out, dive into, kick off. Fix: use the single plain verb (start, contact, read, begin).
## Process
1. Pick the mode (Strict or STE-flavored). Say which only when the user asked for the rule table — see Output Format.
2. Read the input text once for meaning — do not start rewriting before you understand what it must still say afterward.
3. Walk it sentence by sentence. Flag every rule violation from the Core Rewrite Rules tables and every habit from the Scan Checklist. In STE-flavored mode, flag the lexical rules but do not enforce them. For a mechanical first pass over the structural rules, run `scripts/ste-lint.py` (stdin or file args, `--json` for structured output); it checks semicolons, sentence length, phrasal verbs, nominalization, marketing adjectives, synonym rotation, dangling-conjunction in supported list items, passive voice, and compound tenses, and by design never flags hedges or modality. `--baseline N` tolerates N hard violations (for adopting on existing docs); `--disable rule1,rule2` silences named rules.
4. Rewrite each flagged sentence to fix the violation while preserving the original meaning exactly. If a rewrite would drop necessary precision (a safety condition, a scope qualifier, a number), keep the longer phrasing and flag it instead of silently simplifying.
- **Check modality before you commit to a rewrite.** Hedges ("may", "could", "sometimes", "is likely to") carry the author's confidence, and confidence is content. A shorter sentence that upgrades a hedge to a fact is not a simplification — it is a different claim. This is the most common way a well-intentioned STE rewrite goes wrong, because hedges are exactly what a length cap tempts you to cut.
- Never add a fact the source did not state. A rewrite that reads better because it supplies a cause, a frequency, or a mechanism has stopped being a rewrite.
5. Output the rewritten text (see Output Format). Keep the mode choice and the rule analysis internal unless the user asked to see them.
6. If the input already complies, say so — do not force changes onto compliant text.
## Output Format
**Default: the rewritten text, and nothing else.** Most callers want a result they can paste straight into a tool description, an error string, or a prompt. Print the simplified text on its own. Do not add a preamble about this skill, a mode announcement, a violation count, a summary of what changed, a rule table, or a closing offer to explain further.
The one permitted addition: if step 4 kept a longer phrasing on purpose, add a single line after the text, prefixed `Kept as-is:`, naming the phrase and the precision that would have been lost. Omit the line when there is nothing to report.
**On request: the rule table.** When the user asks to see the reasoning — "show the diff", "which rules did it break", "explain the changes", "before/after" — output this table instead:
```markdown
| Rule violated | Original | Simplified |
|---|---|---|
| Present perfect tense | "We have received your request." | "We received your request." |
| Noun cluster (4+ words) | "the agent task queue priority handler" | "the handler that sets task-queue priority" |
Mode: Strict. 7 violations found.
```
Follow the table with a one-line note on anything you deliberately did **not** simplify, and why (usually: simplifying would lose required precision).
## Boundaries
**Will:**
- Rewrite ambiguous or dense English into short, single-meaning, active-voice sentences.
- Return the rewritten text alone by default, and name the rules it applied when the user asks.
- Preserve every fact, condition, and scope qualifier in the original.
- Preserve the strength of every hedge, and add no claim the source did not make.
- Suggest a one-line glossary entry for domain terms that must stay.
**Will not:**
- Reproduce ASD's official ~900-word dictionary as if it were memorized verbatim — always treat the official download as the source of truth for exact approved wording.
- Simplify creative, marketing, or persuasive copy where voice and nuance are the point.
- Silently drop a safety condition, exception, or scope qualifier to shorten a sentence — it will flag the trade-off instead.
- Convert "may have failed" into "failed", or "could be caused by X" into "X is the cause" — losing a hedge changes the claim.
- Guarantee an aerospace/defense-grade STE-compliant document. This is a general-purpose clarity tool inspired by STE, not a certified STE authoring tool.
- Make weak content true or useful. STE fixes the *form* of a text, not its substance. A hollow paragraph rewritten under these rules becomes a clean, short, well-punctuated hollow paragraph. If the text has nothing to say, no rewrite fixes that — say so instead of polishing it.
- Shorten past the point of clarity. Cutting words is not the goal. Removing ambiguity is the goal. Past a certain point compression starts costing the reader time rather than saving it, so stop when the sentence is unambiguous, not when it is shortest.
## Additional Resources
- **`references/writing-rules.md`** — fuller summary of the 9 rule sections and dictionary structure, with citations to the official standard and secondary sources.
- **`examples/before-after.md`** — worked examples, including official STE examples and agent-output examples built for this skill.
- **`scripts/ste-lint.py`** — deterministic, stdlib-only linter for the structural rules, including dangling-conjunction in supported list items, plus a synonym-rotation check (one word, one meaning) scoped per file. Exit 1 when hard violations exceed `--baseline` (default 0); advisory findings (passive voice, compound tenses) never fail the run; `--disable` silences named rules. It never flags hedges or modality: those are content, not style, and `--selftest` asserts that "may have failed" passes clean.