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

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 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, RECIPES.md
review-animations/	Enforce strict animation quality rules	SKILL.md, STANDARDS.md
improve-animations/	Audit codebases and emit prioritized improvement plans	SKILL.md, AUDIT.md, PLAN-TEMPLATE.md
find-animation-opportunities/	Scan UIs for places where motion adds value	SKILL.md
animation-vocabulary/	Define precise terminology for animation intent	SKILL.md
apple-design/	Summarize Apple's UI design and motion guidelines for web	SKILL.md
pick-ui-library/	Recommend optimal UI libraries for frontend tasks	SKILL.md
prototype/	Generate UI mock-ups and switchers for rapid experimentation	SKILL.md, PICKER.md
emil-design-eng/	Core skill blending animation with broader design advice	SKILL.md

Anatomy of a Skill Module: The SKILL.md Pattern

Every skill module centers on a SKILL.md file with standardized structure. Based on the source analysis of files like skills/animate/SKILL.md and 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	Ready-to-copy code snippets for common components	skills/animate/RECIPES.md
STANDARDS.md	Detailed quality criteria for review workflows	skills/review-animations/STANDARDS.md
AUDIT.md	Specific inspection procedures for codebase analysis	skills/improve-animations/AUDIT.md
PLAN-TEMPLATE.md	Output format for generated improvement reports	skills/improve-animations/PLAN-TEMPLATE.md
PICKER.md	Decision helpers for selection tasks	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:

npx skills@latest add emilkowalski/skills

Individual skills are invoked by directory name, with the CLI parsing the corresponding SKILL.md:

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	Front-page documentation and installation guide
LICENSE	MIT license
skills/animate/SKILL.md	Core animation generation logic
skills/animate/RECIPES.md	Ready-made implementations for common UI patterns
skills/review-animations/SKILL.md	Strict QA checklist for animation review
skills/improve-animations/SKILL.md	Audit workflow definition
skills/improve-animations/PLAN-TEMPLATE.md	Template for improvement reports
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 file with YAML front-matter and structured markdown body
• Supplementary files (RECIPES.md, AUDIT.md, 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

Frequently Asked Questions

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

A single 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 and 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. 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 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 would be significantly harder to author and maintain in structured data formats alone.

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