asd-ste100-skill
Otherdanyuchn/asd-ste100-skill
Claude Code skill that rewrites ambiguous English into ASD-STE100 style.
Overview
A Claude Code skill that applies ASD-STE100 Simplified Technical English rules to rewrite dense, ambiguous English so downstream AI agents cannot misparse it. It flags rule violations sentence by sentence, rewrites without losing facts, and ships a deterministic Python linter for structural checks. Modes cover strict procedures and looser explanatory prose.
README Preview
# ASD-STE100 Skill — Simplified Technical English for Agent Output\n\nA 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.\n\nThis 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.\n\n## Why STE, and Why for Agents\n\nSTE 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.\n\nAn 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.\n\n## Before / After\n\n| Before | After |\n|---|---|\n| "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." |\n| "An error may have occurred while processing your request due to a possible mismatch in the expected data format, which could be caused b
FAQ (3)
TroubleshootingWhy does the ASD-STE100 linter flag markdown tables as over-long sentences?
This was a splitter bug, fixed in PR #14. The linter did not strip markdown tables from the prose stream: table rows end in | instead of terminal punctuation, so header + delimiter + data rows glued into one 'sentence', and every | and --- token counted as a word — inflating counts past the 25-word sentence limit (e.g., a normal table counted 122 'words'). Update to the latest version: table structural tokens are no longer counted, while genuine violations inside cells are still detected. Workarounds for older versions: (1) end the last cell of every row with a period so the splitter breaks per row, or (2) convert the table to a vertical bullet list with one period-terminated item per row — which ASD-STE100 prefers anyway for lists of more than two items.
TroubleshootingWhy do the word counts in examples/before-after.md not match the example text?
Three of the four listed counts are wrong. The correct counts using whitespace splitting are: Example A (tool description) = 44 words, not 55; Example C (inter-agent instruction) = 36 words, not 42; Example D (README prose) = 34 words, not 36. Only Example B (error message) is correct at 28 words. All verdicts still hold — every example remains over its cited cap (25-word descriptive cap, 20-word instruction cap), so only the numbers need correcting, not the 'After' text. Verify any count yourself with len(text.split()) in Python. Note that the file does not state its counting method: these numbers assume whitespace-separated tokens with punctuation not counted, so a tokenizer that splits hyphenated words like 'lock-in' will produce different results. Relatedly, line 43 of the same file (the project's own prose, left behind by PR #7) contains a semicolon that violates the repo's own Rule 8.1 and should be removed.
TroubleshootingWhy does the README Before/After table contradict examples/before-after.md (hedges like "may have failed" rewritten as "failed")?
The README table (README.md:17-18) was not updated when PR #4 added the modality-preservation rule to examples/before-after.md, so both "After" cells demonstrate the exact anti-pattern the skill forbids (dropping hedges changes the claim). Fix: replace the two "After" cells with the corrected rewrites from examples/before-after.md.
Row 1 — keep the hedge: use Example A's "After": "The tool tries to synchronize state across the configured backends." Do not rewrite "will attempt to" as "synchronizes", and keep "may resolve" instead of "the tool resolves the conflict".
Row 2 — use Example B's "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." Do not use "The request failed... an outdated client is the most common cause" — the first asserts a failure the system only suspects, and the second invents a frequency claim not present in the input.
Note: contradictory Before/After pairs are worse than none, since a model reading both files treats the table as the strongest signal.