AGENTS.md — motion-skills

Instructions for any coding agent (Codex, Claude Code, Copilot, Gemini and others) and for the people who run them. This repository holds four skills that turn product work into short films and training material.

The skills

All four live in skills/<name>/. Each folder has a SKILL.md with the full steps. Read that file before you start the task it covers.

motion-web-video reuses the score synth of motion-video. Keep both folders side by side.

Use them with your agent

• Claude Code: /plugin install motion-skills --marketplace verbodh-pte-ltd/motion-skills, or python scripts/install.py to copy the folders into ~/.claude/skills/.
• Codex: python scripts/install.py --codex --project <your project> (copies into .agents/skills/).
• Other agents: give the agent the skill's SKILL.md as its instructions for the task.

In every SKILL.md, ${CLAUDE_SKILL_DIR} means that skill's folder. Claude Code fills it in; in other agents, read it as the folder that holds the SKILL.md.

Before the first film, run python scripts/check.py <skill>. It names each missing tool and the command that installs it on this OS. Tell the user what is missing; do not install tools without asking.

Tools to install

ffmpeg: brew install ffmpeg on macOS, winget install --id Gyan.FFmpeg -e on Windows (open a new shell after it).

Settings

Drafts need no setting: they use the free system voice and write files locally.

Rules for every agent

1. Draft first, pay last. Make every film and video with the free system voice first. Use ElevenLabs only after the user approves the draft, and tell them the character count before the first paid run.
2. Look before you report. Take a frame from the middle of each scene and view it. Check that the MP4 has sound: ffmpeg -i <file>.mp4 -af volumedetect -f null - must show Audio: aac and a mean volume above about −40 dB.
3. Every claim on screen is true today. A feature that is only planned or only on a test site is not shown as live.
4. Nothing private on screen or in a file. No keys, tokens, passwords, customer names, emails or security findings in a screenshot, a film or a commit. Read keys from the environment only; never print them or write them to a file.
5. Use made-up names in shared examples: the product Acme Board at board.example.com, the bucket example-training-media.
6. Never embed a narrated video as muted autoplay. Browsers autoplay only muted video, so the voice is never heard. Embed it with controls and a poster.
7. Ask, then build. Ask the user the two questions each film skill lists (style and colours) in one go, then build. Do not ask again for what the request already says.

Check that the skills work

python skills/motion-video/scripts/test_motion.py       # score maths, cue timing, levels
python skills/motion-web-video/scripts/test_render.py   # renders the example film (Chrome, ffmpeg)
python skills/motion-web-video/scripts/test_voice.py    # free voice, clip reuse, --plan (ffmpeg)

The voice test never calls ElevenLabs.

Layout

motion-skills/
├── AGENTS.md                 this file
├── README.md                 overview and install
├── docs/                     INSTALL, QUICKSTART, TROUBLESHOOTING
├── scripts/                  check.py (tools per skill), install.py (copy the skills)
├── .claude-plugin/           plugin and marketplace files
├── LICENSE                   MIT
└── skills/
    ├── motion-video/         SKILL.md, scripts/motion.py, test
    ├── motion-web-video/     SKILL.md, example/, templates/, runtime/ (Motion, MIT), scripts/
    ├── training-guide/       SKILL.md, scripts/session_screenshots.py
    └── training-video/       SKILL.md, scripts/guide_video.py

Licences

MIT. skills/motion-web-video/runtime/motion.js is Motion (motion.dev), MIT, with its own licence file beside it. Do not copy Motion+ (paid) code into a film or a skill. Claude Motion is Anthropic's product; do not use its name or branding in published films.