1. [ ] Detect Makepad version from Cargo.toml
       → Set internal context: "Using Makepad {branch}"

2. [ ] Scan project style (if not done before)
       → Note naming conventions, module structure

3. [ ] Apply version-specific and personalized suggestions
       → All subsequent advice adapted automatically

Widget/Component Pattern     → makepad-patterns/SKILL.md
Shader/Visual Effect         → makepad-shaders/SKILL.md
Error/Debug Solution         → makepad-troubleshooting/SKILL.md
Layout/Responsive Design     → makepad-adaptive-layout/SKILL.md
Build/Deploy Issue           → makepad-packaging/SKILL.md
Project Structure            → makepad-init/SKILL.md
Core Concept/API             → makepad-fundamentals/SKILL.md

## Pattern N: [Pattern Name]

Brief description of what this pattern solves.

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

### Rust Implementation
\```rust
// Rust code
\```

### Usage
\```rust
// How to use
\```

### [Error Type/Message]

**Symptom**: What the developer sees

**Cause**: Why this happens

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

### [Effect Name]

\```rust
draw_bg: {
    // shader code with comments
    fn pixel(self) -> vec4 {
        // implementation
    }
}
\```

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

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

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

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

Developer A: evolves locally → version 1.4.1
Developer B: evolves locally → version 1.4.1  ← Conflict!

┌─────────────────────────────────────────────────────────┐
│  Local Development (Each Developer)                     │
│  - Add content only                                     │
│  - Add evolution markers (date, source, author)         │
│  - Do NOT change version number                         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Git PR / Merge                                         │
│  - Content reviewed and merged                          │
│  - Conflicts resolved at content level                  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Release (Maintainer / CI)                              │
│  - Bump version based on accumulated changes            │
│  - Tag release                                          │
│  - Publish                                              │
└─────────────────────────────────────────────────────────┘

<!-- Evolution: YYYY-MM-DD | source: project-name | author: @github-handle -->

## Pattern 15: Loading State Button

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

A button that shows loading spinner when processing...

# 1. Sync with upstream before evolving
git fetch upstream
git rebase upstream/main

# 2. Create evolution branch
git checkout -b evolution/descriptive-name

# 3. Make your changes (content only, no version bump)
# ... edit SKILL.md files ...

# 4. Commit with conventional prefix
git commit -m "evolution(patterns): add loading state button"
git commit -m "evolution(troubleshooting): fix for timer not firing"
git commit -m "evolution(shaders): add glassmorphism effect"

# 5. Push and create PR
git push origin evolution/descriptive-name
gh pr create --title "evolution: add loading patterns from moly"

<<<<<<< HEAD
## Pattern 15: Loading Button
<!-- Evolution: 2024-01-15 | source: moly | author: @zhangsan -->
=======
## Pattern 15: Expandable Card
<!-- Evolution: 2024-01-15 | source: robrix | author: @lisi -->
>>>>>>> evolution/add-card-pattern

## Pattern 15: Loading Button
<!-- Evolution: 2024-01-15 | source: moly | author: @zhangsan -->
...

## Pattern 16: Expandable Card
<!-- Evolution: 2024-01-15 | source: robrix | author: @lisi -->
...

# Check what's new since last release
git log v1.4.0..HEAD --oneline

# Determine version bump
# - Only troubleshooting fixes → patch (1.4.1)
# - New patterns/shaders → minor (1.5.0)
# - New skill files → major (2.0.0)

# Update version in plugin.json
# Tag and release
git tag v1.5.0
git push --tags

name: Auto Version on Release
on:
  push:
    branches: [main]
    paths:
      - '*/SKILL.md'

jobs:
  version:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Bump version
        run: |
          # Count evolution markers since last tag
          # Auto-bump patch version
          # Update plugin.json

I discovered a useful pattern during development:
[Describe the pattern]

Let me add it to makepad-skills:
1. Read makepad-patterns/SKILL.md
2. Add Pattern N: [Name] following existing format
3. Bump patch version

I solved an error that others might encounter:
[Describe the error and solution]

Let me add it to makepad-skills:
1. Read makepad-troubleshooting/SKILL.md
2. Add under appropriate section
3. Bump patch version

I created a useful shader effect:
[Describe the effect]

Let me add it to makepad-skills:
1. Read makepad-shaders/SKILL.md
2. Add under "Advanced Effects" or appropriate section
3. Bump patch version

THIS_SKILL_PATH = path of this SKILL.md file you just read
SKILLS_ROOT = dirname(dirname(THIS_SKILL_PATH))

Example:
  THIS_SKILL_PATH = /home/user/project/.claude/skills/makepad-skills/makepad-evolution/SKILL.md
  SKILLS_ROOT     = /home/user/project/.claude/skills/makepad-skills/

1. Claude reads this skill from:
   /Users/someone/myapp/.claude/skills/makepad-skills/makepad-evolution/SKILL.md

2. Claude calculates skills root:
   /Users/someone/myapp/.claude/skills/makepad-skills/

3. Claude wants to add a pattern, constructs path:
   /Users/someone/myapp/.claude/skills/makepad-skills/makepad-patterns/SKILL.md

4. Claude uses Read tool to read that file

5. Claude uses Edit tool to add the new pattern

6. File is automatically saved ✓

<makepad-skills-root>/
├── .claude-plugin/
│   └── plugin.json           ← Version (maintainer only)
├── makepad-init/
│   └── SKILL.md              ← Project templates
├── makepad-fundamentals/
│   └── SKILL.md              ← Core concepts, widgets, events
├── makepad-shaders/
│   └── SKILL.md              ← SDF, effects, animations
├── makepad-patterns/
│   └── SKILL.md              ← Production patterns
├── makepad-adaptive-layout/
│   └── SKILL.md              ← Responsive layouts
├── makepad-packaging/
│   └── SKILL.md              ← Build & deployment
├── makepad-troubleshooting/
│   └── SKILL.md              ← Errors & debugging
└── makepad-evolution/
    └── SKILL.md              ← This file

# In your project
ln -s /path/to/makepad-skills .claude/skills/makepad-skills

# Now evolutions save directly to source

<!-- Evolution: YYYY-MM-DD -->
<!-- Source: [project name or context] -->
<!-- Added: [brief description] -->

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

┌─────────────────────────────────────────────────────────┐
│  1. DETECT: Skill advice led to an error                │
│     - Compilation error from suggested code             │
│     - Runtime error from recommended pattern            │
│     - API mismatch (method doesn't exist)               │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  2. VERIFY: Confirm the skill content is wrong          │
│     - Check Makepad source code                         │
│     - Test the correct approach                         │
│     - Ensure fix works                                  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  3. CORRECT: Update the skill file                      │
│     - Fix the incorrect code/advice                     │
│     - Add correction marker                             │
│     - Optionally add to troubleshooting                 │
└─────────────────────────────────────────────────────────┘

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

1. Claude detects: "method `start` not found on Timer"

2. Claude investigates Makepad source, finds correct API:
   timer = cx.start_interval(0.1)

3. Claude updates makepad-fundamentals/SKILL.md:

### Timer Setup

<!-- Correction: 2024-01-20 | was: timer.start(cx, 0.1) | reason: API changed in dev branch -->

```rust
// Correct way to start a timer
fn setup_timer(&mut self, cx: &mut Cx) {
    self.timer = cx.start_interval(0.1);  // Returns Timer directly
}

