# How the emilkowalski/skills Repository is Structured: A Complete Guide

> Explore the emilkowalski/skills repository structure. Learn how each UI animation and design skill is organized in its own directory with a canonical SKILL.md file for rules and workflows.

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

---

**The emilkowalski/skills repository is organized as a modular, Markdown-based knowledge toolkit where each UI animation or design skill lives in its own directory under `skills/`, with a canonical [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) file defining rules, workflows, and decision trees.**

Every skill in this open-source collection is a self-contained specification that encodes best practices for designers and engineers. According to the source code, the repository functions as both human-readable documentation and machine-parseable instructions for automation agents and a companion CLI.

## Top-Level Directory Layout

The repository root contains minimal boilerplate plus the container for all skill modules:

```

/README.md          # Introduction, installation, high-level feature list

/LICENSE            # MIT license

/skills/            # Container directory for every skill module

```

This flat structure keeps the repository approachable. The real complexity lives inside `skills/`, where each subdirectory represents a discrete capability.

## The `skills/` Directory: Modular Skill Architecture

Each subdirectory under `skills/` follows a consistent pattern. As implemented in `emilkowalski/skills`, the directory contains nine specialized modules:

| Skill Folder | Purpose | Key Files |
|-------------|---------|-----------|
| `animate/` | Generate complete, review-ready animation implementations | [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md), [`RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md) |
| `review-animations/` | Enforce strict animation quality rules | [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md), [`STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/STANDARDS.md) |
| `improve-animations/` | Audit codebases and emit prioritized improvement plans | [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md), [`AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/AUDIT.md), [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md) |
| `find-animation-opportunities/` | Scan UIs for places where motion adds value | [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) |
| `animation-vocabulary/` | Define precise terminology for animation intent | [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) |
| `apple-design/` | Summarize Apple's UI design and motion guidelines for web | [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) |
| `pick-ui-library/` | Recommend optimal UI libraries for frontend tasks | [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) |
| `prototype/` | Generate UI mock-ups and switchers for rapid experimentation | [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md), [`PICKER.md`](https://github.com/emilkowalski/skills/blob/main/PICKER.md) |
| `emil-design-eng/` | Core skill blending animation with broader design advice | [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) |

## Anatomy of a Skill Module: The [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) Pattern

Every skill module centers on a [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) file with standardized structure. Based on the source analysis of files like [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md) and [`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md), each contains:

- **YAML front-matter** with `name` and `description` fields
- **Operating posture**: who the skill pretends to be when invoked
- **Hard rules**: non-negotiable constraints that must never be broken
- **Step-by-step decision flow**: gate → purpose → tool → properties → easing → duration
- **"Never ship" checklist**: quality gates used by downstream review skills

This structure makes each skill **self-documenting and self-contained**. No external configuration is required to invoke a skill.

## Supporting Documentation Files

Skills may include supplementary Markdown files that extend their capabilities:

| File Pattern | Purpose | Example Location |
|-------------|---------|----------------|
| [`RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md) | Ready-to-copy code snippets for common components | [`skills/animate/RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/RECIPES.md) |
| [`STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/STANDARDS.md) | Detailed quality criteria for review workflows | [`skills/review-animations/STANDARDS.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/STANDARDS.md) |
| [`AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/AUDIT.md) | Specific inspection procedures for codebase analysis | [`skills/improve-animations/AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/AUDIT.md) |
| [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md) | Output format for generated improvement reports | [`skills/improve-animations/PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/PLAN-TEMPLATE.md) |
| [`PICKER.md`](https://github.com/emilkowalski/skills/blob/main/PICKER.md) | Decision helpers for selection tasks | [`skills/prototype/PICKER.md`](https://github.com/emilkowalski/skills/blob/main/skills/prototype/PICKER.md) |

## How the Repository Structure Enables CLI Consumption

The Markdown-based architecture directly supports the `skills` CLI. Installation pulls the latest skill definitions:

```bash
npx skills@latest add emilkowalski/skills

```

Individual skills are invoked by directory name, with the CLI parsing the corresponding [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md):

```bash
npx skills animate              # Reads skills/animate/SKILL.md

npx skills pick-ui-library      # Reads skills/pick-ui-library/SKILL.md

npx skills improve-animations   # Reads skills/improve-animations/SKILL.md

```

Because skills are pure-text specifications, AI agents can parse the markdown, follow embedded decision tables, and produce code that satisfies the "Never ship" checks without additional tooling.

## File Paths Reference for Repository Navigation

| Path | Role in Repository Structure |
|------|------------------------------|
| [`README.md`](https://github.com/emilkowalski/skills/blob/main/README.md) | Front-page documentation and installation guide |
| `LICENSE` | MIT license |
| [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md) | Core animation generation logic |
| [`skills/animate/RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/RECIPES.md) | Ready-made implementations for common UI patterns |
| [`skills/review-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/review-animations/SKILL.md) | Strict QA checklist for animation review |
| [`skills/improve-animations/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/SKILL.md) | Audit workflow definition |
| [`skills/improve-animations/PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/skills/improve-animations/PLAN-TEMPLATE.md) | Template for improvement reports |
| [`skills/pick-ui-library/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/pick-ui-library/SKILL.md) | Library recommendation engine |
| `skills/*/SKILL.md` | Canonical definition for each respective skill |

## Summary

- The **emilkowalski/skills** repository structure prioritizes **modular, self-contained skill modules** under the `skills/` directory
- Each skill requires **only a [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) file** with YAML front-matter and structured markdown body
- **Supplementary files** ([`RECIPES.md`](https://github.com/emilkowalski/skills/blob/main/RECIPES.md), [`AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/AUDIT.md), [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md)) extend skills for specific workflows
- The **Markdown-first design** enables consumption by humans, the `skills` CLI, and AI agents without translation layers
- **File paths directly map to CLI commands**: `npx skills animate` reads [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md)

## Frequently Asked Questions

### What is the minimum file required for a skill to function?

A single [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) file with proper YAML front-matter containing `name` and `description` fields, plus a structured body defining operating posture, hard rules, and decision workflows. The `skills/improve-animations/` module demonstrates that additional files like [`AUDIT.md`](https://github.com/emilkowalski/skills/blob/main/AUDIT.md) and [`PLAN-TEMPLATE.md`](https://github.com/emilkowalski/skills/blob/main/PLAN-TEMPLATE.md) are optional extensions.

### How does the CLI know which files to read for each skill?

The CLI maps command names directly to directory names under `skills/`. Running `npx skills animate` locates and parses [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md). This convention-based routing eliminates configuration files and keeps the repository structure transparent.

### Can I add custom skills to my local installation?

Yes. The repository structure supports extension: create a new folder under `skills/`, add a [`SKILL.md`](https://github.com/emilkowalski/skills/blob/main/SKILL.md) following the established YAML front-matter and decision-flow pattern, and the skill becomes available to any parser that understands the format. The CLI's `add` command pulls from GitHub by default, but local skill directories follow identical conventions.

### Why use Markdown instead of JSON or YAML for skill definitions?

Markdown enables **rich, readable documentation** for human authors while remaining **machine-parseable** for automation. Code blocks embed directly, decision trees render clearly, and version control diffs remain meaningful. The "Never ship" checklists and step-by-step flows in [`skills/animate/SKILL.md`](https://github.com/emilkowalski/skills/blob/main/skills/animate/SKILL.md) would be significantly harder to author and maintain in structured data formats alone.