Penpot OpenCode ste 技能：把 ASD-STE100 简化技术英语变成可执行的 AI 写作规则

本文解析 Penpot 仓库中 .opencode/skills/ste/ 目录下的 ste 技能：它如何将航空业 ASD-STE100（Simplified Technical English，简化技术英语）标准转译为一套 AI 代理可以直接执行的写作规则。读完本文，你可以完整掌握该技能的触发机制、句子/动词/词汇/标点四类核心规则、配套的"禁用词→替换词"工作字典、改写前后示例，以及它在 Penpot 仓库 AGENTS.md 中的调用约定，并能在自己的项目中参照其结构搭建一套"标准→提示词"的技能文件。

1. 技能文件结构与定位

ste 技能位于 .opencode/skills/ste/，是 Penpot 仓库内置的一套 OpenCode 代理技能（同目录群还包括 code-review、ripgrep、planner、create-pr 等技能，见 .opencode/skills/）。其文件结构为：

• .opencode/skills/ste/SKILL.md — 技能主体：触发条件、分类步骤、核心规则、自检清单；
• .opencode/skills/ste/references/word-substitutions.md — 工作词表：禁用词→替换词映射，以及"一词一义"的判定裁决；
• .opencode/skills/ste/references/examples.md — 改写示例：动词形式、词汇、名词簇、程序性文本、警告语句的前后对照。

技能主体以 YAML frontmatter 声明元数据，其中 name: ste；description 字段承担了关键的"触发范围"职责。它明确写道：只有当用户显式点名该技能时（输入 /ste，或直书 "use the ste skill" / "apply ASD-STE100"）才允许加载；对于 "simplify this"、"make it clearer"、"write technical documentation" 这类改写意图的变体表达，一律不触发，按正常方式作答即可。这种"显式调用门控"写法与仓库中其他技能（如 .opencode/skills/code-review/SKILL.md 用 description 声明"合并前使用"）形成对比——ste 是刻意收窄触发面的一个实例。

技能正文开头还内置了一条合规声明（面向模型自身，不进入输出）：ASD-STE100 官方规范及其词典受 ASD 版权保护，该技能编码的是"改写后的规则 + 公开来源的单词表"，因此：面向航空航天/国防的认证交付物，须告知用户完整合规需要官方规范（免费获取）加人工签核；永远不得声称"经过认证的合规"。这条边界约束是理解该技能能力上限的前提。

2. Step 0：先分类，再动笔

SKILL.md 要求模型在写下第一句话之前，先判断文本类型：

• 程序性文本（procedural）：别人要照着执行的指令；
• 描述性文本（descriptive）：解释、背景、描述。

所有后续限制（句子长度上限等）都依赖这个分类结果；混合文档按章节逐段分类。这一步是整个规则体系的前提——同一篇文章中，指令段落与说明段落适用不同的句子长度上限。

3. 核心规则全集

3.1 句子

• 程序性文本：每句最多 20 词；描述性文本：每句最多 25 词。
• 每段最多 6 句，一段只讲一个主题。
• 每句只含一条指令；仅当两个动作同时发生时才允许一句两个动作。
• 条件必须在指令之前："If the pressure decreases, close the valve."
• 不得为省词而省略冠词、主语或动词。"Ensure file exists" 是错的；"Make sure that the file exists" 是对的。"make sure" 之后的 "that" 必须保留。
• 词数统计规则：数字、带数字的单位、缩写、引号字符串、代码标识符、专有名词各计为 1 个词。

3.2 动词

• 仅允许以下时态形式：不定式、祈使式、一般现在时、一般过去时、一般将来时、以及作形容词的过去分词。
• 禁用现在完成时与进行时："We have received" → "We received"；"is being tested" → 换成简单形式。
• 禁止把 -ing 形式当动词用；-ing 词只允许出现在技术名称内部（"the mounting bracket"、"logging"）。
• 主动语态；被动语态仅允许用于描述性文本，且施动者未知或不重要时。
• 指令使用祈使式："Open the panel"，而不是 "You must open the panel" 或 "The panel should be opened."
• 动作表达为动词而非名词："compress the file"，而不是 "perform compression of the file."
• 情态动词只允许三种：can（可能性）、will（将来）、must（要求）。禁用 should、would、could、may、might。模糊表达要么变成事实，要么降级为 "can"："an explosion can occur."
• 禁用短语动词（phrasal verbs）："go down" → "decrease"，"set up" → "install"，"carry out" → "do"。

3.3 词汇

• 一个词、一个含义、一个词性，全篇一致使用；禁止同义词轮换——一个事物选定一个名字后反复复用。
• 起草前先替换未获批词汇：要求模型读取 references/word-substitutions.md 并应用，它是该技能的"工作字典"（详见第 4 节）。
• 领域名词（部件名、工具名、产品名、UI 标签）与领域动词（drill、ream、boot、compile）属于技术名词/动词，原样保留、每个保持一致使用，且不把名词当动词用、也不把动词当名词用。
• 名词簇（noun cluster）最多 3 个词（"overhead panel light" 已到上限）。更长的簇要用介词拆解，或首次出现时连字符化："main-gear-door retraction-winch handle."
• 使用美式英语拼写。
• 禁用拉丁缩略语："e.g." → "for example"，"i.e." → "that is"，"etc." 直接删除。