### "method `start` not found on Timer"

**Symptom**: `timer.start(cx, duration)` doesn't compile

**Cause**: Timer API changed. Timer is now returned from Cx methods.

**Solution**:
```rust
// Old (wrong)
self.timer.start(cx, 0.1);

// New (correct)
self.timer = cx.start_interval(0.1);

### Auto-Correction Prompt

When Claude detects skill-caused errors:

> "The skill advice I followed caused an error. Let me correct the skill and document this fix."

---

## Self-Validation (自我验证)

Periodically verify skill content is still accurate.

### Validation Triggers

| Trigger | Action |
|---------|--------|
| User asks "validate skills" | Full validation |
| Compilation fails with skill code | Targeted validation |
| New Makepad version detected | API validation |
| Skill hasn't been validated in 30 days | Scheduled validation |

### Validation Checklist

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

### External Links
- [ ] GitHub links resolve
- [ ] Documentation links work
- [ ] Example project links valid

### Completeness
- [ ] No deprecated patterns without warnings
- [ ] No missing common use cases
- [ ] Error messages match current Makepad

┌─────────────────────────────────────────────────────────┐
│  1. READ: Load all SKILL.md files                       │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  2. EXTRACT: Find all code blocks                       │
│     - live_design! blocks                               │
│     - Rust implementation blocks                        │
│     - Cargo.toml snippets                               │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  3. VERIFY: Check against current Makepad               │
│     - Parse DSL syntax                                  │
│     - Check widget/method existence                     │
│     - Verify API signatures                             │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  4. REPORT: List issues found                           │
│     - Outdated code                                     │
│     - Broken examples                                   │
│     - Missing updates                                   │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  5. FIX: Correct issues (with user approval)            │
└─────────────────────────────────────────────────────────┘

<!-- Validated: YYYY-MM-DD | makepad-branch: dev | status: passed -->

<!-- Usage: count=0 | success=0 | failed=0 | last_used=never -->
## Pattern 5: Loading State Button

┌─────────────────────────────────────────────────────────┐
│  User asks Claude to implement something                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Claude uses a pattern from makepad-skills              │
│  → Increment: count += 1                                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Implementation result:                                 │
│  - Works → success += 1                                 │
│  - Fails → failed += 1, trigger self-correction         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Update marker with new counts                          │
│  Update last_used timestamp                             │
└─────────────────────────────────────────────────────────┘

## Pattern Health Report

| Pattern | Uses | Success | Failed | Rate | Status |
|---------|------|---------|--------|------|--------|
| Pattern 1: Basic Widget | 45 | 43 | 2 | 96% | ✅ Healthy |
| Pattern 5: Loading Button | 12 | 8 | 4 | 67% | ⚠️ Needs Review |
| Pattern 8: Theme Switch | 3 | 0 | 3 | 0% | ❌ Broken |

| Branch | Status | Notes |
|--------|--------|-------|
| main | Stable | Production ready |
| dev | Active | Latest features, may break |
| rik | Legacy | Older API style |

### Timer Setup

<version branch="dev">
```rust
// Makepad dev branch (2024+)
self.timer = cx.start_interval(0.1);

