跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

technical-english

Controlled-language rules for technical writing in two registers — strict mode for procedural text and flavored mode for explanatory prose. Strict mode covers skill descriptions, procedure steps, agent definitions, output contracts, error text, and issue acceptance criteria. Flavored mode covers references, READMEs, ADR rationale, and PR bodies. Use when authoring or editing a SKILL.md, a skill description, an agent definition, a bees issue, an ADR, or a README. Use when reviewing prose for passive voice, hedged directives, terms used with two meanings, or overlong sentences.

vinnie357 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add vinnie357/claude-skills --skill technical-english

技能说明


name: technical-english description: Controlled-language rules for technical writing in two registers — strict mode for procedural text and flavored mode for explanatory prose. Strict mode covers skill descriptions, procedure steps, agent definitions, output contracts, error text, and issue acceptance criteria. Flavored mode covers references, READMEs, ADR rationale, and PR bodies. Use when authoring or editing a SKILL.md, a skill description, an agent definition, a bees issue, an ADR, or a README. Use when reviewing prose for passive voice, hedged directives, terms used with two meanings, or overlong sentences. license: MIT

Technical English

Technical English is a controlled-language discipline for procedural and explanatory writing. It sets one strict register for instructions and a second, looser register for context and rationale.

Two registers

Pick the register from the artifact, not from taste.

ArtifactRegisterWhy
Skill descriptionsStrictClaude parses these at load; ambiguity misfires activation
Procedure stepsStrictA step is an instruction, not a discussion
Agent definitionsStrictDispatch logic runs unattended; one meaning per term
Slash commandsStrictArguments and flags need exact, repeatable wording
Output contractsStrictA caller parses a worker's report by its shape
Error and CI-failure textStrictA reader hits this under time pressure
Bees titles and acceptance criteriaStrictCriteria must be checkable, not interpreted
Commit subjectsStrictOne line, one fact, searchable history
ADR Decision linesStrictThe decision is the artifact; hedging voids it
SKILL.md explanatory sectionsFlavoredContext needs nuance and connecting prose
references/*.mdFlavoredDepth material rewards variety and color
READMEsFlavoredA README sells the project before it instructs
ADR Context and ConsequencesFlavoredTrade-offs need qualification, not a checklist
PR bodiesFlavoredA reviewer wants the story, not a manual

The strict rule set

  1. Give every term exactly one meaning and one part of speech, and hold that meaning across the whole document set.
  2. Write every instruction and every procedure step in active voice.
  3. Reserve passive voice for description, and only when no one knows the actor.
  4. Use five tenses only: imperative, simple present, simple past, simple future, infinitive.
  5. Put one instruction in each sentence.
  6. Cap procedure sentences at 20 words and description sentences at 25.
  7. Cap each paragraph at 6 sentences and one topic.
  8. Never drop an article, a subject, or a verb.
  9. State a warning, a caution, or a precondition before the step it governs.
  10. Choose the short word, the concrete noun, and the verb over its noun form.
  11. Cut a qualifier or an adverb that only restates its verb.
  12. Reread the draft once, and cut what the first pass missed.

Worked before/after pairs for eleven of the twelve, several pulled from this repo's own text: references/strict-mode-rules.md.

Word choice

Pick the plainest available word, and use it the same way every time. The pairs below recur in this repo; the plain form wins in strict-mode text.

Substitute only where the plain word carries the same meaning. A term of art stays: implement names a tier and a Behaviour relationship here, and ensure states a guarantee that confirm (a verification) does not.

WordyPlain
leverageuse
performdo
additionalmore
functionalityfeature
modifychange
currentlynow

Hedges vs directives

A directive states what to do. A hedge states an unconfirmed claim. Mixing the two inside a procedure buries the actual instruction under a guess.

  • A step is a directive: Run mise run ci. Never You might want to run mise run ci.
  • Keep a hedge only where the evidence is thin, and name the gap: "requires verification" carries more information than "may work."
  • /core:anti-fabrication sets the canonical rule for uncertainty markers, banned superlatives, and evidence-based claims. Follow that skill directly; this section is a pointer, not a restatement.

Warnings precede the step

State a warning, a caution, or a precondition before the step it governs, never after. A reader who executes line by line has already acted by the time a trailing warning arrives. plugins/core/skills/security/SKILL.md:45 states its warning immediately before the command table it governs — copy that placement.

Where this binds

ContextBinds to
Main-loop conversationThe active output style — core ships Plain Technical, opt-in
Subagent prompts and reportsThis skill plus the response contract
Authored artifacts (skills, ADRs, READMEs)This skill plus review
CIVale, via mise run test:prose

Select the shipped style with /config → Output style → Plain Technical, or set "outputStyle": "Plain Technical" in .claude/settings.local.json. It takes effect after /clear or in a new session. It is never forced on you: it does not override a style you already chose. The style ships with the core plugin and with all-skills; a plugin that vendors this skill alone does not carry it.

What CI checks and what it cannot

Vale runs as mise run test:prose, inside mise run test. It checks banned superlatives, clutter phrases, weak qualifiers, hedged directives, sentence length, and nominalizations. Rule files live in styles/Strict/ and styles/Flavored/; .vale.ini picks the register by path. See /vale:vale for the tool itself — extension points, scopes, alert levels, and how to author a rule.

A rule reports at warning while its findings burn down, then moves to error once it reaches zero. Clutter gates today; the rest report. Burn-down is claude-skills-307.

Sentence length skips code. Heading

阅读完整来源 ↗