3.4 标点

• 禁用分号——拆成两个句子。
• 括号只用于：引用、缩写、条目编号。
• 起单一单位作用的一组词要连字符化；连字符词计为 1 个词。
• 禁止缩略形式（contractions）。

3.5 警告、注意与备注

三类提示的定义是固定的：

• WARNING = 有受伤或死亡风险；
• CAUTION = 有损坏风险；
• NOTE = 仅信息性内容，永不包含指令。

警告/注意的句式要求先命令或条件，后风险：

WARNING: Do not touch the terminal. The terminal has a dangerous voltage.

NOTE 同样受 25 词描述性上限约束。

4. 工作词表：word-substitutions.md

word-substitutions.md 开头声明其编译自公开二手来源（STEMG/ASD 公开页面、TechScribe、Acrolinx、培训材料），是"工作近似值，不是官方 ASD 词典"，并给出兜底策略：表中未列出、但读起来正式或拉丁语源的词，优先选最短的常用替代词。

4.1 禁用词 → 替换词映射（完整继承）

不要使用	改用
utilize, leverage, employ	use
commence, initiate, begin, originate	start
terminate, cease, conclude	stop, end
ensure, verify, confirm, validate, check	make sure (that), examine
perform, conduct, execute, carry out	do
facilitate, assist	help
obtain, acquire, procure	get
sufficient, adequate	enough
approximately	about
prior to	before
subsequent to, following (介词用法)	after
adjacent to	near
accomplish	do
additional, supplementary	more
attempt	try
require, necessitate	need, must
mandatory	necessary
indicate, signify	show
observe (=watch)	look at, examine
rotate	turn
deactivate	turn off, set to off
activate, energize（除非是技术动词）	turn on, start
toxic	poisonous
in order to	to
via, by means of	through, with
due to, owing to	because of
in the event of/that	if
accessible	（改写为 "you can get access to"）
remainder	rest
demonstrate	show
modify, alter	change
construct, fabricate, build	assemble, make
retain	keep
locate (=find)	find
depress (a button)	push, press
proceed	continue, go

4.2 "一词一义、一词性"的规范裁决

词表对若干易混词给出了明确裁决，值得逐条理解：

• close — 仅动词：移动到阻断流动的位置，或操作断路器。形容词用法未获批 → 用 near（"do not go near the propeller"）。
• test — 仅名词："do a test"，永远不写 "test the system."
• check — 不得作验证义动词 → 用 "make sure that" 或 "examine."
• follow — 仅表示"在……之后"；表示遵守规则/步骤用 obey："Obey the safety instructions."
• fall — 仅表示"受重力下落"；数量变化用 decrease；永不指季节。
• oil — 仅名词。"Oil the bearing" → "Put oil on the bearing" / "Lubricate the bearing."
• right — 仅表示方向，永远不作 "correct" 解。
• clear — 意为"无阻碍"。"Wheels are clear of the ground" → "wheels do not touch the ground."
• help — 仅动词；名词形式是 aid（"with the aid of a mirror"）。
• above / below — 仅指物理位置；数量比较用 more than / less than。
• about — 两个获批义项："大约"与"关于"。需谨慎使用。
• turn — 旋转的通用动词；表示电源状态用 "turn on / turn off"。
• level — 名词和形容词均获批（"一词一义"规则下的记录在案例外）。

4.3 高频违规功能词

• should / would / could / may / might — 永不使用。要求 → must；可能性 → can；将来 → will。
• etc. — 删除，或写出完整清单。
• e.g. / i.e. — 写作 "for example" / "that is."
• any / appropriate / applicable / relevant 作模糊限定 — 替换为所指的明确对象。
• there is / there are 开头 — 用真实主语改写："There are three bolts on the panel" → "The panel has three bolts."

5. 改写示例：examples.md 的前后对照

examples.md 提供成对的 before/after 改写，是规则落地的最直接参照。

5.1 动词形式

Before	After
We have received the technical reports from HQ.	We received the technical reports from HQ.
This device has been being used at Boeing since 2005.	Boeing started to use this device in 2005.
The test is continued by the operator.	Continue the test.
The screws should be replaced.	Replace the screws.
The system is currently running diagnostics.	The system does diagnostic tests now.

5.2 词汇与措辞

Before	After
Ensure file exists before running.	Make sure that the file exists before you run the command.
Rotate the cover until the jacks are accessible.	Turn the cover until you can get access to the jacks.
Extend the jack until the wheels are clear of the ground.	Extend the jack until the wheels do not touch the ground.
Make sure that these steps are followed.	Obey these steps.
Utilize approximately 3 liters of water.	Use about 3 liters of water.
Perform a compression of the log files prior to upload.	Compress the log files before you upload them.

