Omarchy Skill
Treat this skill as an Omarchy operating mode, not just a command catalog. When working on an Omarchy system, prefer Omarchy-native wrappers and workflows over generic Linux one-liners that may bypass expected state handling. Use local script docs and names to choose the correct path. Each script has documentation at the top describing its purpose. DO NOT RUN A SCRIPT UNTIL YOU ARE SURE OF ITS PURPOSE.
Operating rules
- Start with command name matching and in-file comments under
/home/achals/.local/share/omarchy/bin.
- Prefer read-only/status commands first (
*list*, *status*, *current*, *available*, *version*).
- Ask before broad or high-impact actions (
*install*, *remove*, *reinstall*, *update*, *pkg*, *setup*, *set*).
- Avoid bulk discovery execution. Do static inspection first.
- Never assume
omarchy-* scripts support standard CLI flags or parameters (including --help). Treat each script as custom; inspect its file/header comments first.
Worked examples (good vs bad)
Use these patterns whenever you operate on Omarchy. The goal is not "run an omarchy command at all costs"; the goal is to avoid bypassing Omarchy’s intended state-management flows.
1) Restarting Waybar
User intent: "Waybar is broken, restart it."
- Bad (generic shortcut):
- Good (Omarchy-native):
- Why: Omarchy wrappers usually handle environment/session assumptions better than raw kill-and-relaunch one-liners.
2) Applying config/UI refresh after edits
User intent: "I changed config, apply it."
- Bad:
- restarting random processes manually until things look fixed
- Good:
- use targeted refresh script first, e.g.
omarchy-refresh-waybar, omarchy-refresh-hyprland, omarchy-refresh-config (pick by component)
- Why: refresh scripts are explicit and reversible; manual shotgun restarts are noisy and risky.
3) Package management task
User intent: "Install/remove package X."
- Bad:
- using raw
pacman/yay first without checking Omarchy wrappers
- Good:
- inspect and prefer
omarchy-pkg-* flow (...-present, ...-missing, then ...-install/...-remove)
- Why: wrapper flow keeps behavior consistent with Omarchy expectations.
4) Theme change request
User intent: "Switch theme / sync theme to apps."
- Bad:
- editing dotfiles manually first and restarting random apps
- Good:
omarchy-theme-list -> omarchy-theme-set -> app-specific follow-ups if needed (omarchy-theme-set-vscode, ...-browser, ...-obsidian)
- Why: Omarchy theme pipeline may include extra integration steps beyond plain config edits.
5) Audio/Bluetooth/Wi‑Fi issue
User intent: "Audio/Bluetooth/Wi‑Fi stopped behaving."
- Bad:
- broad process killing (
killall pipewire, random daemon restarts)
- Good:
- use targeted wrapper restarts such as
omarchy-restart-pipewire, omarchy-restart-bluetooth, omarchy-restart-wifi
- Why: targeted wrappers reduce collateral damage and match Omarchy’s service model.
6) "What command should I run?" discovery flow
User intent: ambiguous request like "fix my display stack".
- Bad:
- execute many commands to discover options (
for c in omarchy-*; do $c --help; done)
- Good:
- Statically inspect names in
/home/achals/.local/share/omarchy/bin
- Read top-of-file script comments for likely candidates
- Start with read-only/status scripts
- Propose 1-3 likely commands and ask before high-impact actions
- Why: static inspection is safer, faster, and follows no-bulk-probing policy.
7) Update workflow
User intent: "Update system."
- Bad:
- directly running full update steps without checking availability/state
- Good:
- check first:
omarchy-update-available (and related status)
- then execute appropriate Omarchy update path with confirmation for impactful steps
- Why: staged update flow reduces surprise breakage.
Decision template (apply every time)
For any Omarchy task, follow this mini-checklist:
- Identify component (UI, package, theme, network, update, device, etc.)
- Find matching
omarchy-* family by name and script header comments
- Prefer read-only/status command first
- Use targeted
omarchy-refresh-*/omarchy-restart-* over raw kill/relaunch
- Ask before high-impact actions (
install/remove/reinstall/update/setup/set)
Omarchy command catalog (static, local)
Total commands: 161
battery (2)
omarchy-battery-monitoromarchy-battery-remaining
branch (1)
channel (1)
cmd (12)
omarchy-cmd-apple-display-brightnessomarchy-cmd-audio-switchomarchy-cmd-first-runomarchy-cmd-missingomarchy-cmd-presentomarchy-cmd-rebootomarchy-cmd-screenrecordomarchy-cmd-screensaveromarchy-cmd-screenshotomarchy-cmd-shareomarchy-cmd-shutdownomarchy-cmd-terminal-cwd
debug (1)
dev (1)
omarchy-dev-add-migration
drive (3)
omarchy-drive-infoomarchy-drive-selectomarchy-drive-set-password
font (3)
omarchy-font-currentomarchy-font-listomarchy-font-set
hibernation (3)
omarchy-hibernation-availableomarchy-hibernation-removeomarchy-hibernation-setup
hook (1)
hyprland (3)
omarchy-hyprland-window-close-allomarchy-hyprland-window-popomarchy-hyprland-workspace-toggle-gaps
install (9)
omarchy-install-chromium-google-accountomarchy-install-dev-envomarchy-install-docker-dbsomarchy-install-dropboxomarchy-install-steamomarchy-install-tailscaleomarchy-install-terminalomarchy-install-vscodeomarchy-install-xbox-controllers
launch (14)
omarchy-launch-aboutomarchy-launch-audioomarchy-launch-bluetoothomarchy-launch-browseromarchy-launch-editoromarchy-launch-floating-terminal-with-presentationomarchy-launch-or-focusomarchy-launch-or-focus-tuiomarchy-launch-or-focus-webappomarchy-launch-screensaveromarchy-launch-tuiomarchy-launch-walkeromarchy-launch-webappomarchy-launch-wifi
lock (1)
menu (2)
omarchy-menuomarchy-menu-keybindings
migrate (1)
notification (1)
omarchy-notification-dismiss
pkg (9)
omarchy-pkg-addomarchy-pkg-aur-accessibleomarchy-pkg-aur-addomarchy-pkg-aur-installomarchy-pkg-dropomarchy-pkg-installomarchy-pkg-missingomarchy-pkg-presentomarchy-pkg-remove
powerprofiles (1)
omarchy-powerprofiles-list
refresh (14)
omarchy-refresh-applicationsomarchy-refresh-chromiumomarchy-refresh-configomarchy-refresh-fastfetchomarchy-refresh-hypridleomarchy-refresh-hyprlandomarchy-refresh-hyprlockomarchy-refresh-hyprsunsetomarchy-refresh-limineomarchy-refresh-pacmanomarchy-refresh-plymouthomarchy-refresh-swayosdomarchy-refresh-walkeromarchy-refresh-waybar
reinstall (4)
omarchy-reinstallomarchy-reinstall-configsomarchy-reinstall-gitomarchy-reinstall-pkgs
remove (1)
reset (1)
restart (15)
omarchy-restart-appomarchy-restart-bluetoothomarchy-restart-btopomarchy-restart-hyprctlomarchy-restart-hypridleomarchy-restart-hyprsunsetomarchy-restart-makoomarchy-restart-opencodeomarchy-restart-pipewireomarchy-restart-swayosdomarchy-restart-terminalomarchy-restart-walkeromarchy-restart-waybaromarchy-restart-wifiomarchy-restart-xcompose
setup (3)
omarchy-setup-dnsomarchy-setup-fido2omarchy-setup-fingerprint
show (2)
omarchy-show-doneomarchy-show-logo
snapshot (1)
state (1)
theme (13)
omarchy-theme-bg-installomarchy-theme-bg-nextomarchy-theme-currentomarchy-theme-installomarchy-theme-listomarchy-theme-removeomarchy-theme-setomarchy-theme-set-browseromarchy-theme-set-gnomeomarchy-theme-set-obsidianomarchy-theme-set-templatesomarchy-theme-set-vscodeomarchy-theme-update
toggle (5)
omarchy-toggle-idleomarchy-toggle-nightlightomarchy-toggle-screensaveromarchy-toggle-suspendomarchy-toggle-waybar
tui (2)
omarchy-tui-installomarchy-tui-remove
tz (1)
update (14)
omarchy-updateomarchy-update-analyze-logsomarchy-update-availableomarchy-update-available-resetomarchy-update-branchomarchy-update-confirmomarchy-update-firmwareomarchy-update-gitomarchy-update-keyringomarchy-update-performomarchy-update-restartomarchy-update-system-pkgsomarchy-update-timeomarchy-update-without-idle
upload (1)
version (4)
omarchy-versionomarchy-version-branchomarchy-version-channelomarchy-version-pkgs
voxtype (5)
omarchy-voxtype-configomarchy-voxtype-installomarchy-voxtype-modelomarchy-voxtype-removeomarchy-voxtype-status
webapp (4)
omarchy-webapp-handler-heyomarchy-webapp-handler-zoomomarchy-webapp-installomarchy-webapp-remove
windows (1)
1---2name: omarchy3description: Omarchy operating guardrails for day-to-day system work: assume the host is Omarchy by default, choose Omarchy-native workflows first, map user intent to the correct omarchy-* wrapper/script family, and avoid generic Linux commands that conflict with Omarchy behavior. Use whenever handling local system tasks on this host unless the user explicitly says it is not Omarchy; prioritize safe Omarchy commands, prevent non-Omarchy shortcuts (e.g., ad-hoc process killing/relaunch patterns), troubleshoot desktop behavior, and validate the right script before execution.4---5
6# Omarchy Skill
7
8Treat this skill as an Omarchy operating mode, not just a command catalog. When working on an Omarchy system, prefer Omarchy-native wrappers and workflows over generic Linux one-liners that may bypass expected state handling. Use local script docs and names to choose the correct path. Each script has documentation at the top describing its purpose. DO NOT RUN A SCRIPT UNTIL YOU ARE SURE OF ITS PURPOSE.
9
10## Operating rules
11
121. Start with command name matching and in-file comments under `/home/achals/.local/share/omarchy/bin`.
132. Prefer read-only/status commands first (`*list*`, `*status*`, `*current*`, `*available*`, `*version*`).
143. Ask before broad or high-impact actions (`*install*`, `*remove*`, `*reinstall*`, `*update*`, `*pkg*`, `*setup*`, `*set*`).
154. Avoid bulk discovery execution. Do static inspection first.
165. Never assume `omarchy-*` scripts support standard CLI flags or parameters (including `--help`). Treat each script as custom; inspect its file/header comments first.
17
18## Worked examples (good vs bad)
19
20Use these patterns whenever you operate on Omarchy. The goal is not "run an omarchy command at all costs"; the goal is to avoid bypassing Omarchy’s intended state-management flows.
21
22### 1) Restarting Waybar
23
24User intent: "Waybar is broken, restart it."
25
26- Bad (generic shortcut):
27 - `pkill waybar && waybar`
28- Good (Omarchy-native):
29 - `omarchy-restart-waybar`
30- Why: Omarchy wrappers usually handle environment/session assumptions better than raw kill-and-relaunch one-liners.
31
32### 2) Applying config/UI refresh after edits
33
34User intent: "I changed config, apply it."
35
36- Bad:
37 - restarting random processes manually until things look fixed
38- Good:
39 - use targeted refresh script first, e.g. `omarchy-refresh-waybar`, `omarchy-refresh-hyprland`, `omarchy-refresh-config` (pick by component)
40- Why: refresh scripts are explicit and reversible; manual shotgun restarts are noisy and risky.
41
42### 3) Package management task
43
44User intent: "Install/remove package X."
45
46- Bad:
47 - using raw `pacman`/`yay` first without checking Omarchy wrappers
48- Good:
49 - inspect and prefer `omarchy-pkg-*` flow (`...-present`, `...-missing`, then `...-install`/`...-remove`)
50- Why: wrapper flow keeps behavior consistent with Omarchy expectations.
51
52### 4) Theme change request
53
54User intent: "Switch theme / sync theme to apps."
55
56- Bad:
57 - editing dotfiles manually first and restarting random apps
58- Good:
59 - `omarchy-theme-list` -> `omarchy-theme-set` -> app-specific follow-ups if needed (`omarchy-theme-set-vscode`, `...-browser`, `...-obsidian`)
60- Why: Omarchy theme pipeline may include extra integration steps beyond plain config edits.
61
62### 5) Audio/Bluetooth/Wi‑Fi issue
63
64User intent: "Audio/Bluetooth/Wi‑Fi stopped behaving."
65
66- Bad:
67 - broad process killing (`killall pipewire`, random daemon restarts)
68- Good:
69 - use targeted wrapper restarts such as `omarchy-restart-pipewire`, `omarchy-restart-bluetooth`, `omarchy-restart-wifi`
70- Why: targeted wrappers reduce collateral damage and match Omarchy’s service model.
71
72### 6) "What command should I run?" discovery flow
73
74User intent: ambiguous request like "fix my display stack".
75
76- Bad:
77 - execute many commands to discover options (`for c in omarchy-*; do $c --help; done`)
78- Good:
79 1. Statically inspect names in `/home/achals/.local/share/omarchy/bin`
80 2. Read top-of-file script comments for likely candidates
81 3. Start with read-only/status scripts
82 4. Propose 1-3 likely commands and ask before high-impact actions
83- Why: static inspection is safer, faster, and follows no-bulk-probing policy.
84
85### 7) Update workflow
86
87User intent: "Update system."
88
89- Bad:
90 - directly running full update steps without checking availability/state
91- Good:
92 - check first: `omarchy-update-available` (and related status)
93 - then execute appropriate Omarchy update path with confirmation for impactful steps
94- Why: staged update flow reduces surprise breakage.
95
96## Decision template (apply every time)
97
98For any Omarchy task, follow this mini-checklist:
99
1001. Identify component (UI, package, theme, network, update, device, etc.)
1012. Find matching `omarchy-*` family by name and script header comments
1023. Prefer read-only/status command first
1034. Use targeted `omarchy-refresh-*`/`omarchy-restart-*` over raw kill/relaunch
1045. Ask before high-impact actions (`install/remove/reinstall/update/setup/set`)
105
106## Omarchy command catalog (static, local)
107
108Total commands: **161**
109
110### battery (2)
111- `omarchy-battery-monitor`
112- `omarchy-battery-remaining`
113
114### branch (1)
115- `omarchy-branch-set`
116
117### channel (1)
118- `omarchy-channel-set`
119
120### cmd (12)
121- `omarchy-cmd-apple-display-brightness`
122- `omarchy-cmd-audio-switch`
123- `omarchy-cmd-first-run`
124- `omarchy-cmd-missing`
125- `omarchy-cmd-present`
126- `omarchy-cmd-reboot`
127- `omarchy-cmd-screenrecord`
128- `omarchy-cmd-screensaver`
129- `omarchy-cmd-screenshot`
130- `omarchy-cmd-share`
131- `omarchy-cmd-shutdown`
132- `omarchy-cmd-terminal-cwd`
133
134### debug (1)
135- `omarchy-debug`
136
137### dev (1)
138- `omarchy-dev-add-migration`
139
140### drive (3)
141- `omarchy-drive-info`
142- `omarchy-drive-select`
143- `omarchy-drive-set-password`
144
145### font (3)
146- `omarchy-font-current`
147- `omarchy-font-list`
148- `omarchy-font-set`
149
150### hibernation (3)
151- `omarchy-hibernation-available`
152- `omarchy-hibernation-remove`
153- `omarchy-hibernation-setup`
154
155### hook (1)
156- `omarchy-hook`
157
158### hyprland (3)
159- `omarchy-hyprland-window-close-all`
160- `omarchy-hyprland-window-pop`
161- `omarchy-hyprland-workspace-toggle-gaps`
162
163### install (9)
164- `omarchy-install-chromium-google-account`
165- `omarchy-install-dev-env`
166- `omarchy-install-docker-dbs`
167- `omarchy-install-dropbox`
168- `omarchy-install-steam`
169- `omarchy-install-tailscale`
170- `omarchy-install-terminal`
171- `omarchy-install-vscode`
172- `omarchy-install-xbox-controllers`
173
174### launch (14)
175- `omarchy-launch-about`
176- `omarchy-launch-audio`
177- `omarchy-launch-bluetooth`
178- `omarchy-launch-browser`
179- `omarchy-launch-editor`
180- `omarchy-launch-floating-terminal-with-presentation`
181- `omarchy-launch-or-focus`
182- `omarchy-launch-or-focus-tui`
183- `omarchy-launch-or-focus-webapp`
184- `omarchy-launch-screensaver`
185- `omarchy-launch-tui`
186- `omarchy-launch-walker`
187- `omarchy-launch-webapp`
188- `omarchy-launch-wifi`
189
190### lock (1)
191- `omarchy-lock-screen`
192
193### menu (2)
194- `omarchy-menu`
195- `omarchy-menu-keybindings`
196
197### migrate (1)
198- `omarchy-migrate`
199
200### notification (1)
201- `omarchy-notification-dismiss`
202
203### pkg (9)
204- `omarchy-pkg-add`
205- `omarchy-pkg-aur-accessible`
206- `omarchy-pkg-aur-add`
207- `omarchy-pkg-aur-install`
208- `omarchy-pkg-drop`
209- `omarchy-pkg-install`
210- `omarchy-pkg-missing`
211- `omarchy-pkg-present`
212- `omarchy-pkg-remove`
213
214### powerprofiles (1)
215- `omarchy-powerprofiles-list`
216
217### refresh (14)
218- `omarchy-refresh-applications`
219- `omarchy-refresh-chromium`
220- `omarchy-refresh-config`
221- `omarchy-refresh-fastfetch`
222- `omarchy-refresh-hypridle`
223- `omarchy-refresh-hyprland`
224- `omarchy-refresh-hyprlock`
225- `omarchy-refresh-hyprsunset`
226- `omarchy-refresh-limine`
227- `omarchy-refresh-pacman`
228- `omarchy-refresh-plymouth`
229- `omarchy-refresh-swayosd`
230- `omarchy-refresh-walker`
231- `omarchy-refresh-waybar`
232
233### reinstall (4)
234- `omarchy-reinstall`
235- `omarchy-reinstall-configs`
236- `omarchy-reinstall-git`
237- `omarchy-reinstall-pkgs`
238
239### remove (1)
240- `omarchy-remove-dev-env`
241
242### reset (1)
243- `omarchy-reset-sudo`
244
245### restart (15)
246- `omarchy-restart-app`
247- `omarchy-restart-bluetooth`
248- `omarchy-restart-btop`
249- `omarchy-restart-hyprctl`
250- `omarchy-restart-hypridle`
251- `omarchy-restart-hyprsunset`
252- `omarchy-restart-mako`
253- `omarchy-restart-opencode`
254- `omarchy-restart-pipewire`
255- `omarchy-restart-swayosd`
256- `omarchy-restart-terminal`
257- `omarchy-restart-walker`
258- `omarchy-restart-waybar`
259- `omarchy-restart-wifi`
260- `omarchy-restart-xcompose`
261
262### setup (3)
263- `omarchy-setup-dns`
264- `omarchy-setup-fido2`
265- `omarchy-setup-fingerprint`
266
267### show (2)
268- `omarchy-show-done`
269- `omarchy-show-logo`
270
271### snapshot (1)
272- `omarchy-snapshot`
273
274### state (1)
275- `omarchy-state`
276
277### theme (13)
278- `omarchy-theme-bg-install`
279- `omarchy-theme-bg-next`
280- `omarchy-theme-current`
281- `omarchy-theme-install`
282- `omarchy-theme-list`
283- `omarchy-theme-remove`
284- `omarchy-theme-set`
285- `omarchy-theme-set-browser`
286- `omarchy-theme-set-gnome`
287- `omarchy-theme-set-obsidian`
288- `omarchy-theme-set-templates`
289- `omarchy-theme-set-vscode`
290- `omarchy-theme-update`
291
292### toggle (5)
293- `omarchy-toggle-idle`
294- `omarchy-toggle-nightlight`
295- `omarchy-toggle-screensaver`
296- `omarchy-toggle-suspend`
297- `omarchy-toggle-waybar`
298
299### tui (2)
300- `omarchy-tui-install`
301- `omarchy-tui-remove`
302
303### tz (1)
304- `omarchy-tz-select`
305
306### update (14)
307- `omarchy-update`
308- `omarchy-update-analyze-logs`
309- `omarchy-update-available`
310- `omarchy-update-available-reset`
311- `omarchy-update-branch`
312- `omarchy-update-confirm`
313- `omarchy-update-firmware`
314- `omarchy-update-git`
315- `omarchy-update-keyring`
316- `omarchy-update-perform`
317- `omarchy-update-restart`
318- `omarchy-update-system-pkgs`
319- `omarchy-update-time`
320- `omarchy-update-without-idle`
321
322### upload (1)
323- `omarchy-upload-log`
324
325### version (4)
326- `omarchy-version`
327- `omarchy-version-branch`
328- `omarchy-version-channel`
329- `omarchy-version-pkgs`
330
331### voxtype (5)
332- `omarchy-voxtype-config`
333- `omarchy-voxtype-install`
334- `omarchy-voxtype-model`
335- `omarchy-voxtype-remove`
336- `omarchy-voxtype-status`
337
338### webapp (4)
339- `omarchy-webapp-handler-hey`
340- `omarchy-webapp-handler-zoom`
341- `omarchy-webapp-install`
342- `omarchy-webapp-remove`
343
344### windows (1)
345- `omarchy-windows-vm`
modbender