# GPUI Skills

AI agent skills for building desktop applications with [GPUI](https://github.com/zed-industries/zed/tree/main/crates/gpui), the UI framework powering the Zed editor.

## Installation

```bash
npx skills add AprilNEA/gpui-skills
```

## Available Skills

### gpui

GPUI framework best practices covering core concepts, rendering, state management, and more.

**Use when:**
- Writing new GPUI views or components
- Implementing state management with Entity
- Handling events and keyboard shortcuts
- Working with async tasks
- Debugging ownership or lifetime issues

**Categories (33 rules):**

| Category | Impact | Description |
|----------|--------|-------------|
| Core Concepts | CRITICAL | Ownership model, Entity operations, Context types |
| Rendering | CRITICAL | Render vs RenderOnce, element composition |
| State Management | HIGH | notify(), observe, subscribe patterns |
| Event Handling | HIGH | Actions, focus management, listeners |
| Async & Concurrency | MEDIUM-HIGH | Task lifecycle, debounce, background work |
| Styling | MEDIUM | Flexbox, theme colors, elevation |
| Components | MEDIUM | Stateless patterns, traits, dialogs |
| Anti-patterns | CRITICAL | Common mistakes to avoid |
| Testing | HIGH | Test framework and patterns |

### gpui-component

Best practices for [gpui-component](https://github.com/longbridge/gpui-component) library.

**Use when:**
- Building reusable UI components
- Implementing theme system
- Creating dialogs, forms, lists
- Following Longbridge component patterns

**Categories:**
- Component Architecture (RenderOnce, traits)
- Theme System (colors, variants)
- Dialogs & Popover patterns
- Form components (Input, Checkbox, etc.)
- Animation patterns

## Usage Examples

Ask your AI coding assistant:

```
Help me create a GPUI view with state management
```

```
Why is my Task being cancelled? (GPUI async issue)
```

```
How do I implement keyboard shortcuts in GPUI?
```

```
Create a Button component following gpui-component patterns
```

## Project Structure

```
gpui-skills/
├── gpui/                    # GPUI framework skill
│   ├── SKILL.md
│   └── rules/
│       ├── core-*.md        # 4 rules
│       ├── render-*.md      # 4 rules
│       ├── state-*.md       # 1 rule
│       ├── event-*.md       # 3 rules
│       ├── async-*.md       # 4 rules
│       ├── style-*.md       # 3 rules
│       ├── comp-*.md        # 4 rules
│       ├── anti-*.md        # 6 rules
│       └── test-*.md        # 4 rules
└── gpui-component/          # gpui-component skill
    ├── SKILL.md
    └── rules/
```

## Key Concepts Covered

### GPUI Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Application (App)                     │
│              (Single owner of all Entities)              │
└─────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
    Entity<A>           Entity<B>           Global<C>
        │                   │
    read/update         observe/subscribe
        │
    ┌─────────────────────────────────────────────────┐
    │           UI Rendering (Render trait)           │
    │      fn render(&mut self, ...) -> impl IntoElement
    └─────────────────────────────────────────────────┘
```

### Critical Anti-patterns

- **Never** silently discard errors with `let _ =`
- **Never** drop Task without `.detach()` or storing
- **Always** call `cx.notify()` after state changes
- **Avoid** `unwrap()` in production code

## Sources

- **GPUI**: [zed-industries/zed/crates/gpui](https://github.com/zed-industries/zed/tree/main/crates/gpui)
- **gpui-component**: [longbridge/gpui-component](https://github.com/longbridge/gpui-component)

## License

MIT