ASD-STE100 Skill：用简化技术英语消除 Agent 输出歧义
英文标题：🔥 danyuchn/asd-ste100-skill
该 Claude Code skill 将密集、含糊的英文改写为 ASD-STE100 简化技术英语，面向解析其他 Agent 输出、工具描述、错误信息和 Agent 间指令的 AI Agent。它提供 Strict 与 STE-flavored 两种模式，并按句检查歧义用词、复杂时态、被动语态、多重指令、名词堆叠、短语动词等问题，同时避免在改写中丢失事实、条件和范围限定。项目内置确定性 linter，但该工具只检查结构模式，不能证明改写前后语义或需求强度完全一致，也不包含 ASD 官方约 900 词的受控词典。开发者可通过 `npx skills add danyuchn/asd-ste100-skill` 安装，用于提高 Agent-to-Agent 消息及机器可读英文的明确性和可解析性。
678 B
56.9 KB
中文
ASD-STE100 Skill：面向 Agent 输出的简化技术英语
这是一个 Claude Code skill，可将密集、含糊的英文改写为 ASD-STE100 Simplified Technical English（STE）——航空航天和国防行业建立的受控语言标准，用于确保飞机维护说明不会被误读。
该 skill 将同一套严格规范用于另一类读者：AI Agent。当 AI Agent 解析另一 Agent 的输出、工具描述、错误消息或 Agent 间指令时，可能没有人类参与来消除歧义。
为什么选择 STE，以及为什么面向 Agent
STE 的存在是因为对飞机指令的误读可能致人死亡，而其预期读者通常是非英语母语者，且无法联系作者寻求澄清。该标准的解决方法是：每个词只表达一个含义，使用主动语态、简单时态，每句只包含一条指令，句子简短，不省略词语。
解析另一 Agent 输出的 LLM Agent 处于极其相似的位置：没有后续沟通渠道，也无法询问“你的意思是 X 还是 Y？”。那些防止机械师误读扭矩规格的规则，同样可以防止下游 Agent 误读工具描述或 Agent 间消息。
| 改写前 | 改写后 |
|---|---|
| “该工具会尝试在已配置的多个后端之间同步状态；如果检测到冲突，它可能会根据已设置的策略自动解决冲突，否则会将冲突呈现出来供人工审查。” | “该工具尝试在已配置的后端之间同步状态。如果它发现冲突，它会读取已配置的策略。如果该策略允许自动解决，工具可以在没有用户参与的情况下解决冲突。如果工具未解决冲突，它会报告该冲突以供人工审查。” |
| “处理你的请求时可能发生错误，原因可能是预期数据格式不匹配，而这可能由过时的客户端版本引起。” | “你的请求可能失败。原因可能是数据格式与服务器预期的格式不匹配。过时的客户端可能导致此不匹配。请检查你的客户端版本。” |
更多示例，包括对官方 STE 规则本身的说明，见 examples/before-after.md。
- 选择一种模式。Strict 适用于流程、错误消息和工具描述。STE-flavored 适用于 README、PR 描述和说明性文本。STE-flavored 保留句子规范，但不实施固定词汇表的严格限制。
- 阅读输入英文文本以理解其含义。
- 按句标记每一项规则违规：含糊的用词、现在完成时/复杂时态、施事不明确的被动语态、多指令句、过长的名词簇、省略词、超长句、短语动词、名词化动作、分号、叠加式模糊限定语和营销形容词。
- 改写每个被标记的句子——不删除原文中的任何事实、条件或范围限定。若更短的表述会失去必要精确性，则保留较长表述，并标记这一权衡，而非悄然简化。
- 仅输出改写后的文本——没有前言、模式声明或改动摘要——如果它刻意保留未简化内容，则额外输出一行
Kept as-is:说明。
如果要求展示推理过程（“show the diff”“which rules did it break”），它会改为输出一张改写前后对照表，并列出每项规则。
它检查的结构规则是机械性的——你可以指出违反每条规则的具体单词或标点符号。依赖 ASD 词典的规则只会被标记为建议，而不会被强制执行；需要判断力的规则则由你自行决定。
该 linter 仅检查结构模式。它不会对比原文与改写版本，不会验证需求强度是否保持不变，也不会证明改写保留了原意。零违规结果仅表示已配置的结构检查未发现问题。
确定性 linter 会检查分号、一小部分柔性短语动词（spin up、reach out、dive into、kick off、circle back、touch base）、名词化、营销形容词、被动语态、现在完成时形式（包括诸如 “has run” 的不规则分词）、长句、同义词轮换，以及受支持列表项中的悬空连词。它不检查名词簇长度（这需要词性标注），也不知道列表之外的短语动词，因此 “take off the panel” 可以通过检查。它绝不会标记模糊限定语或情态表达。
仓库自身的文本并不能干净地通过 lint：规则表引用了它们所禁止的模式，且部分句子较长。使用 python scripts/ste-lint.py --baseline 41 SKILL.md 进行检查，并将检查结果视为示例，而非缺陷。
悬空连词规则会检查行首的列表标记：其前可有零到三个前导空格，且标记后使用 ASCII 空格。它支持无序标记 -、* 和 +，以及以 . 或 ) 结尾的有序数字标记，例如 1. 或 1)。它会检查缩进的续行，直至最后一行有意义的内容。它不会解析引用块中的列表语法、惰性续行或完整的嵌套列表语义。前导空格为四个或更多的独立行不会被视为列表标记。在活动列表项中，计算出的内容列位置上的缩进会被视为续行文本。围栏检测遵循 linter 现有的简单规则：去除首尾空白后，以三个反引号或三个波浪号开头的行会切换围栏状态。
刻意设为无效的 examples/linter-edge-cases.md 文件展示了不完整的 Markdown 列表项。运行 python scripts/ste-lint.py examples/linter-edge-cases.md，即可确认 linter 报告了预期的两项发现。该文件是测试夹具，不应作为合规的 STE 文本使用。
它不会复现 ASD 官方约 900 个词的核准词典。该标准可以免费获取，但不能自由再分发：第 9 版只允许在获得 ASD 书面授权后复制，或者允许由八类列出的组织复制，而本项目不属于其中任何一类。该 skill 应用其底层原则（使用最朴素可用的词，并且每次以相同方式使用），而不是依据固定词表进行检查。如需经过认证、符合 STE 标准的文档，请使用真正的标准。
完整规则摘要和引用资料：references/writing-rules.md。
快速安装（npx skills）
安装此 skill 的最快方式是使用 skills CLI——无需克隆，无需配置路径。在项目根目录运行：
npx skills add danyuchn/asd-ste100-skill
这会从 GitHub 仓库拉取该 skill，并为当前项目安装它。CLI 会向 skills.sh 排行榜发送匿名安装遥测数据（skill 名称和时间戳，不含个人或设备信息），以帮助对 skill 进行排名。设置 DISABLE_TELEMETRY=1 可退出该数据收集。
之后可使用 npx skills update 更新。
git clone https://github.com/danyuchn/asd-ste100-skill ~/.claude/skills/asd-ste100
这会将仓库克隆至 ~/.claude/skills/，使该 skill 可用于每个 Claude Code 项目。它最适合贡献者，以及希望通过 git pull 获得实时更新工作副本的用户。
通过请求简化或澄清英文文本来触发：
Disambiguate this tool description
Rewrite this error message so an agent can't misparse it
Apply ASD-STE100 to this instruction
或者粘贴文本，并要求 Claude “disambiguate this” / “apply STE100 to this” / “reduce ambiguity in this output”。
你将只获得改写后的文本，不会收到其他内容。要查看应用了哪些规则，请在请求中加入“show the diff”或“explain the changes”。
适用场景：Agent-to-Agent 消息、工具/函数描述、错误消息、系统提示词、Agent 间指令——任何必须由机器或非母语读者在无法向人询问时解析的英文文本。
不适用场景：创意写作、营销文案，或任何以文风和细微语感为重点的内容——STE 的设计本意就是刻意平实且直白。
有一项限制值得预先说明：它修复的是文本形式，而非文本实质。一段没有实质内容的文字，经过处理后会变得简短、清晰，但依然空洞。
MIT——见 LICENSE。
English / 原文
ASD-STE100 Skill — Simplified Technical English for Agent Output
A Claude Code skill that rewrites dense, ambiguous English into ASD-STE100 Simplified Technical English (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 |
|---|---|
| "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.
- 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.
- Reads the input English text for meaning.
- 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.
- 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.
- 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.
Quick Install (npx skills)
The fastest way to install this skill is the skills CLI — no clone, no path setup. Run it from your project root:
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.
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.
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.
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.
MIT — see LICENSE.