--- name: makepad-evolution description: Self-improving skill system for Makepad development. Features self-evolution (accumulate knowledge), self-correction (fix errors automatically), self-validation (verify accuracy), usage feedback (track pattern health), version adaptation (multi-branch support), and personalization (adapt to project style). Use to continuously improve makepad-skills during development. --- # Makepad Skills Evolution This skill enables makepad-skills to self-improve continuously during development. --- ## Automatic vs Manual Triggers **IMPORTANT FOR CLAUDE**: Some mechanisms should trigger automatically without user request. ### Automatic (Claude should do proactively) | Mechanism | When to Auto-Trigger | |-----------|---------------------| | **Version Adaptation** | At session start, read Cargo.toml and detect Makepad branch | | **Personalization** | On first code generation, scan 2-3 existing widgets for style | | **Self-Correction** | Immediately when skill-suggested code fails | | **Usage Feedback** | After each pattern usage (success or failure) | ### Semi-Automatic (Claude proposes, user confirms) | Mechanism | When to Propose | |-----------|-----------------| | **Self-Evolution** | After solving a non-trivial problem worth documenting | ### Manual (User must request) | Mechanism | Trigger Phrase | |-----------|---------------| | **Self-Validation** | "validate makepad-skills" | | **Health Report** | "show pattern health report" | --- ## Session Start Checklist (Auto-Execute) When starting a Makepad development session, Claude should automatically: ``` 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 ``` **Claude: Do these silently. Don't announce unless relevant to user's question.** --- ## When to Evolve Trigger skill evolution when any of these occur during development: | Trigger | Target Skill | Priority | |---------|--------------|----------| | New widget pattern discovered | makepad-patterns | High | | Shader technique learned | makepad-shaders | High | | Compilation error solved | makepad-troubleshooting | High | | Layout solution found | makepad-adaptive-layout | Medium | | Build/packaging issue resolved | makepad-packaging | Medium | | New project structure insight | makepad-init | Low | | Core concept clarified | makepad-fundamentals | 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 → 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 ``` ### Step 3: Format the Contribution **For Patterns (makepad-patterns)**: ```markdown ## 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 \``` ``` **For Troubleshooting (makepad-troubleshooting)**: ```markdown ### [Error Type/Message] **Symptom**: What the developer sees **Cause**: Why this happens **Solution**: \```rust // Fixed code \``` ``` **For Shaders (makepad-shaders)**: ```markdown ### [Effect Name] \```rust draw_bg: { // shader code with comments fn pixel(self) -> vec4 { // implementation } } \``` ``` ### Step 4: Update the Skill File 1. Read the target SKILL.md file 2. Find the appropriate section 3. Add new content following existing format 4. Ensure no duplicate content ### Step 5: Mark Evolution (NOT Version) **Important**: Do NOT update version number locally. Add an evolution marker instead: ```markdown ``` Place this comment above the new content you added. ### Step 6: Submit via Git ```bash # 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 ``` --- ## Multi-Developer Collaboration ### The Problem ``` Developer A: evolves locally → version 1.4.1 Developer B: evolves locally → version 1.4.1 ← Conflict! ``` ### The Solution: Content-First Model ``` ┌─────────────────────────────────────────────────────────┐ │ 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 Marker Format Each contribution should include a marker: ```markdown ``` Example in makepad-patterns/SKILL.md: ```markdown ## Pattern 15: Loading State Button A button that shows loading spinner when processing... ``` ### Git Workflow ```bash # 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" ``` ### Handling Content Conflicts When multiple developers add to the same section: ```markdown <<<<<<< HEAD ## Pattern 15: Loading Button ======= ## Pattern 15: Expandable Card >>>>>>> evolution/add-card-pattern ``` Resolution: **Renumber and keep both** ```markdown ## Pattern 15: Loading Button ... ## Pattern 16: Expandable Card ... ``` ### Version Bumping (Maintainer Only) At release time, maintainer reviews accumulated changes: ```bash # 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 ``` ### CI Automation (Optional) `.github/workflows/version.yml`: ```yaml 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 ``` ## Evolution Templates ### Quick Pattern Addition ``` 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 ``` ### Quick Troubleshooting Addition ``` 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 ``` ### Quick Shader Addition ``` 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 ``` ## Skill File Locations ### Locating the Skills Directory (IMPORTANT) **Claude: When this skill is loaded, you know the path of THIS file. Use it to locate other skills.** ``` 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/ ``` ### Auto-Detection Instructions for Claude When evolving skills, Claude MUST: 1. **Remember the path of this skill file** (you just read it, you know where it is) 2. **Calculate the skills root**: - This file is at: `/makepad-evolution/SKILL.md` - So `` = go up two directory levels from this file 3. **Construct target paths relatively**: ``` To edit makepad-patterns: /makepad-patterns/SKILL.md To edit makepad-troubleshooting: /makepad-troubleshooting/SKILL.md To edit makepad-shaders: /makepad-shaders/SKILL.md ``` 4. **Use the Read tool with the constructed absolute path** 5. **Use the Edit tool to update the file** ### Example Evolution Flow ``` 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 ✓ ``` **No hardcoded paths. Always derive from THIS file's location.** ### Relative Structure (from 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 ``` ### Where Updates Are Saved | Scenario | Save Location | Sync Method | |----------|---------------|-------------| | Working in makepad-skills repo | Source directory | Direct | | Using skills in project (copy) | Project's .claude/skills/ | Manual PR to upstream | | Using skills in project (symlink) | Source directory | Direct | **Recommended Setup**: Symlink to source for active contributors ```bash # In your project ln -s /path/to/makepad-skills .claude/skills/makepad-skills # Now evolutions save directly to source ``` ## 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." ## 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 ## Evolution Log When evolving skills, optionally log the change: ```markdown ``` ## 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! --- ## Self-Correction (自我修正) When skill content causes errors, automatically correct it. **AUTO-TRIGGER: Yes** - Claude should automatically correct skills when errors occur. ### Trigger Conditions ``` User follows skill advice → Code fails to compile/run → Claude identifies skill was wrong ↓ AUTO: Correct skill immediately ``` ### Claude Auto-Behavior When Claude detects that code from a skill caused an error: 1. **Recognize** - "This error is because the skill advice was wrong" 2. **Fix user's code** - Provide correct solution 3. **Update skill** - Automatically edit the skill file (no need to ask) 4. **Inform user** - "I've also updated makepad-skills to prevent this error for others" ### Self-Correction Flow ``` ┌─────────────────────────────────────────────────────────┐ │ 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 Marker Format ```markdown ``` ### Example Self-Correction **Scenario**: Skill said `timer.start(cx, 0.1)` but it fails ``` 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: ``` ```markdown ### Timer Setup ```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 } ``` 4. Claude also adds to makepad-troubleshooting: ```markdown ### "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 ``` ### Validation Flow ``` ┌─────────────────────────────────────────────────────────┐ │ 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) │ └─────────────────────────────────────────────────────────┘ ``` ### Validation Marker After validation, add to skill file: ```markdown ``` ### Validation Prompt > "Please valid