evolution – Agents & Automation skill for AI agents

Makepad Skills Evolution

This skill provides a reviewable workflow for maintaining makepad-skills during development. It does not install automatic evolution by itself.

When to Use

• You are maintaining makepad-skills and want the skill library to improve itself during development.
• You need the workflow for deciding when a new pattern should become a skill update or hook-driven evolution.
• You are working on self-correction, self-validation, or version adaptation for the skill set.

Quick Navigation

| Topic | Description |

|-------|-------------|

| Collaboration Guidelines | Contributing to makepad-skills |

| [Hooks Setup](#hooks-based-auto-triggering) | Auto-trigger evolution with hooks |

| [When to Evolve](#when-to-evolve) | Triggers and classification |

| [Evolution Process](#evolution-process) | Step-by-step guide |

| [Self-Correction](#self-correction) | Auto-fix skill errors |

| [Self-Validation](#self-validation) | Verify skill accuracy |

| [Version Adaptation](#version-adaptation) | Multi-branch support |

---

Only update the explicitly requested skill repository. A discovered lesson alone does not authorize persistent memory edits, installed-skill changes, hooks, commits or remote publication. Keep reusable evidence separate from project secrets and private source.

Hooks-Based Auto-Triggering

Hook files are not bundled in this catalog copy. If hook setup is requested, obtain a reviewed immutable upstream revision, inspect the installer and every hook it fetches, and preserve existing host settings. The following historical installer URL is a source pointer, not permission to run mutable remote code. Install with --with-hooks only after that review:

# 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

This will install hooks to .claude/hooks/ and configure .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"
          }
        ]
      }
    ]
  }
}

What Hooks Do

| Hook | Trigger Event | Action |

|------|---------------|--------|

| makepad-skill-router.sh | UserPromptSubmit | Auto-route to relevant skills |

| pre-tool.sh | Before Bash/Write/Edit | Detect Makepad version from Cargo.toml |

| post-bash.sh | After Bash command fails | Detect Makepad errors, suggest fixes |

| session-end.sh | Session ends | Prompt to capture learnings |

---

Skill Routing and Bundling

The makepad-skill-router.sh hook automatically loads relevant skills based on user queries.

Context Detection

| Context | Trigger Keywords | Skills Loaded |

|---------|------------------|---------------|

| Full App | "build app", "从零", "完整应用" | basics, dsl, layout, widgets, event-action, app-architecture |

| UI Design | "ui design", "界面设计" | dsl, layout, widgets, animation, shaders |

| Widget Creation | "create widget", "创建组件", "自定义组件" | widgets, dsl, layout, animation, shaders, font, event-action |

| Production | "best practice", "robrix pattern", "实际项目" | app-architecture, widget-patterns, state-management, event-action |

Skill Dependencies

When loading certain skills, related skills are auto-loaded:

| Primary Skill | Auto-loads |

|---------------|------------|

| 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 |

Example

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

---

When to Evolve

Trigger skill evolution when any of these occur during development:

| Trigger | Target Skill | Priority |

|---------|--------------|----------|

| New widget pattern discovered | robius-widget-patterns/_base | High |

| Shader technique learned | makepad-shaders | High |

| Compilation error solved | makepad-reference/troubleshooting | High |

| Layout solution found | makepad-reference/adaptive-layout | Medium |

| Build/packaging issue resolved | makepad-deployment | Medium |

| New project structure insight | makepad-basics | Low |

| Core concept clarified | makepad-dsl/makepad-widgets | Low |

---

Evolution Process

Step 1: Identify Knowledge Worth Capturing

Ask yourself:

• Is this a reusable pattern? (not project-specific)
• Did it take significant effort to figure out?
• Would it help other Makepad developers?
• Is it not already documented in makepad-skills?

Step 2: Classify the Knowledge

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/

Step 3: Format the Contribution

For Patterns:

## Pattern N: [Pattern Name]

Brief description of what this pattern solves.

### live_design!

live_design! {

// DSL code

}

### Rust Implementation

// Rust code

For Troubleshooting:

### [Error Type/Message]

**Symptom**: What the developer sees

**Cause**: Why this happens

**Solution**:

// Fixed code

Step 4: Mark Evolution (NOT Version)

Add an evolution marker above new content:

<!-- Evolution: 2024-01-15 | source: my-app | author: @zhangsan -->

Step 5: Submit via 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

---

Self-Correction

When skill content appears to cause errors, confirm the cause and prepare a focused correction within the authorized maintenance scope.

Trigger Conditions

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

Correction Flow

1. Detect - Skill advice led to an error

2. Verify - Confirm the skill content is wrong

3. Correct - Update the authorized source skill with the verified fix; do not silently edit installed or unrelated skills

Correction Marker Format

<!-- Correction: YYYY-MM-DD | was: [old advice] | reason: [why it was wrong] -->

---

Self-Validation

Periodically verify skill content is still accurate.

Validation Checklist

## 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

Validation Prompt

> "Please validate makepad-skills against current Makepad version"

---

Version Adaptation

Provide version-specific guidance for different Makepad branches.

Supported Versions

| Branch | Status | Notes |

|--------|--------|-------|

| main | Verify at the selected revision | Branch name alone does not establish stability |

| dev | Active | Latest features, may break |

| rik | Legacy | Older API style |

Version Detection

Claude should detect Makepad version from:

1. Cargo.toml branch reference:

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

2. **Cargo

… (full content is in the download package)