name: persian-motion-director description: Direct and build professional motion design (promo and launch films, kinetic typography, animated explainers, social clips, title sequences) with correct Persian/Farsi and right-to-left typography, in Remotion or plain web code. Use this skill whenever the user wants a video, animation, motion graphics, teaser or animated text that contains Persian, Farsi, Arabic-script or RTL text, and whenever they say a motion piece looks "default", "like a slideshow", "AI-made" or "not pro", or that the Persian looks off, broken or disconnected, even if they never say "motion design". It brings the anti-slideshow method (one camera, objects that carry across scenes, music-first beat-locked edits), eight ready techniques with live sketches, HarfBuzz tooling for per-letter and per-dot Persian animation, kashida stretching, and a Persian correctness checklist and linter.

Persian Motion Director

You are directing, not just animating. Most generated motion fails in two predictable ways: it plays like a slideshow (scenes that fade into each other, one ease-in-out on everything, everything arriving at once), and its Persian is broken (letters split apart, dots clipped, Arabic letters and digits, missing half-spaces, left-to-right reveals). This skill fixes both. The method comes from how professional motion designers describe their own work on X; the Persian rules come from W3C's Arabic & Persian Layout Requirements and were checked in Chrome (the engine Remotion renders with).

The director's loop

Work in this order. Each step exists because skipping it is how pieces end up looking default.

1. Read the brief and fill only real gaps. Copy (Persian and any Latin), length, aspect ratio, brand colours and fonts, where it will be posted, music. If a brand exists, use its palette and fonts instead of inventing one.
2. Show directions before building. Motion is subjective and expensive to redo. Pick 6–10 techniques from the library below that fit the brief, open assets/sketches/gallery.html (or render the clips) and let the user choose. Rework after a full build costs ten times more than a pick list.
3. Music first. Lock the track and its tempo before animating. Build a bar map: which section lives on which bars. If there's no track, compose one (assets/music/compose_shur_pulse.py is a working example that writes beats.json) or ask for one. At 120 BPM one beat is 0.5 s and one bar 2 s; at 60 fps a beat is 30 frames.
4. Write the shot list on the bar grid (template in references/workflow.md). Every section change lands on a downbeat; every cut on a beat or 2 frames before it.
5. Style frames. Render 4–6 stills (assets/remotion/render-stills.mjs) and get a yes before animating everything.
6. Build in Remotion with one camera container and shared objects (see assets/remotion/src/intro/Intro.tsx for a complete worked example).
7. Check, then render: run scripts/lint_persian.py on all copy, review stills at full size for clipped dots and broken joins, scrub every cut against the beat, and make loops exact (clip length = a whole number of loops).

What separates pro motion from a slideshow

More numbers and the sources behind them: references/anti-slideshow.md.

Persian non-negotiables

Read references/persian-typography.md before writing any Persian into a frame. The short version:

