# How to Use animation-vocabulary to Get Better Animations from AI

> Unlock superior AI animations with animation-vocabulary. This skill translates vague motion into precise animation terms for accurate code generation. Learn how now!

- Repository: [Emil Kowalski/skills](https://github.com/emilkowalski/skills)
- Tags: how-to-guide
- Published: 2026-08-08

---

**The `animation-vocabulary` skill is a reverse-lookup glossary that converts vague motion descriptions into precise animation terms, enabling AI models to generate accurate animation code.**

The `animation-vocabulary` skill in the `emilkowalski/skills` repository solves the "I know what I want but don't know what it's called" problem in UI animation. Unlike code generators, this tool acts as a semantic bridge between informal descriptions and industry-standard terminology, dramatically improving the quality of AI-generated animations by ensuring you use the exact terms models understand best.

## What is animation-vocabulary?

`animation-vocabulary` is a **reverse-lookup glossary** designed to translate vague descriptions of motion effects into precise terms that designers and AI models recognize. The skill does not generate animation code itself; instead, it functions as a naming aid that answers *"what's the exact name of that effect?"* with canonical terminology like **Rubber-banding**, **Stagger**, or **Shared element transition**.

This naming step is critical because most LLM-based animation assistants understand official terminology significantly better than free-form adjectives. By feeding the precise term into your prompt, you eliminate ambiguity and ensure the AI selects the correct motion parameters.

## How the Skill Works

### Core Architecture in SKILL.md

The skill definition lives in [`skills/animation-vocabulary/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animation-vocabulary/SKILL.md), which serves as both documentation and the functional data source for runtime lookups.

The file structure follows a discoverable format:

- **Lines 2-4** contain YAML front-matter (`name`, `description`) that downstream tooling parses to discover the skill automatically
- **Lines 12-17** demonstrate the expected output format: a bold term followed by an em-dash and definition
- **Lines 56-174** house the comprehensive glossary containing all available animation terms and their definitions

### Runtime Matching Logic

When integrated into a workflow (such as Instagit's skill executor), the runtime performs the following steps:

1. **Parses** the Markdown file to extract the glossary section into an in-memory map of *term → description*
2. **Executes** a semantic match using either lightweight embedding similarity or keyword-weighting algorithms against the user's free-form description
3. **Returns** the best-matching term in the exact format specified in lines 12-17, optionally including close alternates as shown in lines 18-26

This architecture allows the skill to function without code changes when the glossary expands—adding a new term requires only editing the Markdown file.

## Why Precise Vocabulary Improves AI Output

Using `animation-vocabulary` improves AI-generated animations through three specific mechanisms:

- **Precision** – Feeding the exact term (e.g., *Rubber-banding*) into an LLM prompt ensures the model selects the correct motion parameters, such as physics-based spring curves or overscroll behavior, rather than guessing from ambiguous adjectives like "bouncy"
- **Disambiguation** – When multiple terms could apply, the skill returns the primary match first, followed by 1-2 alternates with one-line distinctions (as implemented in lines 18-26), allowing you to select the most appropriate concept before finalizing your prompt
- **Consistent Vocabulary** – The glossary acts as a single source of truth across your project, preventing "semantic drift" where different team members use varying terminology for identical effects

## Implementing the Lookup in Python

Below is a minimal implementation demonstrating how to load the glossary from [`skills/animation-vocabulary/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animation-vocabulary/SKILL.md), match a user description, and format the response according to the skill specification:

```python
import re
import pathlib
from typing import List, Tuple

# 1️⃣ Load the glossary -------------------------------------------------

def load_glossary(md_path: pathlib.Path) -> List[Tuple[str, str]]:
    """Parse the Glossary section (lines after '## Glossary') into (term, description)."""

    text = md_path.read_text(encoding="utf-8")
    # Find the start of the glossary

    glossary_start = text.index("## Glossary")

    glossary = text[glossary_start:]
    entries = []
    # Each entry starts with a markdown list item "- **Term** — Description"

    for line in glossary.splitlines():
        m = re.match(r"- \*\*(.+?)\*\* — (.+)", line)
        if m:
            term, desc = m.groups()
            entries.append((term.strip(), desc.strip()))
    return entries

# 2️⃣ Simple semantic matcher (keyword overlap) -------------------------

def best_match(description: str, glossary: List[Tuple[str, str]]) -> List[Tuple[str, str]]:
    """Return the best match and up to two alternates."""
    words = set(description.lower().split())
    scores = []
    for term, gloss in glossary:
        term_words = set(term.lower().split())
        gloss_words = set(gloss.lower().split())
        overlap = len(words & term_words) + len(words & gloss_words)
        scores.append((overlap, term, gloss))
    scores.sort(reverse=True)
    # Return top three entries (primary + up to two alternates)

    return [(t, d) for _, t, d in scores[:3]]

# 3️⃣ Format according to the SKILL spec --------------------------------

def format_response(matches: List[Tuple[str, str]]) -> str:
    primary, *alternates = matches
    lines = [f"**{primary[0]}** — {primary[1]}\n"]
    if alternates:
        lines.append("Close alternates:\n")
        for alt in alternates:
            lines.append(f"- **{alt[0]}** — {alt[1]}\n")
    return "```\n" + "".join(lines) + "```"

# 4️⃣ Example usage ------------------------------------------------------

if __name__ == "__main__":
    md_file = pathlib.Path(__file__).parent.parent / "skills" / "animation-vocabulary" / "SKILL.md"
    glossary = load_glossary(md_file)

    user_input = "What do you call the animation where a popover seems to grow out of the button that opened it?"
    matches = best_match(user_input, glossary)
    print(format_response(matches))

```

**Sample Output:**

```markdown
**Origin-aware animation** — An element animates out of its trigger, like a popover growing from the button that opened it instead of from its own center which is the default in CSS.

Close alternates:
- **Pop in** — An element appears with a slight overshoot, like it bounces into place.
- **Scale in** — Element grows from smaller to full size as it appears, often paired with a fade.

```

## Connecting with the Animation Pipeline

The `animation-vocabulary` skill functions as the first step in a multi-stage animation workflow within the `emilkowalski/skills` ecosystem:

1. **Term Discovery** – Use `animation-vocabulary` to identify that "the thing where a popover grows from the button" is called **Origin-aware animation** (as demonstrated in lines 31-36 of [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md))
2. **Code Generation** – Feed the canonical term into the `animate` skill ([`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md)), which provides concrete animation recipes
3. **Refinement** – Apply the `improve-animations` skill ([`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md)) to polish timing, easing, and accessibility

This separation of concerns ensures that you name the effect correctly before requesting implementation details, preventing costly iterations caused by terminology mismatches.

## Summary

- **`animation-vocabulary`** is a reverse-lookup glossary, not a code generator, designed to translate vague motion descriptions into precise industry terms
- The skill definition resides in [`skills/animation-vocabulary/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animation-vocabulary/SKILL.md), with the glossary occupying lines 56-174 and front-matter metadata in lines 2-4
- Runtime implementations parse this Markdown file to perform semantic matching against user queries
- Using canonical terms like **Origin-aware animation** or **Rubber-banding** in AI prompts produces significantly more accurate animation code than descriptive adjectives
- The skill integrates with companion skills (`animate`, `improve-animations`) to form a complete animation workflow

## Frequently Asked Questions

### Is animation-vocabulary a code generator?

No. `animation-vocabulary` is strictly a **naming aid** that returns the precise term for a described motion effect. It does not output CSS, JavaScript, or any other animation code. Once you have the correct term, you use it to prompt a code-generating AI or reference the `animate` skill in the same repository.

### How does the skill handle ambiguous descriptions?

When a description could match multiple terms, the skill returns the best match first, followed by up to two alternates. As shown in lines 18-26 of [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md), each alternate includes a one-line distinction explaining how it differs from the primary match, allowing you to select the most appropriate term for your specific context.

### Can I add custom animation terms to the glossary?

Yes. The skill is designed for extensibility—adding a new term requires only editing the Glossary section of [`skills/animation-vocabulary/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animation-vocabulary/SKILL.md). The skill executor automatically picks up new entries without requiring code changes, making it ideal for domain-specific animation vocabularies.

### What other skills work with animation-vocabulary?

The repository includes two complementary skills: **`animate`** ([`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md)), which provides concrete animation recipes and code patterns, and **`improve-animations`** ([`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md)), which focuses on refining existing animation implementations. Together, these form a complete pipeline from concept to polished implementation.