How the improve-animations Skill Audits Codebases for Motion Issues

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, 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, 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 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:

improve-animations

Execute a quick audit focused only on high-traffic components:

improve-animations quick

Target a specific violation category, such as easing issues:

improve-animations easing

Skip the audit and directly author a plan for a described improvement:

improve-animations plan "replace all ease-in on UI with --ease-out token"

Execute a previously written plan using a lower-capability agent:

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 – Contains the core workflow description, hard rules (including the read-only constraint), and the complete invocation matrix.
• 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 – 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, 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, 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}