evolution

Makepad Skills Evolution

此技能提供了一套可审查的工作流，用于在开发过程中维护 makepad-skills。它本身不会安装自动演进机制。

使用时机

• 你正在维护 makepad-skills，希望技能库在开发过程中不断完善。
• 你需要一套工作流，用于判断何时应将新模式更新为技能，或通过钩子驱动演进。
• 你正在为技能集实现自我纠正、自我验证或版本适配。

快速导航

主题	描述
协作指南	为 makepad-skills 做贡献
钩子设置	使用钩子自动触发演进
何时演进	触发条件和分类
演进流程	分步指南
自我纠正	自动修复技能错误
自我验证	验证技能准确性
版本适配	多分支支持

---

仅更新明确要求修改的技能仓库。仅发现一条经验，并不意味着可以修改持久记忆、已安装的技能、钩子、提交或发布到远程。将可复用的证据与项目机密和私有源代码分开保存。

基于钩子的自动触发

此目录副本不包含钩子文件。如果需要设置钩子，请获取经过审查的不可变上游版本，检查安装程序及其获取的每个钩子，并保留现有主机设置。以下历史安装程序 URL 仅作为来源指针，不代表允许运行可变的远程代码。完成审查后再使用 --with-hooks 安装：

# Install makepad-skills with hooks enabled
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
curl -fsSLo "$tmpdir/makepad-skills-install.sh" https://raw.githubusercontent.com/ZhangHanDong/makepad-skills/main/install.sh
cat "$tmpdir/makepad-skills-install.sh"  # review the full installer before executing
# Execute only the reviewed revision after explicit hook-install authorization:
# bash "$tmpdir/makepad-skills-install.sh" --with-hooks

这将在 .claude/hooks/ 中安装钩子，并配置 .claude/settings.json：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/makepad-skill-router.sh"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/pre-tool.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/post-bash.sh"
          }
        ]
      }
    ]
  }
}

钩子的作用

钩子	触发事件	操作
makepad-skill-router.sh	UserPromptSubmit	自动路由到相关技能
pre-tool.sh	Bash/Write/Edit 执行前	从 Cargo.toml 检测 Makepad 版本
post-bash.sh	Bash 命令失败后	检测 Makepad 错误并建议修复方法
session-end.sh	会话结束时	提示记录经验

---

技能路由与打包

makepad-skill-router.sh 钩子会根据用户查询自动加载相关技能。

上下文检测

上下文	触发关键词	加载的技能
完整应用	"build app", "从零", "完整应用"	basics, dsl, layout, widgets, event-action, app-architecture
UI 设计	"ui design", "界面设计"	dsl, layout, widgets, animation, shaders
创建组件	"create widget", "创建组件", "自定义组件"	widgets, dsl, layout, animation, shaders, font, event-action
生产环境	"best practice", "robrix pattern", "实际项目"	app-architecture, widget-patterns, state-management, event-action

技能依赖关系

加载某些技能时，也会自动加载相关技能：

主要技能	自动加载
robius-app-architecture	makepad-basics, makepad-event-action
robius-widget-patterns	makepad-widgets, makepad-layout
makepad-widgets	makepad-layout, makepad-dsl
makepad-animation	makepad-shaders
makepad-shaders	makepad-widgets
makepad-font	makepad-widgets
robius-event-action	makepad-event-action

示例

User: "我想从零开发一个 Makepad 应用"

[makepad-skills] Detected Makepad/Robius query
[makepad-skills] App development context detected - loading skill bundle
[makepad-skills] Routing to: makepad-basics makepad-dsl makepad-event-action
                            makepad-layout makepad-widgets robius-app-architecture

---

何时进行演进

开发过程中出现以下任一情况时，触发技能演进：

触发条件	目标技能	优先级
发现新的 widget 模式	robius-widget-patterns/_base	高
学会着色器技术	makepad-shaders	高
解决编译错误	makepad-reference/troubleshooting	高
找到布局解决方案	makepad-reference/adaptive-layout	中
解决构建／打包问题	makepad-deployment	中
获得新的项目结构见解	makepad-basics	低
弄清核心概念	makepad-dsl/makepad-widgets	低

---

演进流程

第 1 步：识别值得记录的知识

问问自己：

• 这是可复用的模式吗？（而非项目特有）
• 为弄清楚它是否花费了大量精力？
• 它能帮助其他 Makepad 开发者吗？
• makepad-skills 中是否尚未记录？

第 2 步：对知识分类

Widget/Component Pattern     → robius-widget-patterns/_base/
Shader/Visual Effect         → makepad-shaders/
Error/Debug Solution         → makepad-reference/troubleshooting.md
Layout/Responsive Design     → makepad-reference/adaptive-layout.md
Build/Deploy Issue           → makepad-deployment/SKILL.md
Project Structure            → makepad-basics/
Core Concept/API             → makepad-dsl/ or makepad-widgets/

第 3 步：整理贡献内容

对于模式：

## Pattern N: [Pattern Name]

Brief description of what this pattern solves.

### live_design!
```rust
live_design! {
    // DSL code
}

Rust 实现

// Rust code

**For Troubleshooting**:
```markdown
### [Error Type/Message]

**Symptom**: What the developer sees

**Cause**: Why this happens

