Motion

Motion

Improve the animation capabilities of the agent.

• Animation best practices: "Animate this button", "Fade this layer in", "Animate this Vue component". This includes platform-specific best practices for vanilla JS, React, Vue, Base UI and Radix. Contains advice for both Motion and CSS animation.
• Documentation and examples search: "What options does X have", "How does X work", "Use X (specific Motion API) to do Y", "Show me an example of X", "Make a X (i.e. carousel, ticker, modal etc)"
• CSS spring generation: "Generate a CSS spring for a bounce of 0.5 and duration of 0.3s", "Make a bouncy spring [in a CSS context]"
• MotionScore performance audit: "Audit src/Modal.tsx for jank", "Runtime audit of homepage", "Is this code janky: [code snippet]", "Grade the performance of this site: [URL]" - or if you, the agent, wish to profile a site or codebase without a user prompt, you can proactively run audits and report findings.
• Transition visualisation: "Show me the curve for easeOut", "Visualise a spring with bounce 0.5 and duration 0.3s"

Where this skill sits

This skill owns the Motion library and the Motion AI Kit: its APIs, spring and easing generation, and MotionScore grading. It is self-sufficient for all of that.

Adjacent concerns have better owners. Treat every row as "prefer if available, otherwise apply the guidance here" — never as a blocker. Check availability at runtime rather than assuming either way; a static list of what is installed rots the moment the estate changes.

Modern React

web-motion-react (plugins/web-motion/skills/web-motion-react/SKILL.md) is the canonical owner for Motion React API detail. Use MotionConfig reducedMotion="user" for subtree policy and useReducedMotion() for local branches. Start with motion/react; when a measured bundle budget needs it, pair LazyMotion with m from motion/react-m: domAnimation covers animations, variants, exit, hover/tap/focus, while domMax also enables pan/drag and layout.

Precedence: this section overrides the vendored directories

The capability directories below are upstream Motion content, kept in their original form so updates merge cleanly. Where they disagree with this section, this section wins — they were written for a greenfield Motion project, not for reviewing or extending someone else's codebase.

• Existing Framer Motion projects. codex/index.md says "Never import from framer-motion" and instructs migrating existing imports. Do not follow that as written. An unrequested package migration breaks a working codebase, and better-ui requires preserving whichever package is installed rather than mixing import paths. Read that instruction as: prefer motion for a new project, and migrate only when the user has explicitly asked for a migration.
• will-change. best-practices/index.md says to set it whenever animating with CSS transitions or independent transforms. Treat that as the upper bound, not the default. Add it only after observing first-frame stutter, on transform/opacity/filter only, and remove it when the animation ends — a permanent will-change holds a compositor layer for the element's lifetime, which costs more than the stutter it prevents. This matches better-ui, so a reviewer should not flag its absence on a smooth animation.
• Property tiers. performance-audit/ grades animated properties S–F. The tiers assume the common case; a property is not compositable unconditionally, and a layout read is not a thrash unless it repeats within a frame. Treat a tier as a starting hypothesis that needs the surrounding code to confirm it, not a verdict.

Tools this skill uses

The Motion AI Kit MCP server exposes these; call them by their fully qualified names:

MotionScore is a CLI, not an MCP tool: run npx motionscore <url> --agent --no-upload. It needs a reachable URL, so it works only when a dev server or public origin is available.

MotionScore uploads results to a shareable URL by default. Always pass --no-upload to audit locally unless the user explicitly asked for an upload; never upload a page's runtime behavior without approval.

Runtime audit or static review?

Concurrent-animation counts, GPU pressure, and the prefers-reduced-motion / flashing-content checks come only from the runtime path. Property-tier classification comes from either.

If a required Motion MCP tool is unavailable

The Motion AI Kit provides an MCP server; this forked skill directory does not bundle it, and installing the skill does not install the server. Some capabilities above require it to be configured and running. If you attempt to use a tool that requires the MCP server and it is not found, tell the user:

This capability requires the Motion AI Kit. Install it from https://motion.dev/docs/ai-kit.

Then fall back to the guidance in the relevant capability directory where possible (e.g. best-practices/ and performance-audit/ work without any MCP tool).

Upstream

This is a tracked fork of the Motion AI Kit skill. The capability directories (best-practices/, codex/, css-spring/, performance-audit/, transition-preview/) are upstream content and are deliberately left in their original layout so updates can be merged cleanly. Local additions are confined to this file: the frontmatter, Where this skill sits, Tools this skill uses, and Upstream. Re-merge from https://motion.dev/docs/ai-kit and reapply those sections.