Performance Doctor

Performance Doctor finds and fixes slow animations.

It combines source analysis and local-runtime profiling to find animation performance issues before they ship. Then it opens a report card in your chat, where one click sends any finding back to your agent to fix.

/motion audit

It grades animations using the same S-to-F system as MotionScore Audit.

Install

/motion audit the homepage

Performance Doctor is part of the Motion AI Kit. Installing AI Kit sets up the /motion skill, including its performance audit, for every supported editor. Follow the AI Kit install guide.

Usage

Ask your agent to run a performance audit (adding /motion might be required in some agents).

By default, this runs a broad search of CSS, Motion, GSAP and Anime.js APIs in your codebase.

It's possible to limit the scope by passing a directory or filename:

/motion audit @components/Button

Additionally, you can scope the audit to specific types of animations, or specific APIs:

Can you perform a /motion audit of all scroll animations

Ask for fixes in the same prompt and the agent fixes what it finds without asking first:

/motion fix animation performance on the homepage

Runtime audits

Mention "runtime", a specific page, or pass a URL to profile the page as it runs:

/motion performance audit on http://localhost:3000

Your agent runs npx motionscore <url> --agent, which loads the page in a local browser and records every animation it plays. Static and runtime results go into the same report. A runtime finding points at the element's selector, with a hint for where to look in your code.

The report card

When the audit finishes, your agent opens the report card in the chat.

Rank

The card leads with an overall rank, from S to F, across every animation the audit found. Beside it, a headline counts the animations that need work, and the rank you'll reach once they're fixed.

Under that, a bar shows how many animations sit at each grade. The idea is for it to be top-heavy: more S, A and B than below.

Findings

Every animation with a practical upgrade gets a finding, worst first. Each finding shows:

• Grade: Its current grade and the grade the fix reaches, for instance F → A.

• What: What the animation does, with its filename and line number.

• Why: Why it's slow, in terms of the render pipeline.

• Fix: How to make it faster.

• Example fix: A short diff of the change.

Animations that already pass are listed, collapsed, at the bottom of the card.

Fixing

Click Fix on a finding to send it to your agent, in the same chat that ran the audit. It already knows the finding, so there's nothing to explain.

The agent makes the edit, then checks it: it runs your project's type check, lint and tests for the changed files, and grades the animation again. While it works, the card shows the file it's fixing.

If the check passes, the finding changes to Fixed, with its new grade, and the rank climbs. Changed your mind? Click Undo and the agent restores the original code.

If the check fails, or the fix would change how the animation looks, the agent rolls back its edit and the card says why. Your code is unchanged, and Try again sends it back.

Fix all sends every open finding. The agent works through them one at a time, in order.

Copy prompt copies a standalone prompt for a finding, so you can paste it into a different agent or chat.

Terminals

The report card is an MCP App. Hosts that can't show MCP Apps, for instance Claude Code CLI and Codex CLI, get the same report as a numbered list instead:

Performance Doctor report dr_3f9a1c0e2b7d · acme-storefront · src, static
Rank B. 4 of 18 animations need work. Fixing them reaches rank A.

1. F → A  Layout thrashing · components/Parallax.tsx:18
   What: Each card reads its position, then writes a transform, inside one scroll handler.
   Why: Every read after a write forces a synchronous layout, once per card, every frame.
   Fix: Read every position first with frame.read, then write the transforms with frame.render.
2. D → S  Animating width · components/Drawer.tsx:34
   ...

Passing: 14 animations (9 S, 3 A, 2 B).

Reply with the findings you want fixed:

fix 1 and 3

Or simply "fix all". The agent fixes and checks each one in turn, just as it does from the card.

Tiers

The broad tier list used for grading animations is as follows:

The full explanation of these grades can be found in the MotionScore methodology. For deeper editorial background, read the Web Animation Performance Tier List.