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

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, 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, match a user description, and format the response according to the skill specification:

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:

**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)
2. Code Generation – Feed the canonical term into the animate skill (skills/animate/SKILL.md), which provides concrete animation recipes
3. Refinement – Apply the improve-animations skill (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, 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, 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. 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), which provides concrete animation recipes and code patterns, and improve-animations (skills/improve-animations/SKILL.md), which focuses on refining existing animation implementations. Together, these form a complete pipeline from concept to polished implementation.

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