---
title: Prompt Guide For Agents And LLMs
description: Prompt templates and the recommended workflow for creating editable Motionly projects with the in-app assistant or an external coding agent.
---

# Prompt Guide For Agents And LLMs

An agent or LLM can create the first `.motion` draft. Motionly then lets you inspect, edit, preview, save, and export that draft visually. Strong prompts describe the story and constraints; they do not ask the model to invent `.motion` syntax.

<Tip>
  In Motionly Assistant, choose **Copy Prompt Template** beneath the prompt-guide link to copy the complete template below.
</Tip>

## Use The In-App Assistant

Open **Motionly Assistant** beside Assets:

1. Paste your own API key. Motionly detects Anthropic, OpenRouter, OpenAI, Google Gemini, and Hugging Face keys.
2. Optionally enter the exact model ID. Leave it blank to use Motionly's provider default.
3. If the prefix is unknown, enable **Custom endpoint** and enter the base URL for an OpenAI-compatible service.
4. Describe the animation. The assistant receives the current `.motion` project and imported asset list, so it can reuse real asset paths.
5. Review the response and choose **Load into Editor**. Motionly parses and validates the generated source before replacing the current project.
6. Continue the same chat to refine the draft, then make final visual edits in the canvas, Properties panel, and timeline.

The API key and conversation history are stored in browser `localStorage`. Requests travel directly from the browser to the configured provider and are never sent through a Motionly server. A custom endpoint must allow browser requests from the Motionly origin.

The assistant asks for a brief explanation followed by one fenced `.motion` project. Generated projects use the same parser → scene graph → renderer pipeline as projects opened or edited manually.

## AI Config Knowledge

Motionly gives the in-app assistant persistent knowledge through two rail items. Everything is stored in the browser and appended to the assistant's system context on each request:

- **AI Config (AI/Bot icon)** — enable or disable the built-in skills the assistant should follow. Each enabled skill loads its instructions into the context:
  - `write-motionly` — authoring workflow: storyboard, retime, validate.
  - `motion-graphics` — motion design principles: one focal subject, restrained easing/timing, deliberate exits.
  - `motionly-rules` — core product rules and `.motion` syntax (this replaces a per-project `AGENTS.md`).
  - A **Context** view previews what the assistant knows (enabled skills, brand, asset count, project info).
- **Settings (gear icon)** — the **Brand Profile** editor. Brand name, logo, colors, typography, visual style, motion style, and things to avoid are edited visually and Motionly generates `BRAND.md` (or switch to Edit Markdown mode).

When skills are enabled or a brand is set, the assistant is told to honor them while generating `.motion`.

**Model quality matters.** The AI model you choose directly affects composition, timing, and correct preset use. Smaller models may generate valid syntax but weaker visual decisions. Prefer a current, high-capability model with strong code-generation and instruction-following performance.

## Use An External Agent

Agents that work directly inside a project folder can use Motionly's installed skill instead of the in-app panel.

### Install The Skill

From your project, install the skill and its reference library for your agent:

```bash
npx @coppsary/motionly skills add --all        # or --provider codex|claude|gemini|opencode|kiro
```

`init` installs it too (it asks which agent). Each install writes, under your agent's skills folder — Codex (`.agents/`), Claude Code (`.claude/`), Gemini CLI (`.gemini/`), opencode (`.opencode/`), or Kiro (`.kiro/`):

- `SKILL.md` — the quick `.motion` contract.
- `references/llms.txt` — a discovery index for the focused skills.
- `references/skills/*/SKILL.md` — the full library: `motion-dsl`, `svg`, `animation`, `easing`, `camera`, `composition`, `typography`, `transitions`, `timeline`, `assets`, `rendering`, and `templates`.

Ask the agent to read `AGENTS.md` and the installed `SKILL.md` first, then load `references/llms.txt` and only the reference skills the task needs (always `motion-dsl` for authoring or repair). Re-running the installer keeps your edits and never overwrites existing files.

Working inside a clone of this repository instead? The same guidance lives at `AGENTS.md`, `.agents/skills/write-motionly/SKILL.md`, and `.agents/skills/write-motionly/references/motion-syntax.md`.

### Prepare Your Project

1. Create a folder such as `video-motion/assets/my-project/`.
2. Add the images, SVGs, logos, videos, and audio references needed for the story.
3. Keep original aspect ratios and use clear filenames.
4. Provide the story, audience, goal, and script. Motionly can infer format, duration, and technical defaults.
5. Tell the agent which text must appear exactly and provide narration timestamps when available.

Images, SVGs, and videos can be imported and used as timeline clips. Audio persists in `.motion` format. You can also drag assets from the Assets panel onto the timeline in the editor to create clips visually.

## Prompt Template

Replace the bracketed creative fields that matter. Delete sections that do not apply. Motionly infers file placement, canvas settings, duration, FPS, and renderer details.

```text
/motionly
Create or refine a polished, fully editable Motionly animation from this creative brief.

Audience and goal:
[Who should see this, what should they understand, and what should they do next?]

Story:
[Describe the message or progression. A rough beginning, middle, and end is enough.]

Assets (optional):
[List required logos, screenshots, video, animated SVG/GIF, Lottie, photos, or illustrations. Say which existing animation must be preserved.]

Narration or script:
[Paste narration, exact on-screen copy, or useful timestamps. Mark any wording that must remain verbatim.]

Brand direction:
[Colors, typography, visual references, motion character, and anything to avoid.]

Important requirements:
[Anything that must appear, must not change, or must be avoided.]

Infer sensible format, duration, pacing, timeline organization, and technical settings from the brief and available media. Prefer native editable SVG artwork and Motionly animation for logos, icons, diagrams, and illustrations unless an existing asset's animation must be preserved.
```

## What To Include For Better Results

<CardGroup cols={2}>
  <Card title="Story and timing">
    Give narration timestamps, audio, or required holds when they matter. Otherwise let Motionly establish the pacing.
  </Card>
  <Card title="Asset intent">
    Separate required assets from optional assets and say which file is the hero in each shot.
  </Card>
  <Card title="Copy rules">
    Mark text that must remain verbatim. State whether the agent may shorten or split anything else.
  </Card>
  <Card title="Visual boundaries">
    Provide brand colors, typography, motion character, and treatments the agent must avoid.
  </Card>
</CardGroup>

## Refinement Prompt

For a second pass, name the observed problem and timestamp instead of asking for a generic improvement:

```text
/motionly
Update the existing project; do not replace unrelated work.

At [timestamp], [describe the visible/timing problem].
Change [specific layer, shot, transition, or copy].
Preserve [timing, assets, brand rules, or exact text that must not change].

Re-run inspect:motion and verify frames immediately before, during, and after the edit.
Return the complete updated .motion file.
```

### Replace The Sample

To start from the included sample:

1. Copy `video-motion/motionly.motion` to a new project name.
2. Remove only the sample assets you no longer need.
3. Put your own files in a dedicated asset folder.
4. Ask the agent to replace all old imports and remove unused layers.
5. Open the generated project in Motionly and refine it visually.

Do not ask the agent for implementation details. Describe the creative result; Motionly's skills choose supported, editable techniques and disclose real renderer limitations.

## Review Any Generated Result

Before export:

- Confirm the canvas size, FPS, and duration.
- Scrub every scene transition.
- Check text wrapping, image aspect ratios, and layer overlap.
- Confirm entrances and exits match the script.
- Save the edited `.motion` file.
- Confirm project audio starts at the intended timeline offset and is present in MP4 export.

Generated output is a starting point, not a black-box final video.