GPUI Skills

AI agent skills for building desktop applications with GPUI, the UI framework powering the Zed editor.

Installation

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 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
• gpui-component: longbridge/gpui-component

License

MIT