Skip to main content

​
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.
The skill produces an editable project, not a black-box video. Motionly’s parser, evaluator, renderer, and serializer remain the source of truth.

​
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.