Makepad Skills 技术教程

基于仓库：https://github.com/ZhangHanDong/makepad-skills

本教程面向 Rust / Makepad 开发者，以及希望将 AI 编码助手（Claude / Codex / Gemini 等） 深度融入 GUI 开发流程的工程师。

目标是让你不仅“会用” Makepad Skills，而是理解其设计哲学，并能在真实项目中复用、扩展、进化这些 skills。

1. Makepad Skills 是什么？

Makepad Skills 不是一个传统意义上的代码库，而是一套：

• 面向 AI 代码助手 的「结构化技能知识库」
• 专门用于 Makepad UI 框架 的工程经验抽象
• 可被 AI 在不同开发阶段（初始化 / 编码 / 重构 / 调试）自动调用

可以把它理解为：

👉 “把一个资深 Makepad 工程师的经验，拆解成 AI 能理解、可复用的模块。”

2. 整体架构与设计理念

2.1 Skills 的核心思想

Makepad Skills 采用 模块化技能分层 设计：

• 每个目录 = 一个「技能领域」
• 每个文件 = 一个「可被 AI 检索和执行的知识单元」
• 技能强调 模式（Pattern），而不是零散 API

这非常适合 LLM 的工作方式：

• 检索（Retrieval）
• 组合（Composition）
• 生成（Generation）

2.2 目录结构解读

makepad-skills/
├── 00-getting-started/   # 项目初始化 & 基础认知
├── 01-core/              # Makepad 核心概念
├── 02-components/        # UI 组件技能
├── 03-graphics/          # 绘制 / 动效 / GPU
├── 04-patterns/          # 工程模式（非常重要）
├── 05-deployment/        # 构建、发布、打包
└── 06-reference/         # 速查 & 常见错误

你可以把它理解为：一个从“新手 → 专家”的技能成长路径。

3. 快速上手：让 AI 学会 Makepad

3.1 安装 Skills 到 AI 工具

以 Claude Code 为例：

mkdir -p .claude/skills
cd .claude/skills
git clone https://github.com/ZhangHanDong/makepad-skills

对于 Codex / Gemini，只需替换目录：

• .codex/skills
• .gemini/skills

3.2 一个最小工作流示例

你可以直接对 AI 说：

“使用 Makepad Skills，帮我创建一个带侧边栏的桌面应用。”

AI 会自动：

1. 检索 00-getting-started
2. 引用 01-core 中的 App / Window 模式
3. 从 02-components 选择合适组件
4. 应用 04-patterns 中的布局结构

这就是 Skills 的价值所在：

AI 不再胡写 UI，而是在“遵循 Makepad 最佳实践”。

4. 核心技能详解

4.1 Core：理解 Makepad 的运行模型

在 01-core 中，你会看到围绕以下主题的技能：

• App 生命周期
• Event / Signal 机制
• Live Design（Makepad 的核心特色）

重点理解：

Makepad 并不是 React / Flutter 的思维模型，而是： 事件驱动 + GPU 即时绘制 + Live DSL

Skills 在这里的作用是：

• 告诉 AI「什么是对的写法」
• 避免生成不符合 Makepad 哲学的代码

4.2 Components：可复用 UI 能力

02-components 中的技能，通常包含：

• 组件结构说明
• 推荐的 state 管理方式
• 常见错误示例（非常重要）

例如：

• Button / Label / ScrollView
• 自定义 Widget

教程建议用法：

当你需要新组件，不要直接写代码，先让 AI： “基于 Makepad Skills 生成一个组件骨架”。

4.3 Graphics：Makepad 的杀手锏

Makepad 的强项在于：

• GPU Path 绘制
• Shader + UI 融合
• 高性能动画

03-graphics 的 skills 非常关键，因为：

• 这是 Makepad 与传统 UI 框架差异最大的部分
• 人类写起来容易踩坑，AI 更容易写错

Skills 的存在能极大降低试错成本。

5. Patterns：真正的工程价值

如果只能选一个目录深入学习：

一定是 04-patterns。

这里沉淀的是：

• 从真实项目（如 Robrix / Moly）抽取的经验
• 可长期复用的 UI / 状态 / 模块化结构

5.1 为什么 Patterns 对 AI 特别重要？

因为 AI：

• 擅长模仿结构
• 不擅长自己设计架构

Patterns 本质上是在告诉 AI：

“在 Makepad 中，复杂应用应该长这样。”

5.2 推荐使用方式

• 先选 Pattern，再写功能
• 把 Pattern 当作“项目骨架”
• 在此基础上让 AI 填充细节

这会显著提升生成代码的稳定性。

6. Self‑Evolution：让 Skills 越用越强

Makepad Skills 最有前瞻性的设计是：

允许从你的项目中反向提取新技能。

推荐流程：

1. 在真实项目中完成一个复杂功能
2. 总结其通用结构 / 约束 / 反模式
3. 抽象为一个新的 skill
4. 加入 skills 库

这样做的结果是：

• AI 会“记住”你的工程经验
• 后续项目质量呈指数级提升

7. 常见误区与最佳实践

❌ 不要把 Skills 当文档看

它的目标不是给人读，而是给 AI 检索 + 组合。

✅ 要用自然语言驱动 AI

例如：

“使用 Makepad Skills 的 patterns，设计一个支持多窗口的桌面应用。”

8. 总结

Makepad Skills = UI 工程经验 × AI 编码能力。

它适合：

• 想认真做 Makepad 项目的人
• 希望 AI 写的代码「像人一样靠谱」
• 打算长期沉淀 UI 工程能力的团队