Makepad Skills Evolution

This skill enables makepad-skills to self-improve continuously during development.

Quick Navigation

Hooks-Based Auto-Triggering

For reliable automatic triggering, use Claude Code hooks. Copy the hooks to your project:

# Copy hooks to your project
cp -r .claude/skills/99-evolution/hooks your-project/.claude/skills/hooks
chmod +x your-project/.claude/skills/hooks/*.sh

Then merge hooks/settings.example.json into your .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/skills/hooks/pre-tool.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/skills/hooks/post-bash.sh \"$TOOL_OUTPUT\" \"$EXIT_CODE\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/skills/hooks/session-end.sh"
          }
        ]
      }
    ]
  }
}

What Hooks Do

When to Evolve

Trigger skill evolution when any of these occur during development:

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     → 04-patterns/
Shader/Visual Effect         → 03-graphics/
Error/Debug Solution         → 06-reference/troubleshooting.md
Layout/Responsive Design     → 06-reference/adaptive-layout.md
Build/Deploy Issue           → 05-deployment/SKILL.md
Project Structure            → 00-getting-started/
Core Concept/API             → 01-core/

Step 3: Format the Contribution

For Patterns:

## Pattern N: [Pattern Name]

Brief description of what this pattern solves.

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

Rust Implementation

// 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
<!-- 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 04-patterns/widget-patterns.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 causes errors, automatically correct it.

Trigger Conditions

User follows skill advice → Code fails to compile/run → Claude identifies skill was wrong
                                                      ↓
                                         AUTO: Correct skill immediately

Correction Flow

1. Detect – Skill advice led to an error
2. Verify – Confirm the skill content is wrong
3. Correct – Update the skill file with fix

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

Version Detection

Claude should detect Makepad version from:

1. Cargo.toml branch reference:

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

2. Cargo.lock content

3. Ask user if unclear

Personalization

Adapt skill suggestions to project’s coding style.

Style Detection

Claude analyzes the current project to detect:

Quality Guidelines

DO Add

• Generic, reusable patterns
• Common errors with clear solutions
• Well-tested shader effects
• Platform-specific gotchas
• Performance optimizations

DON’T Add

• Project-specific code
• Unverified solutions
• Duplicate content
• Incomplete examples
• Personal preferences without rationale

Skill File Locations (New Structure)

skills/
├── 00-getting-started/    ← Project setup
├── 01-core/               ← Layout, widgets, events, styling
├── 02-components/         ← Widget gallery
├── 03-graphics/           ← Shaders, SDF, animations
├── 04-patterns/           ← Production patterns
├── 05-deployment/         ← Build & packaging
├── 06-reference/          ← Troubleshooting, code quality
└── 99-evolution/          ← This file + hooks
    └── hooks/             ← Auto-trigger hooks

Auto-Evolution Prompts

Use these prompts to trigger self-evolution:

After Solving a Problem

“This solution should be added to makepad-skills for future reference.”

After Creating a Widget

“This widget pattern is reusable. Let me add it to makepad-patterns.”

After Debugging

“This error and its fix should be documented in makepad-troubleshooting.”

After Completing a Feature

“Review what I learned and update makepad-skills if applicable.”

Continuous Improvement Checklist

After each Makepad development session, consider:

• Did I discover a new widget composition pattern?
• Did I solve a tricky shader problem?
• Did I encounter and fix a confusing error?
• Did I find a better way to structure layouts?
• Did I learn something about packaging/deployment?
• Would any of this help other Makepad developers?

If yes to any, evolve the appropriate skill!

References

• makepad-skills repository
• Makepad documentation
• Project Robius