How Emil Kowalski's Skills Help AI Agents Make Design Decisions: A Deep Dive into Executable UI/Animation Expertise

Emil Kowalski's skills are self-contained, markdown-based knowledge modules that convert decades of UI/animation expertise into deterministic, auditable guidance that AI agents can parse, reason over, and execute without human intervention.

The emilkowalski/skills repository transforms subjective design taste into structured, machine-readable instructions. Each skill lives at skills/*/SKILL.md and provides a complete decision framework—from philosophy to implementation—that LLM-based agents can consume directly.

What Makes These Skills Machine-Actionable

Unlike generic design advice, Kowalski's skills enforce a strict internal architecture that eliminates ambiguity for automated systems:

Component	Location	Function
YAML front-matter	Top of each SKILL.md	Declares name, description, and scope so agents can route requests to the correct module
Decision tables	Core section of each skill	Encode conditional logic (e.g., animation frequency → implementation strategy) as parseable markdown
Hard rules	Explicit ### Hard Rules sections	Guardrails that trigger immediate rejection of unsafe outputs with explanatory errors

| Recipes & snippets | RECIPES.md or inline code blocks | Copy-paste implementations guaranteed to pass subsequent validation | | Review format | Mandatory output specification | Standardizes agent responses as markdown tables for human verification and re-processing | | Cross-skill references | Inline links (e.g., "see pick-ui-library") | Enable composable, multi-stage decision pipelines |

This structure lets an agent traverse a knowledge graph rather than retrieve isolated facts. For example, the animate skill in skills/animate/SKILL.md references the core philosophy in skills/emil-design-eng/SKILL.md, creating a coherent reasoning chain from first principles to final code.

The Decision Pipeline: How Agents Use These Skills

AI agents following Kowalski's skills execute a six-stage deterministic workflow:

1. Load — Parse front-matter to identify the relevant skill for a user request
2. Parse — Extract scope, constraints, and available tools from the skill body
3. Apply — Map inputs against decision tables and enforce hard rules (early exit on violation)
4. Select — Choose implementation tools (CSS transitions, WAAPI, Motion, etc.) based on table outputs
5. Generate — Emit code using approved recipes and format output per the review specification
6. Validate — Optionally delegate to secondary skills like review-animations for automated quality checks

Because all knowledge lives in plain markdown, any LLM with structured text parsing can execute this pipeline—making the same design reasoning reusable across React, Vue, Svelte, or even native mobile projects.

Hard Rules: The Guardrail System

The animate skill's hard rules section (lines 21-27 in skills/animate/SKILL.md) exemplifies how Kowalski encodes quality enforcement:

• "Never use ease-in on UI" — Eliminates sluggish-feeling deceleration curves
• "Use only transform and opacity for animations" — Guarantees 60fps by avoiding layout-triggering properties
• "Respect prefers-reduced-motion" — Mandates accessibility compliance before code generation

Agents check each rule before emitting output. A violation forces immediate termination with a clear explanation, preventing the "confidently wrong" behavior common in unconstrained LLM outputs.

Decision Tables in Practice

The emil-design-eng skill contains the foundational frequency gating table (lines 62-75) that determines whether an animation should exist at all:

Frequency	Decision	Implementation
Constant (scroll, hover)	No animation	Static state or immediate feedback
Frequent (dropdowns, tooltips)	Micro-interaction only	Sub-150ms, minimal easing
Occasional (modals, toasts, drawers)	Standard animation	Full 200-400ms with deliberate easing
One-time (onboarding, celebration)	Enhanced animation	Longer, more expressive motion

Agents evaluate user requests against this table to avoid animation overload—a common failure mode when developers animate everything by default.

Real-World Agent Execution Examples

Example 1: Toast Entrance Animation

User request: "Add an entrance animation to my toast component"

Agent reasoning trace using animate skill:

Gate result: Frequency = "Occasional" → Standard animation permitted
Purpose: Delight (first-time toast appearance)
Tool: CSS animation (runs off main thread)
Properties: transform + opacity (hard rule enforced)
Easing: --ease-out (cubic-bezier(0.23, 1, 0.32, 1))
Duration: 250ms (within "Occasional" tier)

Generated output:

.toast {
  opacity: 0;
  transform: translateY(100%);
  animation: toastEnter 250ms var(--ease-out) forwards;
}

@keyframes toastEnter {
  to { opacity: 1; transform: translateY(0); }
}

Mandatory review table:

Before	After	Why
opacity: 0; transform: translateY(100%); (no animation)	CSS animation as above	Smooth, perceptually fast entrance under 300ms threshold

The agent followed the decision table's frequency tier and enforced the hard rule restricting properties to transform and opacity.

Example 2: Component Library Selection

User request: "Recommend a React toast library matching this design system"

Agent using pick-ui-library skill:

• Selected: Sonner
• Rationale: Lightweight, CSS transition-based, respects prefers-reduced-motion, ships with --ease-out token matching the design system's animation vocabulary
• Implementation:

import { toast, Toaster } from "sonner";

function notify(message: string) {
  toast(message);
}

This selection applies the "good defaults matter more than options" principle from the Sonner Principles section in emil-design-eng (lines 58-66), demonstrating how cross-skill references maintain consistency.

The Complete Skill Ecosystem

File Path	Role in AI Decision-Making
skills/emil-design-eng/SKILL.md	Foundational philosophy and decision tables inherited by all animation skills
skills/animate/SKILL.md	Full construction pipeline: gating, purpose analysis, tool selection, easing, duration, interruption handling
skills/review-animations/SKILL.md	Output validation enforcing markdown-table format for automated quality loops
skills/improve-animations/SKILL.md	Codebase auditing producing prioritized, agent-consumable action plans
skills/find-animation-opportunities/SKILL.md	UI scanning guidance using the same decision framework to identify where animation adds value
skills/pick-ui-library/SKILL.md	Vetted library list with selection criteria preventing abandoned or inappropriate recommendations
skills/animation-vocabulary/SKILL.md	Standardized terminology for cross-agent communication and semantic consistency

Each skill composes with others. An agent might chain find-animation-opportunities → animate → review-animations to move from discovery through implementation to validation without human handoff.

Why Markdown Enables Cross-Platform AI Design

The skills' language-agnostic markdown format provides critical advantages for AI agent deployment:

• No runtime dependencies — Agents parse text, not proprietary binaries
• Version control friendly — Git diffs track evolution of design rules
• Human inspectable — Developers can read and override agent reasoning
• LLM-native — Structured text aligns with how language models process context

This format choice means Kowalski's animation expertise can guide agents writing Flutter, SwiftUI, or CSS with equal fidelity—the decision tables translate, even when implementation syntax changes.

Summary

• Skills are executable expertise: Each SKILL.md combines philosophy, decision logic, guardrails, and implementations into a single agent-consumable document
• Hard rules prevent failure: Explicit prohibitions stop agents before they generate low-quality or inaccessible code
• Decision tables enable deterministic reasoning: Input conditions map to specific outputs without LLM hallucination
• Cross-skill references create pipelines: Complex design tasks decompose into validated stages
• Markdown format ensures portability: The same knowledge works across frameworks, languages, and agent implementations

Frequently Asked Questions

How do AI agents know which skill to use?

Agents match user requests against the name and description fields in each skill's YAML front-matter. For example, a request mentioning "animation" triggers loading of skills/animate/SKILL.md, while "component library" routes to skills/pick-ui-library/SKILL.md. The repository's README.md provides an index for discovery.

Can developers override or extend these skills?

Yes. Skills are plain markdown files in version control. Developers can fork the repository, modify decision tables, add hard rules for their design system, or create new SKILL.md files following the established structure. The review-animations skill will validate outputs against whatever rules are present.

What happens when an agent violates a hard rule?

The agent must halt execution and return a clear error message explaining which rule was triggered and why. In skills/animate/SKILL.md, the hard rules section (lines 21-27) explicitly requires this behavior—preventing the common failure mode where LLMs generate "confidently wrong" code that breaks performance or accessibility requirements.

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