Agent Skills for Makepad

English | 中文 | 日本語

Agent skills for building cross-platform UI applications with the Makepad framework in Rust.

About Makepad

Makepad is a next-generation UI framework written in Rust that enables building high-performance, cross-platform applications. Key features include:

• Cross-Platform: Single codebase for Desktop (macOS, Windows, Linux), Mobile (Android, iOS), and Web (WebAssembly)
• GPU-Accelerated: Custom shader-based rendering with SDF (Signed Distance Field) drawing
• Live Design: Hot-reloadable live_design! DSL for rapid UI development
• High Performance: Native compilation, no virtual DOM, minimal runtime overhead

About Robius

Project Robius is an open-source initiative to build a full-featured application development framework in Rust. Production applications built with Makepad include:

• Robrix - A Matrix chat client showcasing real-time messaging, E2E encryption, and complex UI patterns
• Moly - An AI model manager demonstrating data-heavy interfaces and async operations

These skills are extracted from patterns used in Robrix and Moly.

Installation

Quick Install (Recommended)

Use the install script for one-command setup:

# Install to current project
curl -fsSL https://raw.githubusercontent.com/ZhangHanDong/makepad-skills/main/install.sh | bash

# Install with hooks enabled
curl -fsSL https://raw.githubusercontent.com/ZhangHanDong/makepad-skills/main/install.sh | bash -s -- --with-hooks

# Install to specific project
curl -fsSL https://raw.githubusercontent.com/ZhangHanDong/makepad-skills/main/install.sh | bash -s -- --target /path/to/project

# Install for Codex (.codex/skills)
curl -fsSL https://raw.githubusercontent.com/ZhangHanDong/makepad-skills/main/install.sh | bash -s -- --agent codex

# Install for Gemini CLI (.gemini/skills)
curl -fsSL https://raw.githubusercontent.com/ZhangHanDong/makepad-skills/main/install.sh | bash -s -- --agent gemini

Gemini CLI note: Skills are experimental. Enable experimental.skills in /settings if needed.

Script features:

• Auto-detects Rust/Makepad projects (checks for Cargo.toml)
• Backs up existing skills before installation
• --with-hooks copies and configures self-evolution hooks (Claude Code only)
• --agent codex|claude-code|gemini chooses Codex, Claude Code, or Gemini CLI (default: claude-code)
• --target allows installing to any project directory
• Colored output with clear progress indicators

Available options:

Option	Description
--target DIR	Install to specific directory (default: current)
--with-hooks	Enable self-evolution hooks (Claude Code only)
--agent AGENT	Set agent: codex, claude-code, or gemini (default: claude-code)
--branch NAME	Use specific branch (default: main)
--help	Show help message

Manual Install

# Clone this repo
git clone https://github.com/ZhangHanDong/makepad-skills.git

# Copy to your project (https://code.claude.com/docs/en/skills)
cp -r makepad-skills/skills your-project/.claude/skills

# Copy to your project for Codex (https://developers.openai.com/codex/skills)
cp -r makepad-skills/skills your-project/.codex/skills

# Copy to your project for Gemini CLI (https://geminicli.com/docs/cli/skills/)
cp -r makepad-skills/skills your-project/.gemini/skills

Your project structure should look like (use .codex or .gemini instead of .claude):

your-project/
├── .claude/
│   └── skills/
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── 00-getting-started/
│       ├── 01-core/
│       ├── 02-components/
│       ├── 03-graphics/
│       │   ├── _base/          # Official skills (atomic)
│       │   └── community/      # Community contributions
│       ├── 04-patterns/
│       │   ├── _base/          # Official patterns (atomic)
│       │   └── community/      # Community contributions
│       ├── 05-deployment/
│       ├── 06-reference/
│       ├── 99-evolution/
│       │   └── templates/      # Contribution templates
│       └── CONTRIBUTING.md
├── src/
└── Cargo.toml

See Claude Code Skills documentation for more details.

Architecture: Atomic Skills for Collaboration

Why Atomic Structure?

v2.1 introduces an atomic skill structure designed for collaborative development:

