AI Agent UI Design Workflows: Practical Examples Using the Skills Repository

The Skills repository enables AI agents to execute complete UI design workflows—from ideation and animation review to improvement planning—using nothing more than markdown files with YAML front matter and structured rules.

The Skills repository by emilkowalski is a curated collection of knowledge packs that encode UI design best practices, animation guidelines, and component-building heuristics into machine-readable markdown. By organizing expertise into discrete, parseable skills, the repository powers AI agent UI design workflows that automate prototyping, strict quality reviews, and systematic improvements without requiring specialized runtime libraries.

Repository Architecture for Agent-Driven Design

The repository structures design knowledge into four distinct layers that make it discoverable and actionable by automated agents.

• Entry Point: The root README.md provides the installation command and high-level index of available skills.
• Skill Definitions: Each skill lives under skills/<category>/ as either SKILL.md or PICKER.md, containing YAML front matter (name, description) followed by concrete guidelines and code snippets.
• Supporting Assets: Auxiliary files like RECIPES.md and PLAN-TEMPLATE.md provide reusable snippets and plan structures for specific workflows.
• Meta-Documentation: STANDARDS.md defines formatting rules—such as required markdown table structures—that all skills share.

Because every skill is pure markdown, an agent only needs a YAML parser and markdown renderer to interpret the knowledge base, making the system lightweight and version-controlled.

Three-Stage AI Agent Workflow

A complete UI design workflow using these skills follows a structured pipeline that maps directly to three core skill files.

1. Ideation with the Prototype Skill

The agent begins by invoking the prototype skill (skills/prototype/SKILL.md) to generate multiple visual mock-ups based on user requirements. This skill provides heuristics for rapid UI exploration and component selection.

2. Strict Review with Review-Animations

Next, the agent calls review-animations (skills/review-animations/SKILL.md) to validate each mock-up against animation best practices. According to the source code in skills/emil-design-eng/SKILL.md (lines 38-48), the agent must output findings as a markdown table with three columns: Before, After, and Why.

The review enforces strict rules such as:

• Avoid transition: all in favor of specific properties
• Use custom easing curves instead of defaults
• Limit animation duration to under 300ms

3. Improvement Planning with Improve-Animations

Finally, the improve-animations skill (skills/improve-animations/SKILL.md) audits the codebase, creates prioritized plan items, and emits a structured summary. The skill references PLAN-TEMPLATE.md (lines 73-77) to generate a plans/README.md file containing a severity-ranked table of issues.

Implementing the Workflow: Code Examples

Below are concrete implementations showing how an AI agent interacts with the repository structure.

Loading the Skills Catalog (Node.js)

This snippet discovers all available skills by scanning the skills/ directory and parsing YAML front matter using gray-matter:

import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';

const skillDir = path.resolve('skills');
const catalog = {};

fs.readdirSync(skillDir, { withFileTypes: true }).forEach(dirent => {
  if (!dirent.isDirectory()) return;
  const skillPath = path.join(skillDir, dirent.name, 'SKILL.md');
  if (fs.existsSync(skillPath)) {
    const { data } = matter(fs.readFileSync(skillPath, 'utf8'));
    catalog[data.name] = {
      description: data.description,
      path: skillPath,
    };
  }
});

console.log('Available skills:', catalog);

This matches the front-matter structure found in skills/emil-design-eng/SKILL.md, which defines name and description fields for agent discovery.

Generating Review Tables (Python)

When executing the review-animations workflow, the agent emits findings in the required markdown table format:

def review_animation(issue, before, after, why):
    """Emit a markdown table row for a UI animation issue."""
    return f"| {before} | {after} | {why} |\n"

print("| Before | After | Why |\n|---|---|---|")
print(review_animation(
    "duration",
    "`transition: all 300ms`",
    "`transition: transform 200ms ease-out`",
    "Specify exact properties; avoid `all`"
))

This output format is strictly defined in skills/emil-design-eng/SKILL.md and enforced by skills/review-animations/STANDARDS.md.

Creating Improvement Plans (Shell)

To initiate the improvement phase, the agent generates a plan file following the template structure:

cat <<EOF > plans/README.md
| # | Title                     | Severity | Status |

|---|---------------------------|----------|--------|
| 1 | Replace \`transition: all\` | High     | TODO   |
| 2 | Add custom easing curves  | Medium   | TODO   |
EOF

# Trigger downstream execution

npx ci-runner --plan plans/README.md

This follows the plan-template guidelines specified in skills/improve-animations/PLAN-TEMPLATE.md.

Key Files and Their Functions

Understanding these specific files is essential for implementing agent-driven UI workflows:

• skills/emil-design-eng/SKILL.md: Core design engineering philosophy and the required review table format for animation critiques.
• skills/animate/SKILL.md: Step-by-step guide for building animations from scratch, referenced during the ideation phase.
• skills/review-animations/SKILL.md: Strict checklist enforcing animation quality standards and required markdown output formats.
• skills/improve-animations/SKILL.md: Audit procedures and prioritization logic for systematic UI improvements.
• skills/improve-animations/PLAN-TEMPLATE.md: Template structure for generating actionable improvement plans.
• skills/review-animations/STANDARDS.md: Shared formatting standards across all skills, defining how tables and code blocks should be structured.
• skills/pick-ui-library/SKILL.md: Decision matrix for selecting UI libraries based on trust criteria and project requirements.

Summary

• The Skills repository stores UI design knowledge as markdown files with YAML front matter, making them parseable by any agent with basic markdown capabilities.
• AI agent UI design workflows follow a three-stage pipeline: ideation via skills/prototype/SKILL.md, validation via skills/review-animations/SKILL.md, and systematic improvement via skills/improve-animations/SKILL.md.
• Each skill enforces specific output formats—such as the markdown review table defined in skills/emil-design-eng/SKILL.md—ensuring consistent, machine-readable results.
• The repository requires no runtime dependencies beyond a markdown parser, enabling deployment in sandboxed CI environments using the npx skills@latest add emilkowalski/skills installation command.

Frequently Asked Questions

How does the review-animations skill enforce output formatting?

The review-animations skill requires agents to output findings as markdown tables with specific columns: Before, After, and Why. This format is defined in skills/emil-design-eng/SKILL.md and standardized across the repository via skills/review-animations/STANDARDS.md. Agents parse these rules to ensure their output matches the expected structure for downstream processing.

Can I use these skills without Node.js or JavaScript?

Yes. While the installation command uses npx skills@latest add emilkowalski/skills, the skills themselves are pure markdown files. Any runtime environment with a YAML parser and markdown renderer can load skills from the skills/ directory and execute the workflows. The Node.js examples provided are illustrative implementations, not runtime requirements.

How do I add custom skills to the repository?

Create a new directory under skills/<your-skill-name>/ containing a SKILL.md file with YAML front matter specifying name and description fields. Include actionable rules, code snippets, and any required output formats (such as markdown tables). Follow the structure established in skills/emil-design-eng/SKILL.md to ensure compatibility with agent discovery mechanisms.

What distinguishes the improve-animations skill from review-animations?

The review-animations skill performs static analysis and outputs critique tables, while improve-animations actively generates prioritized execution plans. According to skills/improve-animations/SKILL.md, it creates a plans/README.md file using the template from PLAN-TEMPLATE.md, assigning severity ratings and TODO statuses to each issue, effectively bridging the gap between review and implementation.

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