**Solution**:
```rust
// Fixed code

### Step 4: Mark Evolution (NOT Version)

Add an evolution marker above new content:

```markdown

第 5 步：通过 Git 提交

# Create branch for your contribution
git checkout -b evolution/add-loading-pattern

# Commit your changes
git add robius-widget-patterns/_base/my-pattern.md
git commit -m "evolution: add loading state pattern from my-app"

# Push and create PR
git push origin evolution/add-loading-pattern

---

自我纠正

当技能内容似乎导致错误时，确认原因，并在授权维护范围内准备有针对性的修正。

触发条件

User follows skill advice → Code fails to compile/run → Claude identifies skill was wrong
                                                      ↓
                                         Prepare evidence-backed correction for review

修正流程

1. 检测 - 技能建议导致了错误
2. 验证 - 确认技能内容有误
3. 修正 - 使用经验证的修复更新获授权的源技能；不要擅自修改已安装或无关的技能

修正标记格式

---

自我验证

定期验证技能内容是否仍然准确。

验证清单

## Validation Report

### Code Examples
- [ ] All `live_design!` examples parse correctly
- [ ] All Rust code compiles
- [ ] All patterns work as documented

### API Accuracy
- [ ] Widget names exist in makepad-widgets
- [ ] Method signatures are correct
- [ ] Event types are accurate

验证提示词

“请根据当前 Makepad 版本验证 makepad-skills”

---

版本适配

针对不同的 Makepad 分支提供特定版本的指导。

支持的版本

分支	状态	备注
main	在选定的修订版本上验证	仅凭分支名称无法确定稳定性
dev	活跃	包含最新功能，但可能会有破坏性变更
rik	旧版	使用较旧的 API 风格

版本检测

Claude 应通过以下方式检测 Makepad 版本：

1. Cargo.toml 分支引用：

   makepad-widgets = { git = "...", branch = "dev" }
   

2. Cargo.lock 内容

3. 不明确时询问用户

---

个性化

根据项目的编码风格调整技能建议。

风格检测

Claude 分析当前项目以检测：

方面	检测方法	调整方式
命名约定	扫描现有 widget	匹配 snake_case 或 camelCase
代码组织	检查模块结构	建议匹配的模式
注释风格	阅读现有注释	匹配文档风格
widget 复杂度	统计每个 widget 的行数	建议合适的模式

---

质量指南

应添加

• 通用、可复用的模式
• 有明确解决方案的常见错误
• 经过充分测试的着色器效果
• 特定平台的注意事项
• 性能优化

不应添加

• 项目特有的代码
• 未经验证的解决方案
• 重复内容
• 不完整的示例
• 没有理由说明的个人偏好

---

技能文件位置

skills/
├── # === Core Skills (16) ===
├── makepad-basics/        ← Getting started, app structure
├── makepad-dsl/           ← DSL syntax, inheritance
├── makepad-layout/        ← Layout, sizing, alignment
├── makepad-widgets/       ← Widget components
├── makepad-event-action/  ← Event handling
├── makepad-animation/     ← Animation, states
├── makepad-shaders/       ← Shader basics
├── makepad-platform/      ← Platform support
├── makepad-font/          ← Font, typography
├── makepad-splash/        ← Splash scripting
├── robius-app-architecture/   ← App architecture patterns
├── robius-widget-patterns/    ← Widget reuse patterns
├── robius-event-action/       ← Custom actions
├── robius-state-management/   ← State persistence
├── robius-matrix-integration/ ← Matrix SDK
├── molykit/               ← AI chat toolkit
│
├── # === Extended Skills (3) ===
├── makepad-shaders/ ← Advanced shaders, SDF
│   ├── _base/             ← Official patterns
│   └── community/         ← Community contributions
├── makepad-deployment/    ← Build & packaging
├── makepad-reference/     ← Troubleshooting, code quality
│
├── # Note: Production patterns integrated into robius-* skills:
├── # - Widget patterns → robius-widget-patterns/_base/
├── # - State patterns → robius-state-management/_base/
├── # - Async patterns → robius-app-architecture/_base/
│
└── evolution/             ← Self-evolution system
    ├── hooks/             ← Auto-trigger hooks
    ├── references/        ← Detailed guides
    └── templates/         ← Contribution templates

---

自动演进提示词

使用以下提示词触发自我演进：

解决问题后

“这个解决方案应添加到 makepad-skills，以供日后参考。”

创建 widget 后

“这个 widget 模式可以复用。我来把它添加到 makepad-patterns。”

调试后

“应将此错误及其修复记录到 makepad-troubleshooting。”

完成功能后

“回顾我学到的内容，并在适用时更新 makepad-skills。”

---

持续改进清单

每次 Makepad 开发会话结束后，请考虑：

• 我是否发现了新的组件组合模式？
• 我是否解决了棘手的着色器问题？
• 我是否遇到并修复了令人困惑的错误？
• 我是否找到了更好的布局结构方式？
• 我是否学到了有关打包/部署的知识？
• 这些内容对其他 Makepad 开发者有帮助吗？

如果任一项的答案是肯定的，请提出有证据支持的更新；仅在用户要求的维护范围内执行。

参考资料

• makepad-skills 仓库
• Makepad 文档
• Project Robius

限制

• 仅当任务明显符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。