04-patterns/
├── SKILL.md              # Index file
├── _base/                # Official patterns (numbered, atomic)
│   ├── 01-widget-extension.md
│   ├── 02-modal-overlay.md
│   ├── ...
│   └── 14-callout-tooltip.md
└── community/            # Your contributions
    ├── README.md
    └── {github-handle}-{pattern-name}.md

Benefits:

• No merge conflicts: Your community/ files never conflict with official _base/ updates
• Parallel development: Multiple users can contribute simultaneously
• Clear attribution: Your GitHub handle in filename provides credit
• Progressive disclosure: SKILL.md index → individual pattern details

Self-Evolution: Enriching Skills from Your Development

The self-evolution feature allows you to capture patterns discovered during your development and add them to the skills.

How It Works

1. During Development: You discover a useful pattern, shader, or error solution while building with Makepad

2. Capture the Pattern: Ask Claude to save it:

   User: This tooltip positioning logic is useful. Save it as a community pattern.
   Claude: [Creates community/{handle}-tooltip-positioning.md using template]
   

3. Auto-Detection (with hooks enabled): When you encounter and fix errors, the system can automatically capture solutions to troubleshooting

Enable Self-Evolution Hooks (Optional)

# Copy hooks from 99-evolution to your project
cp -r your-project/.claude/skills/99-evolution/hooks your-project/.claude/skills/hooks

# Make hooks executable
chmod +x your-project/.claude/skills/hooks/*.sh

# Add hooks config to your .claude/settings.json
# See skills/99-evolution/hooks/settings.example.json for the configuration

Manual Pattern Creation

Ask Claude directly:

User: Create a community pattern for the drag-drop reordering I just implemented
Claude: I'll create a pattern using the template...

Claude will:

1. Use the template from 99-evolution/templates/pattern-template.md
2. Create file at 04-patterns/community/{your-handle}-drag-drop-reorder.md
3. Fill in the frontmatter and content

Community Contribution Guide

Contributing Patterns

1. Create your pattern file:

   04-patterns/community/{github-handle}-{pattern-name}.md
   

2. Use the template: Copy from 99-evolution/templates/pattern-template.md

3. Required frontmatter:

   ---
   name: my-pattern-name
   author: your-github-handle
   source: project-where-you-discovered-this
   date: 2024-01-15
   tags: [tag1, tag2, tag3]
   level: beginner|intermediate|advanced
   ---
   

4. Submit PR to the main repository

Contributing Shaders/Effects

1. Create your effect file:

   03-graphics/community/{github-handle}-{effect-name}.md
   

2. Use the template: Copy from 99-evolution/templates/shader-template.md

Contributing Error Solutions

1. Create troubleshooting entry:

   06-reference/troubleshooting/{error-name}.md
   

2. Use the template: Copy from 99-evolution/templates/troubleshooting-template.md

Syncing with Upstream

Keep your local skills updated while preserving your contributions:

# If you've forked the repo
git fetch upstream
git merge upstream/main --no-edit
# Your community/ files won't conflict with _base/ changes

Promotion Path

High-quality community contributions may be promoted to _base/:

• Pattern is widely useful and well-tested
• Documentation is complete
• Community feedback is positive
• Credit preserved via author field

Skills Overview (v2.1 Atomic Structure)

00-getting-started - Project Setup

File	Description	When to Use
init.md	Project scaffolding	"Create a new Makepad app"
project-structure.md	Directory organization	"How should I organize my project?"

01-core - Core Development

File	Description	When to Use
layout.md	Flow, sizing, spacing, alignment	"Arrange UI elements"
widgets.md	Common widgets, custom widgets	"How do I create a button?"
events.md	Event handling, hit testing	"Handle click events"
styling.md	Fonts, text styles, SVG icons	"Change font size", "Add icons"

02-components - Widget Gallery

All built-in widgets reference (from ui_zoo): Buttons, TextInput, Sliders, Checkboxes, Labels, Images, ScrollView, PortalList, PageFlip, and more.

03-graphics - Graphics & Animation (Atomic)

14 individual skills in _base/:

Category	Skills
Shader Basics	01-shader-structure, 02-shader-math
SDF Drawing	03-sdf-shapes, 04-sdf-drawing, 05-progress-track
Animation	`06-animator-