Rewrite agent messages using aviation maintenance grammar rules
When an agent reads another agent's output, sentence ambiguity can lead to unintended actions. This repository is a tool that restructures Simple Technical English (STE) rules from aviation maintenance manuals for communication between AI agents. It converts complex sentences into short, clear ones so that machines can read them without room for misinterpretation.
Why aviation maintenance rules apply to AI
In aviation maintenance, misreading instructions can result in loss of life, so strict rules were created that allow only one meaning per word and exclude passive voice. AI agents also lack a channel to ask 'what did this mean?' when interpreting another agent's output. The same principle applies: removing ambiguous expressions increases the likelihood that downstream agents will accurately understand tool descriptions or error messages.
How sentences are corrected
The tool analyzes input English text to find rule violations at the sentence level. It points out ambiguous word choices, complex tenses, passive voice with unclear agents, and cases where multiple instructions are mixed in one sentence. It rewrites each sentence without omitting any original facts, conditions, or scope limiters. If a shorter expression would compromise precision, the longer expression is kept, and the reason is stated. The final output provides only the rewritten text, without summaries of changes or introductions.
Verification limits and precautions
The built-in linter checks only structural patterns such as semicolons, specific colloquial verbs, nominalization, marketing adjectives, passive voice, present perfect, long sentences, synonym repetition, and missing conjunctions. It does not check noun cluster length or colloquial verbs outside of lists, and it never flags hedging expressions or modal verbs. A violation count of zero means no issues were found in the configured structural checks; it does not verify meaning preservation between the original and rewritten text or the maintenance of requirement strength. Additionally, it does not reproduce the list of approximately 900 approved words from the official ASD dictionary, and actual standards must be used when certified STE documents are required.
Installation and usage
Run npx skills add danyuchn/asd-ste100-skill from the project root to install it in the current project. To use it in all projects, clone the repository to the ~/.claude/skills/asd-ste100 path. To use it, request actions such as 'make this tool description clear' or 'rewrite this error message so agents do not misunderstand it.' To review the applied rules, add requests like 'show the differences' or 'explain the changes' to receive a comparison table by rule.
Who this tool is for
It is suitable for English text that must be interpreted by machines or non-native speakers without human intervention, such as inter-agent messages, tool function descriptions, error messages, and system prompts. It is not suitable for content where voice and nuance are important, such as creative writing or marketing copy. The tool changes the form of the text but not the content. A paragraph with thin content will become short and clean but will remain thin. It is distributed under the MIT license, and telemetry transmission can be disabled with the DISABLE_TELEMETRY=1 environment variable.