1. Never put Persian letters in their own boxes. inline-block spans, flex children (including direct children of Remotion's <AbsoluteFill>, which is a flex box) and any per-letter transform draw each letter in its isolated form. Animate whole words or lines. When you truly need per-letter or per-dot motion, use shaped outlines (scripts/shape_persian.py) or zero-width-joiner splitting (scripts/split_fa.js).
2. Fade words, not letters. Joined letters overlap; per-letter opacity or see-through text colour leaves seams at every join.
3. Masks need slack. Persian reaches far above and below Latin: pad clip masks by about 0.5em top and bottom, use line-height ≥ 1.6 (≥ 2.4 for Nastaliq), or the dots and the top of گ get cut.
4. Direction. dir="rtl" lang="fa" on every Persian block; wrap Latin names and numbers in <bdi> (or FSI/PDI) or the line scrambles. Reveals and staggers start on the right, camera progress travels left, "next" arrows point left. Play buttons, clocks and numbers are never mirrored.
5. Characters. Persian ی (U+06CC) and ک (U+06A9), never Arabic ي/ك; Persian digits ۰–۹ (U+06F0–06F9), never Arabic-Indic ٠–٩; the half-space (ZWNJ, U+200C) in می‌, ‑ها, ‑تر/‑ترین; punctuation ، ؛ ؟ « ». scripts/lint_persian.py catches these.
6. No letter-spacing. Chrome ignores it inside Persian words (since version 137) and other tools break the joins. Stretch with kashida instead, only after a letter that joins forward, at most one per word.
7. Load the font, every time. If the Persian font (or its Arabic-script subset) isn't loaded, Chrome silently falls back to a system font. In Remotion use FontFace + delayRender (see assets/remotion/src/fonts.ts).
8. Copy. Write natural Persian in one register; no word-for-word English idioms. A native reader signs off on every line before render (references/persian-copy.md).

Technique library

Live code for each is in assets/sketches/sketches.js (plain JS, a pure function of time) and runs both in a browser page and in Remotion through SketchPlayer. Details, numbers and the X posts each comes from are in references/techniques/.

Pick by the brief, not by novelty: one or two signature techniques used consistently read as a system; all eight at once read as a reel.

Tools in this skill

• scripts/shape_persian.py — shapes Persian with HarfBuzz and exports SVG outlines split into letter bodies, dots and connected letter groups (pip install uharfbuzz fonttools). This is what makes per-letter, per-dot and kashida animation possible without breaking the script.
• scripts/split_fa.js — splits a Persian word into letters that keep their joined forms (zero-width joiners), for when outlines are overkill.
• scripts/lint_persian.py — checks copy (Arabic letters and digits, missing half-spaces, English punctuation, misplaced kashida) and code (letter-spacing, per-letter boxes, missing dir).
• assets/sketches/ — the motion engine (engine.js), the eight sketches, shaped glyph data, styles and gallery.html (serve the folder with any static server).
• assets/remotion/ — SketchPlayer (drives a sketch from the frame number), one clip composition per technique, the full intro film as a worked example, and scripts to render clips and stills.
• assets/music/compose_shur_pulse.py — an original 120 BPM track in Dastgah Shur written in code, with a beat map; shows how to make the edit lock to the music.

When the user only wants a quick piece

Still keep the two non-negotiables that cost nothing: no per-letter boxes for Persian, and no scene-to-scene fades. Use one technique well, set the timing on a beat grid, and render stills to check the Persian before the full render.

persian-motion-director

A Claude skill for professional motion design with correct Persian typography. Films that don't play like slideshows, and Persian that doesn't fall apart.

Most generated motion fails in two predictable ways. It plays like a slideshow: scenes fade into each other, one ease-in-out on everything, everything arrives at once. And its Persian breaks: letters split apart when animated, dots get clipped, Arabic letters and digits slip in, half-spaces go missing, reveals run the wrong way.

This skill teaches Claude to direct instead: show directions before building, lock the music first, cut on the beat, keep one camera moving, and set Persian the way a Persian reader expects. It comes with eight working techniques, tooling for per-letter and per-dot Persian animation, and a checklist and linter for Persian copy.

Eight techniques

Every sketch is plain JavaScript, a pure function of time, so the same code runs live in a browser and frame-exact in Remotion.

What's inside

SKILL.md                      the director's loop, anti-slideshow rules, Persian non-negotiables
references/
  workflow.md                 brief → directions → music first → shot list on the bar grid → style frames → build → checks
  anti-slideshow.md           curves, springs, staggers, holds, motion blur, rhythm (with numbers and sources)
  persian-typography.md       joining, masks, bidi, characters, kashida, fonts, a review checklist
  persian-copy.md             natural Persian for motion, common machine-copy mistakes
  techniques/01…08            one file per technique: recipe, values, Persian notes, the X posts behind it
scripts/
  shape_persian.py            HarfBuzz shaping → SVG outlines split into letter bodies, dots and joined groups
  split_fa.js                 split a word into letters that keep their joined forms (zero-width joiners)
  lint_persian.py             lint copy (ي/ك, digits, half-spaces, punctuation, kashida) and code (letter boxes, letter-spacing, fades)
assets/
  sketches/                   motion engine, the eight sketches, shaped glyph data, gallery.html
  remotion/                   SketchPlayer adapter, one clip per technique, the intro film, render scripts
  music/compose_shur_pulse.py an original 120 BPM track in Dastgah Shur, written in code, with a beat map

Install

Claude Code (personal skills):

git clone https://github.com/atmirrr/persian-motion-director ~/.claude/skills/persian-motion-director

Or put it in a project's .claude/skills/ folder. Claude picks it up when you ask for motion with Persian or RTL text, or when you say an animation looks "like a slideshow".

Use

Things to ask Claude:

• "Make a 30-second Persian teaser for my app in Remotion, cut to music."
• "This animation looks like a slideshow. Make it feel pro."
• "My Persian title breaks into separate letters when I animate it."
• "Show me 8 motion directions for our launch film before you build anything."

Check Persian copy and code yourself:

python3 scripts/lint_persian.py copy copy.txt
python3 scripts/lint_persian.py code src/
pip install uharfbuzz fonttools
python3 scripts/shape_persian.py assets/sketches/fonts/Vazirmatn-VF.ttf "کارگردان موشن فارسی" --wght 800

Run the examples

Live sketches in a browser:

cd assets/sketches && python3 -m http.server 8000   # open http://localhost:8000/gallery.html

Render the clips and the intro film with Remotion:

cd assets/remotion
npm install
npx remotion studio src/index.ts          # browse every composition
node render-clips.mjs out                 # the eight technique clips
node render-clips.mjs out --only Intro    # the 82-second intro film
python3 ../music/compose_shur_pulse.py public/music   # rebuild the music (WAV) and beat map, then convert to MP3

The intro film is the worked example: music first (120 BPM, Shur on D), a bar map, every cut on a beat, one camera that whips right to left between sections, and Persian set correctly throughout. See assets/remotion/src/intro/Intro.tsx.

Where the method comes from

The anti-slideshow rules and the eight techniques come from research into how professional motion designers describe their own work on X (October 2026, about 100 posts, each one checked to exist). Every technique file links the posts it draws on. The Persian rules follow W3C's Arabic & Persian Layout Requirements and were tested in Chrome, the engine Remotion renders with.

به فارسی

کارگردانِ موشنِ فارسی یک اسکیل متن‌باز برای Claude است که دو مشکل همیشگی موشن‌های ساخته‌شده با هوش مصنوعی را حل می‌کند: حسِ اسلایدشو، و فارسیِ به‌هم‌ریخته.

• اول جهت‌ها را نشان می‌دهد و بعد می‌سازد؛ اول موسیقی، بعد تدوین، و هر کات روی ضرب.
• یک دوربین که بین صحنه‌ها از راست به چپ حرکت می‌کند، به‌جای محو شدن صحنه‌ها در هم.
• حروف فارسی هیچ‌وقت از هم جدا نمی‌شوند؛ برای انیمیشنِ حرف‌به‌حرف و نقطه‌به‌نقطه، متن با HarfBuzz شکل‌دهی می‌شود.
• اعداد فارسی، «ی» و «ک» فارسی، نیم‌فاصله، علامت‌گذاری فارسی و جهت راست به چپ، همه با یک چک‌لیست و یک لینتر کنترل می‌شوند.
• به‌جای فاصله انداختن بین حروف، کشیده؛ همان‌جایی که خط اجازه می‌دهد.

License

Code: MIT. Vazirmatn: SIL Open Font License (assets/sketches/fonts/OFL.txt). The music in assets/remotion/public/music is generated by assets/music/compose_shur_pulse.py and is free to use. Example copy uses the word هرمس (Hermes) from the original brief; the default palette (#0000F2, #F2F2F2, #F2F200) is set with CSS variables and easy to change.