> ## Documentation Index
> Fetch the complete documentation index at: https://motionly.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# write-motionly agent skill for Claude and Codex

> How the write-motionly skill briefs Claude, Codex, and other coding agents to create, edit, retime, review, and repair .motion projects reliably.

# Write Motionly Agent Skill

The `write-motionly` skill is the repository workflow for agents that create, edit, retime, review, or repair `.motion` projects.

It turns a script, audio track, storyboard, existing project, or asset folder into a polished animation that still previews, edits, saves, reloads, and exports through Motionly's normal pipeline.

<Info>
  The skill produces an editable project, not a black-box video. Motionly's parser, evaluator, renderer, and serializer remain the source of truth.
</Info>

## When To Use It

Use `write-motionly` when an agent needs to:

* Create a complete `.motion` project
* Retime animation to narration or audio
* Choose supported transitions and presets
* Fix visual overlap, clipping, stale layers, or weak composition
* Explain valid `.motion` syntax
* Validate a generated animation before handing it back

## Required Agent Context

Agents should read:

* `AGENTS.md` for product boundaries and supported syntax expectations
* `.agents/skills/write-motionly/SKILL.md` for the authoring workflow
* `.agents/skills/write-motionly/references/motion-syntax.md` for properties, presets, and syntax details

The repository parser and preset implementation are authoritative if they differ from older generated examples.

## The Authoring Contract

Before editing, an agent identifies the project type, audience, goal, exact copy, narration timing, brand constraints, required assets, and prohibited treatments. It infers sensible canvas/FPS/duration and file placement unless a choice materially changes the story. It should preserve unrelated user work and avoid guessing media dimensions or duration.

## Workflow

1. Inspect the request, existing `.motion` project, script, audio, and every relevant asset.
2. Infer canvas size, frame rate, and duration from the brief/media; confirm whether spoken copy must appear verbatim.
3. Storyboard distinct shots before editing.
4. Give each shot a purpose, focal subject, supporting elements, entrance, exit, and time range.
5. Write or edit the smallest valid `.motion` project that realizes the storyboard.
6. Run `inspect:motion` with the expected duration and review every reported empty-frame range.
7. Preview representative frames at entrances, completed holds, transitions, exits, and the final frame.
8. Fix and repeat until semantic inspection, visual review, round-trip serialization, and relevant tests pass.

Agents should not invent new engine features while authoring a project. Missing editor or renderer capabilities should be handled as separate engineering work.

## Asset Rules

* Inventory asset paths before placing them.
* Inspect image and SVG dimensions before layout.
* Preserve original aspect ratios.
* Do not stretch assets.
* Do not place every available asset on screen.
* Treat MP4, WebM, MOV/M4V, GIF, animated SVG, and Lottie as animated assets; never silently flatten them.
* Prefer native SVG/vector overlays for logos, icons, diagrams, badges, illustrations, line art, and UI graphics unless an existing animation must be preserved.
* Use `drawSVG` for simple stroked artwork; use editable fill/stroke, masks, transforms, and grouped layers for richer vector motion.
* Animate local SVG zoom/pan with `x`, `y`, `scale`, `rotation`, `originX`, and `originY`, not the global camera.
* Report browser codec failures and animated-SVG exact-seeking limitations plainly.

## Script, Audio, And Timeline Rules

* Preserve exact script text when requested.

* Split long sentences only for layout, keeping words and punctuation unchanged and in order.

* Probe audio duration instead of guessing.

* Set canvas duration to cover the full track and closing fade.

* Place text entrances at the spoken phrase when timestamps are available.

* Keep labels and matching logos revealed together.

* Keep project audio on the bottom audio track.

* Preserve its timeline `start` offset through save/reload and MP4 export.

* Treat visual tracks as simple layers: horizontal movement changes time, vertical movement targets a layer, overlaps are allowed, and content type does not restrict placement.

* Do not rely on magnetic packing, ripple editing, or automatic content allocation.

* Moving a whole animated layer moves its keyframes; trimming changes its visibility window without silently retiming them.

## Motion Direction

* Default to `power3.out`.
* Use entrances around `650ms` to `1s`.
* Use staggered word reveals for important copy, not every label.
* Use `shapeWipe` or `irisWipe` for real scene changes.
* Use `maskReveal` for hero media.
* Use `dynamicSlide` for supporting assets and logo groups.
* Use `speedZoom` once at a meaningful transition, not as continuous camera drift.
* Include deliberate exits with `exitAt` and `exitDuration`.

Avoid repeated fade-only scenes, random rotation, large bounce, accidental overlap, and constant camera motion.

## Validation Checklist

Before finishing, an agent should:

* Parse the final `.motion` file.
* Build its scene graph.
* Confirm canvas duration, imports, and expected scene elements.
* Verify exact script text against ordered text layer values.
* Inspect frames around scene starts, holds, transitions, and exits.
* Check for blank frames, overlap, clipping, distortion, and stale layers.
* Confirm parse/serialize/parse does not lose tracks, timing windows, masks, animation delays, or keyframes.
* Confirm preview and deterministic MP4 export evaluate the same project timing.
* Run the repository tests and build commands that cover the changed project.

The final output should be a completed `.motion` file that users can refine visually in Motionly.