5.3 名词簇拆解

Before	After
Main gear door retraction winch handle	Main-gear-door retraction-winch handle
Runway light connection resistance calibration	Calibration of the resistance of the runway light connection
Remove the engine transmission housing attachment bolts.	Remove the bolts that attach the transmission housing to the engine.

5.4 程序性文本改写（条件在前，一句一指令）

改写前（单句 40+ 词，动作交错，条件埋在中段）：

You should check that the reservoir has been filled with the correct fluid and, after attaching a clear tube to the bleed screw while ensuring its free end is submerged, the pedal can be pumped and held so that opening the screw releases trapped air.

改写后（编号步骤，条件前置，每句一动作）：

1. Fill the reservoir with the correct fluid.
2. Attach a clear tube to the bleed screw.
3. Put the free end of the tube in a container of fluid.
4. Push the pedal three times. Hold the pedal down.
5. Open the bleed screw one half turn. Air and fluid flow into the tube.
6. Close the bleed screw. Release the pedal.
7. If air continues to come out, do steps 4 thru 6 again.

5.5 警告与注意（先命令，后风险）

改写前：

Note that serious data loss may potentially occur if the --force flag is used against production.

改写后：

CAUTION: Do not use the --force flag on the production database. The flag deletes the rows that do not match the source.

另一组对照："Touching the terminal could result in electrocution." → "WARNING: Do not touch the terminal. The terminal has a dangerous voltage."

5.6 常见错误清单

• 丢冠词："Insert pin in bracket" → "Insert the pin in the bracket."
• 同义词轮换：同一动作出现 check/verify/confirm → 全篇只用一个词。
• 模糊限定："you may want to"、"it is recommended that" → 祈使句或 "must."
• 指令藏在 NOTE 里：NOTE 永不发指令；把指令移到编号步骤中。
• 分号连接两个分句 → 拆成两个句子。
• "There are three bolts on the panel" → "The panel has three bolts."

6. Step 2：交付前九项自检

SKILL.md 要求起草完成后、回复之前，逐项扫描全文并修正所有命中项：

1. 超过 20/25 词句长上限的句子（按其文本类型）；
2. 缩略形式、分号；
3. "should"、"would"、"could"、"may"、"might"；
4. "has been"、"have been"、"had been"、"is being"、"was being"；
5. 被当动词使用的 -ing 词；
6. 名词前缺少冠词（a/an/the/this）；
7. 同义词轮换（同一对象出现两个名字）；
8. word-substitutions.md 禁用列中的任何词；
9. 先写风险、后写命令的警告句。

这套自检清单与第 3 节的核心规则逐条对应，构成"规则→产出→回扫"的闭环，是整个技能中保证输出一致性的关键机制。

7. 边界：什么内容不改

SKILL.md 末尾单列 "What NOT to touch" 一节，划定 STE 规则的适用范围边界：

代码块、命令字符串、文件路径、错误信息、引号中的 UI 文本、专有名词，一律保持原样不动。STE 只作用于包裹这些内容的散文部分。

这一条对技术文档场景至关重要：技术文章中的命令、API 名称、报错原文恰恰是信息密度最高的部分，任何"简化"都会破坏其可复制性。

8. 在 Penpot 仓库中的调用方式与集成证据

该技能不是孤立文件，它与仓库的代理约定显式联动：

• AGENTS.md 的 "Writing Rules" 一节写明："Use the ste skill when the user explicitly requests STE, /ste, or ASD-STE100." 这与 SKILL.md frontmatter 中"仅显式调用才触发"的声明相互印证，形成双重门控：代理指南层与技能描述层都要求用户显式点名，"帮我把句子改短"这类泛化请求不会加载该技能。
• 技能目录遵循 OpenCode 技能的通用约定：name + description 的 frontmatter 供代理发现与加载，正文是规则本体，references/ 子目录存放按需加载的辅助文件。SKILL.md 明确要求"起草前先读 word-substitutions.md，它很短"；"改写既有文本或不确定某条规则如何适用时，读 examples.md"——两个参考文件因此有各自的加载时机，而不是一次性全部塞入上下文。

适用前提与限制需要说明：该词表自述为公开来源的近似值，不构成官方 ASD 词典；技能本身也禁止对认证交付物声称合规。因此该技能适合把日常技术文档、注释、用户面向文案的写作风格约束在 STE 的"短句、主动、一词一义"纪律内，但不能替代官方规范加人工签核的认证流程。

9. 要点小结

ste 技能展示了一条把成熟语言标准工程化为提示词资产的完整路径：frontmatter 收窄触发面 → Step 0 文本分类决定参数 → 四类核心规则（句子/动词/词汇/标点）加警告句法 → 外置工作词表与示例库 → 九项自检回扫 → 明确的"不可触碰"边界。对想在自有仓库中落地类似"写作风格技能"的开发者而言，.opencode/skills/ste/ 目录（主体 + references/ 双参考文件的组织方式）是一个可直接参照的最小完整样板。