emilkowalski/skills is not one giant prompt for making interfaces prettier. At commit 7bb7061, it is a small judgment system: one broad design skill, four narrower specialists, and a deliberate handoff from expensive diagnosis to self-contained execution plans.
That separation is the architecture. The animation rules matter, but the more reusable idea for skill authors is where each kind of judgment starts, what it returns, and when it must stop.
Five files, five different contracts
The repository describes emil-design-eng as its main skill, then gives the other four narrower jobs: strict animation review, codebase-wide audit and planning, vocabulary lookup, and Apple-derived web design guidance (README.md:42-48).
| Skill | Trigger boundary | Output boundary | Role in the system |
|---|---|---|---|
animation-vocabulary |
The user can describe the motion but does not know its name | A best-match term, with one or two alternatives when needed | Normalize vague intent into shared language |
emil-design-eng |
A broad UI polish, component, or animation-decision question | General design-engineering guidance | Hold the main body of reusable taste |
apple-design |
Apple-style gestures, springs, momentum, materials, typography, or accessibility | Apple-derived principles translated into web techniques | Specialize the broad advice for physical, interruptible interaction |
review-animations |
A diff containing animation or motion code | Findings, impact tiers, and an explicit decision | Turn principles into a strict local gate |
improve-animations |
A request to improve motion across a codebase | A vetted audit and self-contained plans | Spend judgment on diagnosis and specification, then hand off implementation |
The smallest skill makes the boundary easiest to see. animation-vocabulary is a reverse lookup: vague description in, precise term out. It explicitly says it is for naming an effect, not designing or building one, and it limits ambiguity handling to a best match plus one or two alternatives (animation-vocabulary/SKILL.md:1-18). That restraint is useful. The skill does not need implementation authority to improve every later prompt.
The knowledge layer splits into general and specialized taste
emil-design-eng is the broad reference. Its declared scope spans UI polish, component design, animation decisions, and the fine details that make software feel good (emil-design-eng/SKILL.md:1-3). Its decision framework asks whether motion should exist, what purpose it serves, which easing fits, and how long it should take (emil-design-eng/SKILL.md:62-135).
apple-design is not merely a second copy. Its scope narrows to fluid, physical interaction and explicitly translates WWDC-derived ideas into CSS, Pointer Events, requestAnimationFrame, and web spring libraries (apple-design/SKILL.md:1-10). The implementation vocabulary becomes more specific: pointer-down response, pointer capture, continuous tracking, interruption from the presentation value, velocity blending, and spring retargeting (apple-design/SKILL.md:20-69).
So the knowledge layer has two depths. The main skill answers, “What usually makes this interface feel right?” The Apple skill answers, “What does that mean when the interaction must feel directly manipulated, momentum-aware, and interruptible?”
Review is a gate, not another advice mode
review-animations sharply reduces its scope: it reviews animation and motion code only. It does not write features, fix unrelated bugs, or review general code. When a finding needs a precise curve, duration, spring value, or citation, the skill points to its companion STANDARDS.md (review-animations/SKILL.md:9-17).
Its judgment is intentionally asymmetric. Every violation of ten non-negotiable standards becomes a finding (review-animations/SKILL.md:19-41). Named escalation triggers are flagged hard, and the remediation order starts by deleting or reducing motion before reaching for better easing, physicality, interruptibility, GPU properties, timing, polish, accessibility, or cohesion (review-animations/SKILL.md:43-74).
The output is equally constrained. The first part must be one Before | After | Why table. The second groups commentary by impact, then closes with Block or Approve; findings use file:line, and exact values come from STANDARDS.md rather than approximation (review-animations/SKILL.md:76-107).
This is where taste becomes an operational gate. General advice can explain trade-offs. A reviewer must emit a stable artifact that another person or agent can act on.
improve-animations moves judgment upstream
The broadest workflow still refuses to implement source changes during its normal advisory path. Its opening contract assigns the capable model the work where judgment compounds—understanding the motion surface, deciding what is worth fixing, and writing the specification—then allows execution by another agent, including a cheaper model (improve-animations/SKILL.md:6-10). Its hard rules forbid source edits and mutating operations while requiring plans to carry exact context and values (improve-animations/SKILL.md:20-24).
The analysis funnel is explicit:
- Recon comes first. The advisor maps the stack, where motion lives, existing conventions, product personality, and interaction frequency before judging anything (improve-animations/SKILL.md:28-40).
- The audit covers eight categories. Beyond a small repository, it can fan those checks out to read-only subagents, while effort levels control coverage (improve-animations/SKILL.md:42-63).
- The primary advisor re-reads every cited location, rejects invalid or duplicate findings, and orders the survivors by leverage (improve-animations/SKILL.md:65-78).
- Selected findings become implementation plans written for a zero-context executor. Those plans include a commit stamp, verbatim source, exact targets, repository exemplars, ordered edits, hard boundaries, mechanical checks, and perceptual feel checks (PLAN-TEMPLATE.md:3-65).
Execution is a separate mode. execute <plan> dispatches an executor in an isolated worktree, then reviews the resulting diff against the review-animations bar (improve-animations/SKILL.md:88-97). The plan is the interface between high-cost judgment and lower-cost mechanical work.
Two exceptions reveal the real contract
I found two places where a clean summary would be wrong if stated without its exception.
First, the workflow does not always stop for a human choice. In an interactive run, it waits for the user to select which findings become plans. In a non-interactive run, it defaults to the top three to five findings by leverage (improve-animations/SKILL.md:65-78). The architecture has a human checkpoint, but also defines deterministic unattended progress.
Second, “one plan per finding” is a default, not an absolute one-to-one mapping. Two findings may merge when they share every file and the same fix pattern (PLAN-TEMPLATE.md:68-72). The handoff artifact stays self-contained without forcing duplicated plans.
These are not editorial footnotes. They show that the repository treats orchestration policy as part of the skill contract: it specifies both the normal path and the conditions under which the path changes.
What a skill author can reuse
The reusable pattern is not “write a longer expert prompt.” It is to separate kinds of authority:
- Give ambiguous intent a small normalization layer.
- Keep broad principles separate from domain-specific implementation depth.
- Make review a narrow gate with a fixed output schema and an explicit decision.
- Spend the strongest model on reconnaissance, evidence checking, prioritization, and specification.
- Put every detail needed for implementation into a commit-stamped handoff artifact.
- State interaction and merge exceptions inside the workflow instead of leaving orchestration to guesswork.
On the wider map of agent systems, this repository sits closer to a compiler pipeline than a persona prompt: each stage narrows ambiguity and emits a more operational artifact. But that is a source-level reading, not a runtime benchmark. The repository shows how the contracts are designed; it does not prove that weaker executors always preserve the intended motion quality, or that the five-skill split consistently outperforms one well-prompted model. Those questions need empirical evaluation.
What the pinned source does prove is narrower and more useful: motion taste has been decomposed into names, principles, verdicts, plans, and a reviewed execution path. That is the mechanism—not merely a collection of Markdown files.