How to Customize or Extend Skills for Specific UI Animation Needs

You extend the emilkowalski/skills repository by adding new recipes to skills/animate/RECIPES.md or creating dedicated sub-skills that inherit the core gate logic, ensuring all custom animations follow the six-step decision pipeline for GPU-accelerated, accessible motion.

The emilkowalski/skills repository treats UI animation as a modular capability that language models invoke through structured markdown files. Each animation request flows through a strict decision tree defined in skills/animate/SKILL.md, which guarantees consistent performance and accessibility without procedural code.

Understanding the Core Animation Skill Structure

The foundation of any animation resides in skills/animate/SKILL.md. This file encodes a declarative decision tree that the model evaluates before emitting code, consisting of six sequential gates implemented as markdown tables.

Gate 1: Frequency Check

The skill first evaluates whether animation is appropriate. Keyboard shortcuts and high-frequency interactions automatically bypass animation to maintain UI responsiveness and prevent motion fatigue.

Gate 2: Purpose Validation

The user must explicitly declare a purpose—such as feedback or delight—in the prompt. If no purpose is supplied, the skill aborts immediately, preventing arbitrary decorative motion.

Tool Selection Hierarchy

When animation proceeds, the skill selects the cheapest adequate tool from this priority list defined in lines 59-70:

• CSS transitions for simple state changes
• CSS animations for multi-step keyframes
• Web Animations API (WAAPI) for programmatic control
• Framer Motion for complex physics-based interactions

Property Constraints

The skill restricts animations to transform, opacity, and optionally clip-path. This constraint guarantees GPU acceleration and prevents layout thrashing by avoiding width, height, or top/left animations.

Token-Based Timing

Instead of arbitrary values, the skill pulls easing curves and durations from a predefined token table—such as --ease-out and --duration-modal—ensuring visual coherence across the application.

Interruption Handling

For rapid interactions, the skill prefers transitions over keyframes to allow reversible state changes, reserving spring physics for gesture-based animations.

Extending Skills with Custom Animation Recipes

To support a custom UI pattern—such as a fold-out panel—you do not modify the core logic. Instead, you extend the system by adding recipes and optional sub-skills.

Adding a New Recipe to RECIPES.md

Create your implementation in skills/animate/RECIPES.md using the established token conventions:

## Fold-out panel

```css
.fold-panel {
  overflow: hidden;
  transform-origin: top;
  transition:
    height 250ms var(--ease-out),
    opacity 250ms var(--ease-out);
}

.fold-panel[data-closed] {
  height: 0;
  opacity: 0;
}

This recipe automatically inherits the property constraints and token system from the core skill.

### Creating a Dedicated Sub-Skill

If your pattern requires custom gating logic—such as a fold-out that only appears for first-time visits—duplicate [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md) into a new file like [`skills/fold-out/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/fold-out/SKILL.md). Adjust the Purpose table to include new conditions (`first-time → delight`), and reference your recipe with a markdown link:

```markdown
[Fold-out recipe](../animate/RECIPES.md#fold-out-panel)

Wire the skill by calling it directly in your prompt:

animate: "Create a fold-out panel for the settings drawer."

Integrating Third-Party Motion Libraries

When CSS capabilities prove insufficient—such as for drag-with-momentum gestures—the core skill automatically escalates to Framer Motion. The skills/pick-ui-library/SKILL.md file checks package.json for existing dependencies; if motion is present, the animation skill emits Motion-compatible code:

<motion.div
  animate={{ transform: "translateX(100px)" }}
  transition={{ type: "spring", bounce: 0.2, duration: 0.5 }}
/>

Reference the library picker skill before emitting complex animations to ensure the dependency exists and avoid runtime errors.

Best Practices for Skill Extensions

Follow these guidelines when customizing skills:

• Reuse existing tokens (--ease-out, --duration-modal) to maintain visual coherence across the application.
• Preserve the gate flow by always starting with "Should this animate?" checks to prevent over-animation.
• Document using markdown tables matching the existing format so models can parse the logic automatically.
• Link recipes to skills using relative markdown links for discoverability.
• Validate with review-animations after adding custom code to ensure style guide compliance.

Summary

• The core animation logic lives in skills/animate/SKILL.md and follows a six-step decision pipeline including frequency checks, purpose validation, and tool selection.
• Extend the system by adding concrete implementations to skills/animate/RECIPES.md rather than modifying core decision files.
• Create sub-skills only when you need custom gating logic beyond the standard frequency and purpose checks defined in the core skill.
• The tool selection hierarchy automatically escalates from CSS transitions to Framer Motion based on interaction complexity and existing dependencies.
• Always use predefined design tokens for timing and easing to ensure consistency with the broader animation system.

Frequently Asked Questions

Where do I add a new animation pattern?

Add concrete CSS or JS implementations to skills/animate/RECIPES.md. If the pattern requires unique conditional logic—such as appearing only for first-time users—create a new sub-skill by duplicating skills/animate/SKILL.md into a dedicated directory like skills/your-pattern/SKILL.md and modifying the appropriate decision tables.

How does the skill decide which animation tool to use?

The decision table in lines 59-70 of skills/animate/SKILL.md defines a strict hierarchy: CSS transitions for simple state changes, CSS animations for keyframe sequences, WAAPI for programmatic control, and Framer Motion for complex physics-based interactions requiring springs or gestures.

Can I override the default gate logic for specific use cases?

Yes. Create a dedicated sub-skill that duplicates the core structure but modifies the Purpose or Frequency tables. This allows you to implement specialized conditions—such as first-time user animations or accessibility-reduced-motion preferences—while maintaining the property constraints and token system enforced by the parent skill.

How do I ensure my custom animation uses the correct design tokens?

Reference the token table defined in the core skill files using CSS custom properties like var(--ease-out) and var(--duration-modal) instead of hard-coded values. After implementation, invoke the review-animations skill to validate that your custom recipes adhere to the established token system and performance constraints.

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