Codex skill for clear technical writing

SKILL.md

name	technical-writing
description	Write clear, simple technical prose and check it with the vale CLI. Applies to documentation, READMEs, PR descriptions, GitHub comments, code comments, commit messages, specifications, and implementation plans (never to code). Use when writing or editing technical text, or when asked to make writing plain, clear, or less AI-sounding.

technical-writing

Use simple language in all technical prose. This covers documentation, READMEs, pull request text, GitHub comments, commit messages, code comments, error messages, specifications, and implementation plans. It does not cover code, identifiers, or command syntax.

Write simply

• Prefer the short common word over the formal one.
• Use one name for one thing. Do not switch names for the same item.
• Use the active voice and name the actor.
• Put one statement or one instruction in each sentence.
• Keep one topic per paragraph.
• For procedures, write a numbered list with one imperative action per item. Put a condition before its command.
• Delete filler. State the point in the first sentence.
• Write only the requested text, without preamble or closing summary.
• Use American spelling.

Check with vale

Check the finished text with the vale CLI. The global config in ~/.config/vale/ applies to any path.

1. If the text is not already in a file, write it to a scratch file with a .md extension.
2. Run vale <file>.
3. Read each finding and fix it, unless the fix would make the writing worse.

Zero findings is not the goal. Treat the output as advice:

• A finding can be a false positive, such as a flagged word inside a quote or a title.
• When you mention a flagged word as a specimen, wrap it in backticks. Vale skips code spans.
• You have the last word. If a vale rule conflicts with good writing, good writing wins.