rtl-writing · diff
git:20261106.7fb37ec to git:20261107.d32c0dc
42 added, 73 removed. Audit A to A.
---
name: rtl-writing
description: "Write right-to-left languages — Hebrew (עברית), Arabic (العربية), Persian (فارسی), Urdu — mixed with English technical terms so they render correctly, in chat and in files (Markdown, Word, LaTeX, PowerPoint). Use when the user types /rtl-writing, /academic-students:rtl-writing or the old /hebrew-with-english; when they complain that lines come out flipped, mirrored or with punctuation on the wrong side (\"השורות יוצאות הפוכות\", \"הנקודה קופצת\", \"النص مقلوب\", \"the Arabic is mirrored\"); when they ask for an RTL document, summary or slide deck that contains English terms; or when another skill in this plugin is about to write RTL prose into a file. Once invoked, keep applying it to every later reply until the user says to stop. Do not trigger just because the user wrote in an RTL language, and not for translation requests."
license: MIT
---
-
# RTL writing (Hebrew, Arabic, Persian, Urdu with English terms)
## Purpose
- Mix right-to-left prose (Hebrew, Arabic, Persian, Urdu) with English technical terms without breaking
- right-to-left rendering — in the chat UI, in
- Markdown files, and in Word, LaTeX and PowerPoint documents. The failure this skill prevents looks small (a line
- that starts with an English word flips to left-to-right, punctuation jumps to the wrong side) and reads as broken
- to every RTL reader. The rules and the checker are the same for every RTL script; the examples are Hebrew,
- and `references/arabic-persian-urdu.md` adds what differs for the other languages. The skill never translates technical terms: commands, identifiers, product names and
- terms of art stay in English inside Hebrew sentences.
-
- ## When this triggers
-
- - The user invokes it (`/rtl-writing`, or the agent's namespaced form of it) — then it stays on for
- the whole conversation until they say to stop.
- - The user complains about direction: "השורות יוצאות הפוכות", "הנקודה קופצת לצד השני", "the Hebrew is mirrored".
- - The user asks for Hebrew output that will contain English terms: a summary, a report, a `.docx`, a LaTeX
- section, slides.
- - Another skill in this plugin (assignment-coach, academic-writing, exam-prep, lecture-notes, study-planner,
- moodle-sync) is about to write Hebrew prose into a file.
-
- Not for: translating a text into English, questions about Hebrew grammar, or a Hebrew message that needs no
- special handling (plain prose with no English tokens renders fine on its own).
-
- ## Workflow
+ Mixed RTL + English text renders by one rule: each line (paragraph, bullet, heading, table cell, bold label)
+ takes its direction from its **first letter**. Start a line with an English word, number, symbol, emoji, link
+ or inline code and the whole line flips left-to-right and its punctuation jumps. So every line opens with an
+ RTL word. Never translate technical terms: names, commands and terms of art stay in English inside the
+ sentence. Once invoked, this applies to every later reply until the user says stop. Examples are Hebrew;
+ for Arabic, Persian or Urdu also read `references/arabic-persian-urdu.md` once.
- 1. **Pick the output format** and read the matching reference before writing:
- - chat reply or Markdown file → `references/chat-markdown.md` (the core rules: every line opens with a Hebrew
- word, punctuation anchoring, tables, code-block neighbours, bold labels).
- - Word document → `references/docx.md` (`w:bidi` on paragraphs, `w:rtl` on runs, styles, fonts).
- - LaTeX → `references/latex.md` (`polyglossia`, `\textenglish`, fonts, math inside Hebrew).
- - PowerPoint → `references/pptx.md` (`rtl="1"`, `rtlCol`, complex-script fonts).
- - Arabic, Persian or Urdu (any format) → also `references/arabic-persian-urdu.md` (openers, fonts, ZWNJ,
- Arabic-Indic digits).
- 2. **Terminology.** Look up the course's discipline family in `references/glossary/` (12 families; rule set in
- `references/glossary/README.md`): first mention = Hebrew term with the English in parentheses, afterwards
- whichever the course uses. A `COURSE.md` in the course folder may override individual terms.
- 3. **Write with the opening word chosen first.** For every line, heading, bullet, bold label and table cell,
- decide the Hebrew opener before the rest of the line. Fixing afterwards is where slips survive.
- 4. **Verify mechanically** (next section) before sending or saving. Then send the checked text word for word.
+ ## Chat replies — write once, no tool call
- ## Files in this skill
+ Write the reply directly: no reference to read, no checker to run, no draft to retype. Choose each line's
+ opening word **before** writing the rest of the line; that one habit prevents almost every slip.
- - `references/chat-markdown.md` — the rules, the high-risk spots table, the list of natural Hebrew openers.
- - `references/docx.md`, `references/latex.md`, `references/pptx.md` — how direction works in each format and how to set it from code.
- - `references/glossary/README.md` + `references/glossary/<family>.md` — Hebrew ⇄ English term pairs per discipline family.
- - `references/arabic-persian-urdu.md` — what changes for Arabic-script languages: natural openers, fonts, LaTeX and Word settings, digits, ZWNJ.
- - `scripts/check_rtl.py` — any RTL script; checks Markdown/chat text; `--fix` prints a suggested rewrite per failing line (never edits); `--json`.
- - `scripts/check_docx_rtl.py` — lists Hebrew paragraphs in a `.docx` that lack `w:bidi` (resolves style inheritance); `--json`.
+ 1. **Hebrew opener on every line.** "Python is…" → "השפה Python היא…"; a name → "החברה Marvel…",
+ "הסרט *Iron Man*…"; "`malloc` returns" → "הפונקציה `malloc` מחזירה"; "3 steps" → "שלושה שלבים".
+ The first **word** must be Hebrew, not a prefix glued to English: "ה-DC משמש…" flips the line, so write
+ "השרת DC משמש…"; "ב-Docker" and "ה-API" are fine later in the line.
+ 2. **Headings, bullets, bold labels, table cells** follow rule 1, header cells included: "## הגדרת Docker",
+ "- הפונקציה fork יוצרת…", "**הכלי Podman:** …", "| הכלי Docker | נפוץ |". Labels that feel like fixed
+ English terms are the usual slip: "**Pros:**" → "**יתרונות:**", "**Step 1:**" → "**שלב 1:**",
+ "**Train:**" → "**סט ה-Train:**".
+ 3. **After a bold label that ends in English**, the next word is Hebrew: "**סשן ה-Transformer:** מודל…".
+ 4. **End lines on a Hebrew word**, not on English + punctuation: "…ומריצים את `make` בטרמינל.". If no Hebrew
+ ending fits, drop the final period.
+ 5. **Numbers next to English:** "*Iron Man* (2008)" → "הסרט *Iron Man* משנת 2008"; "-1" → "מינוס 1".
+ 6. **Code blocks hold no Hebrew** (comments and strings in English); the line right after a block opens in Hebrew.
+ 7. **A cell or line that is only a name** gets a Hebrew noun: "הכלי Docker", "השירות GitHub".
- ## Verify before sending (mandatory)
+ Before sending, glance down the left edge of the reply: every first word Hebrew? That is the whole check.
+ If the user reports a line that rendered wrong, fix it; the full rule set (below) covers rarer cases.
- A mental read-through is not enough; the eye reads the content of a line and skips its first word. The check is
- mechanical:
+ ## Files you write
- **When a shell is available** and the reply has any list, table, heading or bold label, or is longer than about
- eight lines:
- 1. Pipe the full draft to the checker on stdin, so nothing has to be written:
- `python3 scripts/check_rtl.py - --fix <<'EOF'` … `EOF` (path relative to this skill folder). A draft file in
- the scratch directory (`rtl_draft.md`) works too.
- 2. Read the report; a folder you cannot write to is never a reason to skip the check.
- 3. Fix every ERROR and WARNING — the `→` suggestions are first candidates, not final wording — and re-run until
- it reports `0 errors, 0 warnings`.
- 4. Send the corrected draft word for word. Do not retype it from memory.
+ Files are checked mechanically, on the file itself (nothing to retype):
+ - Markdown: `python3 scripts/check_rtl.py FILE --fix` → fix until `0 errors` (stdin works: `-`).
+ - Word: set `w:bidi` / `w:rtl` (`references/docx.md`); `python3 scripts/check_docx_rtl.py FILE` → 0 paragraphs without RTL.
+ - LaTeX: `references/latex.md` (polyglossia, XeLaTeX). PowerPoint: `references/pptx.md` (`rtl="1"`).
+ - Course terminology for a document: `references/glossary/<family>.md` (first mention: Hebrew term with the
+ English in parentheses); a `COURSE.md` may override terms.
- For a Word file: `python3 scripts/check_docx_rtl.py out.docx` must report 0 paragraphs without RTL.
- For LaTeX: compile with XeLaTeX/LuaLaTeX; "Missing character" warnings mean a font without Hebrew glyphs.
+ ## Files in this skill
- **When no shell is available**, list to yourself the first word of every line (each heading, bullet, bold label,
- table cell, the lines around each code block, and the last line) and confirm each is Hebrew; do the same for the
- last token before each line's final punctuation. Fix any line that fails using rule 2 of the chat reference.
- These slips survive this check most often, so look for them by name:
- - **The first sentence after a heading that opens with a name** (`Marvel היא…`, `Python היא…`). Put a Hebrew
- noun first: `החברה Marvel היא…`, `השפה Python היא…`.
- - **A bold label that ends in English followed by English text** (`**סשן ה-Transformer:** Transformer…`):
- the label jumps sides. The first word after the label is Hebrew: `**סשן ה-Transformer:** מודל Transformer…`.
- - **Hebrew inside a code block** (comments, strings): it renders reversed. Comments in code are English;
- the Hebrew explanation goes in the prose after the block.
- - **An English name followed by a number in parentheses** (`*Iron Man* (2008)`): the number renders on the wrong
- side of the name. Write the number in Hebrew words around it: `הסרט *Iron Man* משנת 2008`.
+ - `scripts/check_rtl.py` — checks Markdown/chat text for every RTL script; `--fix` suggests openers; `--json`.
+ - `scripts/check_docx_rtl.py` — Hebrew/Arabic paragraphs in a `.docx` that lack `w:bidi`.
+ - `references/chat-markdown.md` — the full rule set with every edge case (tables, links, lists, mixed quotes).
+ - `references/docx.md`, `references/latex.md`, `references/pptx.md`, `references/arabic-persian-urdu.md`, `references/glossary/`.
- - **A negative number** (`ירידה של -1`, a cell `| -1 |`): it renders as `1-`. Write `מינוס 1`, or put a
- left-to-right mark (U+200E) right before the minus.
+ ## When this triggers
- Skip the check only for a short reply of plain sentences with no list, table, heading or label.
+ The user invokes it (`/rtl-writing`, the old `/hebrew-with-english`, or a namespaced form); complains that RTL
+ lines come out flipped or punctuation jumps; asks for an RTL document or slides with English terms; or another
+ skill is about to write RTL prose into a file. Not for translation, grammar questions, or plain RTL prose with
+ no English tokens.