# Skills

Open-source skills for design engineers. Instructions that teach an AI coding agent the interface details that decide whether something feels built or assembled.

They are MIT licensed and published at https://github.com/jaeel29/skills.

## Install

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

Once installed, an agent loads one on its own when a request matches its description. Each can also be invoked directly by name, for example `/animate-icons`.

## Why they exist

Agents write plausible code, and plausible is the problem. An icon that rotates about its bounding box instead of the point the object really turns on. A scroll lock that does nothing on a layout where an inner frame is the scroller. A reply discarded when the connection drops. None of these throw, none fail review, and all of them are visible to the person using the product.

Every rule in these files exists because breaking it caused a real defect, and most carry that defect in the text so a principle can be told from a preference.

## animate-icons

Hover gestures and idle loops for inline SVG icons.

Hover gestures for the small SVG glyphs in a nav, a button or a menu. Covers pivoting, stroke draw-on, timing and the reduced-motion guards.

**Reach for it when:**

- You want a sidebar or menu to feel alive on hover.
- An icon animation jitters, flickers on first hover, or swings like a propeller.
- A glyph moves as one block when only part of it should.

**The idea:** Animate the part, not the whole glyph, and pivot where the object really turns. A key rotates on its bow, not on the icon’s centre.

Source: https://github.com/jaeel29/skills/blob/main/skills/animate-icons/SKILL.md

## build-streaming-ui

The UI for a reply that arrives token by token.

Chat and agent interfaces, and any surface where a result arrives over time. Covers follow-mode scrolling, deltas, stop and reconnects.

**Reach for it when:**

- You are building a chat or agent interface.
- The thread jumps while you are reading it.
- A stopped reply keeps writing, or text duplicates mid-stream.
- A reply is lost when the connection drops.

**The idea:** The reply lives on the server and the connection is one disposable window onto it. Backwards, a dropped connection throws away a reply you already paid for.

Source: https://github.com/jaeel29/skills/blob/main/skills/build-streaming-ui/SKILL.md

## overlay-mechanics

What a modal, drawer or popover does to the page underneath it.

What a modal, drawer or popover does to the page underneath it. Covers stacking, scroll locking and fitting a menu into the space it has.

**Reach for it when:**

- The page scrolls behind an open modal.
- Content jumps sideways when a dialog opens.
- Escape closes the wrong dialog when two are stacked.
- A dropdown is clipped and its first rows cannot be reached.

**The idea:** An overlay mutates the whole page, so that state has to be shared and counted, never stored per component.

Source: https://github.com/jaeel29/skills/blob/main/skills/overlay-mechanics/SKILL.md

## guard-conventions

Turn a rule people keep breaking into a test that breaks instead.

Tests that read your source and fail when a convention is broken again. For defects that pass type-checking, linting and unit tests.

**Reach for it when:**

- The same mistake keeps coming back after it is fixed.
- A convention lives only in a README or in review comments.
- A defect is invisible at runtime, so no ordinary test can fail on it.

**The idea:** Some defects are silent by construction. Scanning the source is the only check that can actually fail on them.

Source: https://github.com/jaeel29/skills/blob/main/skills/guard-conventions/SKILL.md

## build-state-explorer

A dev-only panel that drives the real UI into any state.

A panel that puts your real screens into any state with no backend data. Empty, error, loading, thirty rows, a broken record.

**Reach for it when:**

- Nobody can review an error state without breaking the API on purpose.
- A designer asks what a screen looks like when it is empty and nobody knows.
- A bug only appears with a lot of rows, or with one unusual record.

**The idea:** Drive the real page, not a copy of the component. A copy drifts from the real thing, and the drift is invisible until production.

Source: https://github.com/jaeel29/skills/blob/main/skills/build-state-explorer/SKILL.md

## Where they come from

These were extracted from production work on a design system and dashboard Jaber builds and maintains, then stripped of everything specific to it. The incidents behind the rules are real; the product they happened in is not named, and nothing here depends on it.

## Contact

- Contact form: https://jaberelferkh.com/contact
- Email: contact@jaberelferkh.com