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

> Explore practical AI agent UI design workflows using the emilkowalski/skills repository. Execute complete UI design tasks from ideation to improvement planning with simple markdown files.

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

---

**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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) or [`PICKER.md`](https://github.com/emilkowalski/skills/blob/main/PICKER.md), containing YAML front matter (`name`, `description`) followed by concrete guidelines and code snippets.
- **Supporting Assets**: Auxiliary files like [`RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md) and [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md) provide reusable snippets and plan structures for specific workflows.
- **Meta-Documentation**: [`STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md)) audits the codebase, creates prioritized plan items, and emits a structured summary. The skill references [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md) (lines 73-77) to generate a [`plans/README.md`](https://github.com/emilkowalski/skills/blob/main/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`:

```javascript
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`](https://github.com/emilkowalski/skills/blob/main/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:

```python
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`](https://github.com/emilkowalski/skills/blob/main/skills/emil-design-eng/SKILL.md) and enforced by [`skills/review-animations/STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md).

### Creating Improvement Plans (Shell)

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

```bash
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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/skills/emil-design-eng/SKILL.md)**: Core design engineering philosophy and the required review table format for animation critiques.
- **[`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md)**: Step-by-step guide for building animations from scratch, referenced during the ideation phase.
- **[`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md)**: Strict checklist enforcing animation quality standards and required markdown output formats.
- **[`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md)**: Audit procedures and prioritization logic for systematic UI improvements.
- **[`skills/improve-animations/PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/PLAN-TEMPLATE.md)**: Template structure for generating actionable improvement plans.
- **[`skills/review-animations/STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/skills/prototype/SKILL.md), validation via [`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md), and systematic improvement via [`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/skills/emil-design-eng/SKILL.md) and standardized across the repository via [`skills/review-animations/STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/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`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md), it creates a [`plans/README.md`](https://github.com/emilkowalski/skills/blob/main/plans/README.md) file using the template from [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md), assigning severity ratings and TODO statuses to each issue, effectively bridging the gap between review and implementation.