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

Plugin Marketplace (Recommended)

Install via Claude Code's plugin marketplace:

# Step 1: Add marketplace
/plugin marketplace add ZhangHanDong/makepad-skills

# Step 2: Install the plugin (includes all 20 skills)
/plugin install makepad-skills@makepad-skills-marketplace

Using Plugin Skills:

Plugin skills are accessed via namespace format (they won't appear in /skills list, but can be loaded):

# Load specific skills by namespace
/makepad-skills:makepad-widgets
/makepad-skills:makepad-layout
/makepad-skills:robius-widget-patterns

# Or just ask questions - hooks will auto-route to relevant skills
"How do I create a Makepad button?"
"makepad 布局怎么居中？"

Manage installed plugins:

/plugin                  # List installed plugins
/plugin uninstall makepad-skills@makepad-skills-marketplace  # Uninstall

Shell Script Install

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
│       │
│       ├── # === Core Skills (16) ===
│       ├── makepad-basics/
│       ├── makepad-dsl/
│       ├── makepad-layout/
│       ├── makepad-widgets/
│       ├── makepad-event-action/
│       ├── makepad-animation/
│       ├── makepad-shaders/
│       ├── makepad-platform/
│       ├── makepad-font/
│       ├── makepad-splash/
│       ├── robius-app-architecture/
│       ├── robius-widget-patterns/
│       ├── robius-event-action/
│       ├── robius-state-management/
│       ├── robius-matrix-integration/
│       ├── molykit/
│       │
│       ├── # === Extended Skills (3) ===
│       ├── makepad-deployment/
│       ├── makepad-reference/
│       │
│       ├── evolution/          # Self-evolution system
│       │   └── templates/      # Contribution templates
│       └── CONTRIBUTING.md
├── src/
└── Cargo.toml

See Claude Code Skills documentation for more details.

GitHub Actions Packaging

Use the Makepad Packaging Action to build and release Makepad apps in CI. It wraps cargo-packager (desktop) and cargo-makepad (mobile), and can upload artifacts to GitHub Releases.

Marketplace: makepad-packaging-action

- uses: Project-Robius-China/makepad-packaging-action@v1
  with:
    args: --target x86_64-unknown-linux-gnu --release

Notes:

• Desktop packages must run on matching OS runners.
• iOS builds require macOS runners.

Architecture: Atomic Skills for Collaboration

Why Atomic Structure?

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

robius-widget-patterns/
├── SKILL.md              # Index file
├── _base/                # Official patterns (numbered, atomic)
│   ├── 01-widget-extension.md
│   ├── 02-modal-overlay.md
│   ├── ...
│   └── 18-drag-drop-reorder.md
└── community/            # Your contributions
    └── {descriptive-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 evolution to your project
cp -r your-project/.claude/skills/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/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 evolution/templates/pattern-template.md
2. Create file at robius-widget-patterns/community/{descriptive-pattern-name}.md
3. Fill in the frontmatter and content

Community Contribution Guide

Contributing Patterns

1. Create your pattern file in the appropriate robius-* skill's community directory:

   • Widget patterns → robius-widget-patterns/community/
   • State patterns → robius-state-management/community/
   • Async patterns → robius-app-architecture/community/

2. Use the template: Copy from 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:

   makepad-shaders/community/{github-handle}-{effect-name}.md
   

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

Contributing Error Solutions

1. Create troubleshooting entry:

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

2. Use the template: Copy from 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 (v3.0 Flat Structure)

Core Skills (16)

Makepad Core (10 Skills)

Skill	Description	When to Use
makepad-basics	App structure, live_design!, app_main!	"Create a new Makepad app"
makepad-dsl	DSL syntax, inheritance, prototypes	"How to define widgets in DSL"
makepad-layout	Flow, sizing, spacing, alignment	"Center a widget", "Arrange elements"
makepad-widgets	Common widgets, custom widgets	"Create a button", "Build a form"
makepad-event-action	Event handling, actions	"Handle click events"
makepad-animation	Animator, states, transitions	"Add hover animation"
makepad-shaders	Shaders, SDF, gradients, visual effects	"Custom visual effects"
makepad-platform	Platform support	"Build for Android/iOS"
makepad-font	Font, text, typography	"Change font, text styling"
makepad-splash	Splash scripting language	"Dynamic UI scripting"

Robius Patterns (5 Skills)

Skill	Description	When to Use
robius-app-architecture	Tokio, async/sync patterns	"Structure an async app"
robius-widget-patterns	Reusable widgets, apply_over	"Create reusable components"
robius-event-action	Custom actions, MatchEvent	"Custom event handling"
robius-state-management	AppState, persistence	"Save/load app state"
robius-matrix-integration	Matrix SDK integration	"Chat client features"

MolyKit (1 Skill)

Skill	Description	When to Use
molykit	AI chat, SSE streaming, BotClient	"AI chat integration"

Extended Skills (3)

Note: Production patterns are now integrated into robius-* skills:

• Widget patterns (11) → robius-widget-patterns/_base/
• State patterns (5) → robius-state-management/_base/
• Async patterns (3) → robius-app-architecture/_base/

makepad-deployment - Build & Package

Build for desktop (Linux, Windows, macOS), mobile (Android, iOS), and web (WebAssembly).

makepad-reference - Reference Materials

File	Description	When to Use
troubleshooting.md	Common errors and fixes	"Apply error: no matching field"
code-quality.md	Makepad-aware refactoring	"Simplify this code"
adaptive-layout.md	Desktop/mobile responsive	"Support both desktop and mobile"

evolution - Self-Improvement

Component	Description
templates/	Pattern, shader, and troubleshooting templates
hooks/	Auto-detection and validation hooks
references/	Collaboration guidelines

Usage Examples

Create a New Project

User: Create a new Makepad app called "my-app" with a counter button
Claude: [Uses makepad-basics for scaffolding, makepad-widgets for button/counter]

Add a Tooltip

User: Add a tooltip that shows user info on hover
Claude: [Uses robius-widget-patterns/_base/14-callout-tooltip.md for complete implementation]

Save a Custom Pattern

User: Save this infinite scroll implementation as a community pattern
Claude: [Creates robius-widget-patterns/community/infinite-scroll.md]

Fix Compilation Error

User: Getting "no matching field: font" error
Claude: [Uses makepad-reference/troubleshooting.md to identify correct text_style syntax]

What You Can Build

With these skills, Claude can help you:

• Initialize new Makepad projects with proper structure
• Create custom widgets with live_design! DSL
• Handle events and user interactions
• Write GPU shaders for visual effects
• Implement smooth animations
• Manage application state with async/tokio
• Build responsive desktop/mobile layouts
• Package apps for all platforms
• Capture and share patterns you discover during development

Projects Built with These Skills

Real-world projects created using makepad-skills and Claude Code:

Project	Description	Time
makepad-skills-demo	Currency converter app demo	~20 min
makepad-component	Reusable Makepad component library	-

makepad-skills-demo Screenshot

makepad-component Screenshots

Resources

• Makepad Repository
• Makepad Examples
• Project Robius
• Robrix
• Moly

License

MIT