diff --git a/default/omarchy-skill/SKILL.md b/default/omarchy-skill/SKILL.md
index cf3a0569..f591022a 100644
--- a/default/omarchy-skill/SKILL.md
+++ b/default/omarchy-skill/SKILL.md
@@ -1,22 +1,26 @@
 ---
 name: omarchy
 description: >
-  REQUIRED for ANY changes to Linux desktop, window manager, or system config.
+  REQUIRED for end-user customization of Linux desktop, window manager, or system config.
   Use when editing ~/.config/hypr/, ~/.config/waybar/, ~/.config/walker/,
   ~/.config/alacritty/, ~/.config/kitty/, ~/.config/ghostty/, ~/.config/mako/,
   or ~/.config/omarchy/. Triggers: Hyprland, window rules, animations, keybindings,
   monitors, gaps, borders, blur, opacity, waybar, walker, terminal config, themes,
   wallpaper, night light, idle, lock screen, screenshots, layer rules, workspace
-  settings, display config, or any omarchy-* commands.
+  settings, display config, and user-facing omarchy commands. Excludes Omarchy
+  source development in ~/.local/share/omarchy/ and omarchy-dev-* workflows.
 ---
 
 # Omarchy Skill
 
 Manage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, modern, opinionated Arch Linux distribution with Hyprland.
 
+This skill is for end-user customization on installed systems.
+It is not for contributing to Omarchy source code.
+
 ## When This Skill MUST Be Used
 
-**ALWAYS invoke this skill when the user's request involves ANY of these:**
+**ALWAYS invoke this skill for end-user requests involving ANY of these:**
 
 - Editing ANY file in `~/.config/hypr/` (window rules, animations, keybindings, monitors, etc.)
 - Editing ANY file in `~/.config/waybar/`, `~/.config/walker/`, `~/.config/mako/`
@@ -25,14 +29,16 @@ Manage [Omarchy](https://omarchy.org/) Linux systems - a beautiful, modern, opin
 - Window behavior, animations, opacity, blur, gaps, borders
 - Layer rules, workspace settings, display/monitor configuration
 - Themes, wallpapers, fonts, appearance changes
-- Any `omarchy-*` command
+- User-facing `omarchy-*` commands (`omarchy-theme-*`, `omarchy-refresh-*`, `omarchy-restart-*`, etc.)
 - Screenshots, screen recording, night light, idle behavior, lock screen
 
 **If you're about to edit a config file in ~/.config/ on this system, STOP and use this skill first.**
 
+**Do NOT use this skill for Omarchy development tasks** (editing files in `~/.local/share/omarchy/`, creating migrations, or running `omarchy-dev-*` workflows).
+
 ## Critical Safety Rules
 
-**NEVER modify anything in `~/.local/share/omarchy/`** - but READING is safe and encouraged.
+**For end-user customization tasks, NEVER modify anything in `~/.local/share/omarchy/`** - but READING is safe and encouraged.
 
 This directory contains Omarchy's source files managed by git. Any changes will be:
 - Lost on next `omarchy-update`
@@ -60,6 +66,8 @@ This directory contains Omarchy's source files managed by git. Any changes will
 - `~/.config/omarchy/themes/<custom-name>/` - Custom themes (must be real directories)
 - `~/.config/omarchy/hooks/` - Custom automation hooks
 
+If the request is to develop Omarchy itself, this skill is out of scope. Follow repository development instructions instead of this skill.
+
 ## System Architecture
 
 Omarchy is built on:
@@ -336,26 +344,15 @@ When user requests system changes:
 2. **Is it a config edit?** Edit in `~/.config/`, never `~/.local/share/omarchy/`
 3. **Is it a theme customization?** Create a NEW custom theme directory
 4. **Is it automation?** Use hooks in `~/.config/omarchy/hooks/`
-5. **Is it a package install?** Use `yay`
+5. **Is it a package install?** Use `omarchy-pkg-add` (or `omarchy-pkg-aur-add` for AUR-only packages)
 6. **Unsure if command exists?** Search with `compgen -c | grep omarchy`
 
-## Development (AI Agents)
+## Out of Scope
 
-When contributing to Omarchy itself (e.g., fixing bugs, adding features), migrations are used to apply changes to existing installations.
-
-### Creating Migrations
-
-```bash
-# ALWAYS use --no-edit flag or you will get stuck
-omarchy-dev-add-migration --no-edit
-```
-
-This creates a new migration file and outputs its path without opening an editor. The migration filename is based on the git commit timestamp.
-
-**Migration files** are shell scripts in `~/.local/share/omarchy/migrations/` that run once per system during `omarchy-update`. Use them for:
-- Updating user configs with new defaults
-- Installing new dependencies
-- Running one-time setup tasks
+This skill intentionally does not cover Omarchy source development. Do not use this skill for:
+- Editing files in `~/.local/share/omarchy/` (`bin/`, `config/`, `default/`, `themes/`, `migrations/`, etc.)
+- Creating or editing migrations
+- Running `omarchy-dev-*` commands
 
 ## Example Requests