# How the improve-animations Skill Audits Codebases for Motion Issues > Discover animation stacks and evaluate code against eight categories with the improve-animations skill. Get prioritized findings and implementation plans without code modification. - Repository: [Emil Kowalski/skills](https://github.com/emilkowalski/skills) - Tags: how-to-guide - Published: 2026-08-08 --- **The `improve-animations` skill performs a four-phase read-only audit that discovers animation stacks, evaluates code against eight standardized categories, prioritizes findings by leverage, and generates self-contained implementation plans without modifying source files.** The `improve-animations` skill in the `emilkowalski/skills` repository acts as a senior motion advisor that automates the audit of animation systems across any codebase. By following a strict read-only workflow defined in [`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md), it maps existing motion patterns, identifies violations like improper easing or missing accessibility features, and produces executable remediation plans stored in the `plans/` directory. ## The Four-Phase Audit Workflow The skill implements a systematic audit pipeline that separates judgment from execution. According to the source code in `emilkowalski/skills`, this workflow ensures consistent, reproducible analysis across projects of any size. ### Phase 1: Reconnaissance – Mapping the Motion Surface During the **Recon** phase, the skill builds a comprehensive motion surface map of the repository. It identifies the animation stack in use—whether Framer Motion, CSS transitions, Tailwind animations, or keyframe libraries—and locates where motion lives within the codebase. The reconnaissance process catalogs global design tokens, `transition` and `animate` props, keyframe definitions, and existing naming conventions. It also constructs a frequency map of animated interactions to understand the application's motion personality. This foundational data guides the severity weighting applied in later phases. ### Phase 2: Audit – Evaluating Against Eight Categories Using the eight categories defined in **[`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md)**, the skill deploys parallel read-only sub-agents to scan the codebase for concrete violations. Each agent hunts for specific anti-patterns such as **ease-in on UI elements**, **`transition: all`** properties that hurt performance, or missing **prefers-reduced-motion** handling. The audit rules are hard-coded in the audit playbook, ensuring that decisions remain consistent across different projects and execution contexts. For smaller repositories, a single agent may perform the entire scan. ### Phase 3: Vetting and Prioritization by Leverage Findings undergo a strict vetting process to eliminate false positives by re-checking evidence against original source files. The skill then ranks issues using a **leverage** calculation (impact ÷ effort) to identify high-value fixes. Each vetted finding receives a severity tag—**HIGH**, **MEDIUM**, or **LOW**—accompanied by a brief fix summary. This prioritization ensures that teams address motion debt that delivers the most user experience improvement for the implementation cost. ### Phase 4: Plan Generation with Self-Contained Execution For each selected finding, the skill generates a detailed implementation plan following the **[`skills/improve-animations/PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/PLAN-TEMPLATE.md)** format. These plans contain: - Exact file paths and current code excerpts - Target values (cubic-bezier curves, durations, spring configs) - Repository-specific token conventions - Step-by-step edit instructions - Verification criteria including mechanical tests and feel-checks Because the plan is fully explicit, any downstream executor—regardless of capability—can apply the changes without additional context. The skill adheres to a hard rule: it never mutates source code directly, outputting all generated files exclusively to the `plans/` directory. ## CLI Usage and Execution Modes The skill provides multiple invocation patterns to match different audit depths and use cases. Run a comprehensive audit across all components: ```bash improve-animations ``` Execute a quick audit focused only on high-traffic components: ```bash improve-animations quick ``` Target a specific violation category, such as easing issues: ```bash improve-animations easing ``` Skip the audit and directly author a plan for a described improvement: ```bash improve-animations plan "replace all ease-in on UI with --ease-out token" ``` Execute a previously written plan using a lower-capability agent: ```bash improve-animations execute 001-add-ease-out-token.md ``` ## Core Architecture and Source Files The audit system relies on three canonical documents that define its behavior: - **[`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md)** – Contains the core workflow description, hard rules (including the read-only constraint), and the complete invocation matrix. - **[`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md)** – Defines the eight audit categories, target values, and specific hunting patterns for motion anti-patterns. - **[`skills/improve-animations/PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/PLAN-TEMPLATE.md)** – Specifies the canonical layout ensuring that every generated plan is self-contained and executable. All generated outputs are written to the **`plans/`** directory, maintaining a strict separation between the audit logic and the resulting implementation artifacts. ## Summary - The `improve-animations` skill provides a **read-only audit** of animation systems without modifying source code. - It follows a **four-phase workflow**: Reconnaissance, Audit, Vetting/Prioritization, and Plan Generation. - Violations are categorized into **eight standardized groups** defined in [`AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/AUDIT.md), covering issues from easing curves to accessibility. - Findings are ranked by **leverage** (impact ÷ effort) and tagged with severity levels (HIGH, MEDIUM, LOW). - Generated plans in `plans/` follow a strict template format containing exact file paths, code excerpts, and verification steps suitable for any execution agent. ## Frequently Asked Questions ### What types of animation violations does the skill detect? The skill scans for concrete anti-patterns defined in [`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md), including ease-in timing functions applied to UI elements, performance-heavy `transition: all` declarations, missing `prefers-reduced-motion` media query handling, and inconsistent spring configurations. Each category includes specific hunting patterns to locate violations across different animation stacks. ### How does the skill prioritize which issues to fix first? The skill calculates **leverage** for each finding by dividing the estimated user impact by the implementation effort required. This ratio helps surface high-value fixes—such as correcting global easing tokens—that affect many components with minimal code changes. Findings are then tagged as HIGH, MEDIUM, or LOW severity to guide implementation priority. ### Can the improve-animations skill modify my code directly? No. The skill operates under a hard read-only constraint defined in [`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md). It never mutates source files; instead, it generates detailed implementation plans in the `plans/` directory. These self-contained documents can be executed by downstream agents, CI pipelines, or human developers who retain full control over when and how changes are applied. ### What information is included in a generated plan? Each plan follows the [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md) structure and includes the exact file path, current code excerpt, target animation values (such as specific cubic-bezier curves or spring physics), repository-specific token conventions, step-by-step editing instructions, and verification criteria. This explicit format ensures that even low-capability agents can execute the fixes without requiring additional context or clarification.