┌─────────────────────────────────────────────────────────┐
│  1. DETECT: Identify project's Makepad version          │
│     - Read Cargo.toml                                   │
│     - Check branch reference                            │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  2. FILTER: Show only relevant version content          │
│     - Hide incompatible examples                        │
│     - Highlight version-specific gotchas                │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  3. WARN: Alert about version mismatches                │
│     - "This pattern is for dev branch, you're on rik"   │
│     - "API changed in dev, see updated syntax"          │
└─────────────────────────────────────────────────────────┘

## API Compatibility

| Feature | main | dev | rik |
|---------|------|-----|-----|
| cx.start_interval() | ✅ | ✅ | ❌ |
| timer.start() | ❌ | ❌ | ✅ |
| AdaptiveView | ✅ | ✅ | ✅ |
| StackNavigation | ✅ | ✅ | ⚠️ |

## Project Style Profile

- **Widget naming**: snake_case (e.g., `my_button`, `user_card`)
- **Module organization**: Feature-based (`src/features/auth/`)
- **State management**: Centralized AppState
- **Error handling**: Result with custom errors
- **Comments**: Minimal, code is self-documenting
- **Complexity preference**: Simple, small widgets

┌─────────────────────────────────────────────────────────┐
│  1. SCAN: Analyze existing project code                 │
│     - Read 3-5 representative widget files              │
│     - Note naming patterns                              │
│     - Identify organizational structure                 │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  2. PROFILE: Build project style profile                │
│     - Naming conventions                                │
│     - Code organization                                 │
│     - Complexity level                                  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  3. ADAPT: Modify skill suggestions to match            │
│     - Rename widgets in examples                        │
│     - Adjust code structure                             │
│     - Match comment style                               │
└─────────────────────────────────────────────────────────┘

pub struct MyCustomButton {
    #[walk] walk: Walk,
    #[live] label_text: String,
}

pub struct CustomButtonView {
    #[walk] walk: Walk,
    #[live] label_text: String,
}

{
  "makepad-skills": {
    "style": {
      "widget_suffix": "_view",
      "naming": "snake_case",
      "prefer_simple": true
    }
  }
}

                    ┌─────────────────┐
                    │  Development    │
                    │  Session        │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
         ▼                   ▼                   ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Personalize │     │   Use       │     │  Detect     │
│ suggestions │     │   Patterns  │     │  Version    │
└─────────────┘     └──────┬──────┘     └─────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Success  │ │ Failure  │ │ New      │
        │ +1       │ │ +1       │ │ Pattern  │
        └──────────┘ └────┬─────┘ └────┬─────┘
                          │            │
                          ▼            ▼
                   ┌──────────┐ ┌──────────┐
                   │ Self-    │ │ Self-    │
                   │ Correct  │ │ Evolve   │
                   └──────────┘ └──────────┘
                          │            │
                          └─────┬──────┘
                                │
                                ▼
                       ┌─────────────┐
                       │  Improved   │
                       │  Skills     │
                       └─────────────┘