omarchy

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.

Security Scan

The skill's requirements and runtime instructions are internally consistent with its stated purpose (an Omarchy-specific guardrail for running local omarchy-* scripts); it only directs static inspection of a local omarchy script directory and does not request credentials or install code.

Purpose & Capability

The name/description say this is an Omarchy operating-mode guardrail for local system tasks and the SKILL.md only instructs the agent to prefer and inspect local omarchy-* wrapper scripts. There are no unrelated env vars, binaries, or install steps requested, so the requested capabilities align with the described purpose.

Instruction Scope

The instructions direct the agent to statically inspect and prefer scripts under /home/achals/.local/share/omarchy/bin and to use read-only/status commands before taking impactful actions. This is appropriate for a local guardrail, but the path is hard-coded to a specific home directory ("/home/achals"), which may not match other hosts and could cause the agent to read a user's home files. The SKILL.md explicitly warns not to run scripts until sure, and discourages bulk probing, which reduces risk.

Install Mechanism

No install specification or code is included (instruction-only). That minimizes disk-write/execution risk and is proportional for a guidance/guardrail skill.

Credentials

The skill requests no environment variables, credentials, or config paths. Its instructions only reference a local script directory relevant to the stated purpose, so the level of access requested is proportionate.

Persistence & Privilege

The skill is not marked always:true and does not request persistent system changes or modify other skills. Autonomous invocation is allowed by platform default, but that is not excessive given the skill's benign, local-scope purpose.

Scan Findings in Context

[NO_REGEX_MATCHES] expected: This is an instruction-only skill with no code files, so the static regex scanner had nothing to analyze. That absence of findings is expected and not evidence of safety by itself.

Assessment

This skill appears coherent: it guides the agent to prefer and inspect local omarchy-* wrapper scripts instead of running raw system commands, and it doesn't request credentials or install code. Before installing, confirm that this host actually uses Omarchy and that the hard-coded path (/home/achals/.local/share/omarchy/bin) matches your environment; otherwise the skill may attempt to read a different user's home-path or be ineffective. Also review the actual scripts in the referenced directory (and their header comments) so you trust what the agent may propose running, and be cautious about granting the agent autonomous execution rights if you do not want it to run local scripts without approval.

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

1. Start with command name matching and in-file comments under /home/achals/.local/share/omarchy/bin.
2. Prefer read-only/status commands first (*list*, *status*, *current*, *available*, *version*).
3. Ask before broad or high-impact actions (*install*, *remove*, *reinstall*, *update*, *pkg*, *setup*, *set*).
4. Avoid bulk discovery execution. Do static inspection first.
5. 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):
  • pkill waybar && waybar
• Good (Omarchy-native):
  • omarchy-restart-waybar
• 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:
  1. Statically inspect names in /home/achals/.local/share/omarchy/bin
  2. Read top-of-file script comments for likely candidates
  3. Start with read-only/status scripts
  4. 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:

1. Identify component (UI, package, theme, network, update, device, etc.)
2. Find matching omarchy-* family by name and script header comments
3. Prefer read-only/status command first
4. Use targeted omarchy-refresh-*/omarchy-restart-* over raw kill/relaunch
5. Ask before high-impact actions (install/remove/reinstall/update/setup/set)

Omarchy command catalog (static, local)

Total commands: 161

battery (2)

• omarchy-battery-monitor
• omarchy-battery-remaining

branch (1)

• omarchy-branch-set

channel (1)

• omarchy-channel-set

cmd (12)

• omarchy-cmd-apple-display-brightness
• omarchy-cmd-audio-switch
• omarchy-cmd-first-run
• omarchy-cmd-missing
• omarchy-cmd-present
• omarchy-cmd-reboot
• omarchy-cmd-screenrecord
• omarchy-cmd-screensaver
• omarchy-cmd-screenshot
• omarchy-cmd-share
• omarchy-cmd-shutdown
• omarchy-cmd-terminal-cwd

debug (1)

• omarchy-debug

dev (1)

• omarchy-dev-add-migration

drive (3)

• omarchy-drive-info
• omarchy-drive-select
• omarchy-drive-set-password

font (3)

• omarchy-font-current
• omarchy-font-list
• omarchy-font-set

hibernation (3)

• omarchy-hibernation-available
• omarchy-hibernation-remove
• omarchy-hibernation-setup

hook (1)

• omarchy-hook

hyprland (3)

• omarchy-hyprland-window-close-all
• omarchy-hyprland-window-pop
• omarchy-hyprland-workspace-toggle-gaps

install (9)

• omarchy-install-chromium-google-account
• omarchy-install-dev-env
• omarchy-install-docker-dbs
• omarchy-install-dropbox
• omarchy-install-steam
• omarchy-install-tailscale
• omarchy-install-terminal
• omarchy-install-vscode
• omarchy-install-xbox-controllers

launch (14)

• omarchy-launch-about
• omarchy-launch-audio
• omarchy-launch-bluetooth
• omarchy-launch-browser
• omarchy-launch-editor
• omarchy-launch-floating-terminal-with-presentation
• omarchy-launch-or-focus
• omarchy-launch-or-focus-tui
• omarchy-launch-or-focus-webapp
• omarchy-launch-screensaver
• omarchy-launch-tui
• omarchy-launch-walker
• omarchy-launch-webapp
• omarchy-launch-wifi

lock (1)

• omarchy-lock-screen

menu (2)

• omarchy-menu
• omarchy-menu-keybindings

migrate (1)

• omarchy-migrate

notification (1)

• omarchy-notification-dismiss

pkg (9)

• omarchy-pkg-add
• omarchy-pkg-aur-accessible
• omarchy-pkg-aur-add
• omarchy-pkg-aur-install
• omarchy-pkg-drop
• omarchy-pkg-install
• omarchy-pkg-missing
• omarchy-pkg-present
• omarchy-pkg-remove

powerprofiles (1)

• omarchy-powerprofiles-list

refresh (14)

• omarchy-refresh-applications
• omarchy-refresh-chromium
• omarchy-refresh-config
• omarchy-refresh-fastfetch
• omarchy-refresh-hypridle
• omarchy-refresh-hyprland
• omarchy-refresh-hyprlock
• omarchy-refresh-hyprsunset
• omarchy-refresh-limine
• omarchy-refresh-pacman
• omarchy-refresh-plymouth
• omarchy-refresh-swayosd
• omarchy-refresh-walker
• omarchy-refresh-waybar

reinstall (4)

• omarchy-reinstall
• omarchy-reinstall-configs
• omarchy-reinstall-git
• omarchy-reinstall-pkgs

remove (1)

• omarchy-remove-dev-env

reset (1)

• omarchy-reset-sudo

restart (15)

• omarchy-restart-app
• omarchy-restart-bluetooth
• omarchy-restart-btop
• omarchy-restart-hyprctl
• omarchy-restart-hypridle
• omarchy-restart-hyprsunset
• omarchy-restart-mako
• omarchy-restart-opencode
• omarchy-restart-pipewire
• omarchy-restart-swayosd
• omarchy-restart-terminal
• omarchy-restart-walker
• omarchy-restart-waybar
• omarchy-restart-wifi
• omarchy-restart-xcompose

setup (3)

• omarchy-setup-dns
• omarchy-setup-fido2
• omarchy-setup-fingerprint

show (2)

• omarchy-show-done
• omarchy-show-logo

snapshot (1)

• omarchy-snapshot

state (1)

• omarchy-state

theme (13)

• omarchy-theme-bg-install
• omarchy-theme-bg-next
• omarchy-theme-current
• omarchy-theme-install
• omarchy-theme-list
• omarchy-theme-remove
• omarchy-theme-set
• omarchy-theme-set-browser
• omarchy-theme-set-gnome
• omarchy-theme-set-obsidian
• omarchy-theme-set-templates
• omarchy-theme-set-vscode
• omarchy-theme-update

toggle (5)

• omarchy-toggle-idle
• omarchy-toggle-nightlight
• omarchy-toggle-screensaver
• omarchy-toggle-suspend
• omarchy-toggle-waybar

tui (2)

• omarchy-tui-install
• omarchy-tui-remove

tz (1)

• omarchy-tz-select

update (14)

• omarchy-update
• omarchy-update-analyze-logs
• omarchy-update-available
• omarchy-update-available-reset
• omarchy-update-branch
• omarchy-update-confirm
• omarchy-update-firmware
• omarchy-update-git
• omarchy-update-keyring
• omarchy-update-perform
• omarchy-update-restart
• omarchy-update-system-pkgs
• omarchy-update-time
• omarchy-update-without-idle

upload (1)

• omarchy-upload-log

version (4)

• omarchy-version
• omarchy-version-branch
• omarchy-version-channel
• omarchy-version-pkgs

voxtype (5)

• omarchy-voxtype-config
• omarchy-voxtype-install
• omarchy-voxtype-model
• omarchy-voxtype-remove
• omarchy-voxtype-status

webapp (4)

• omarchy-webapp-handler-hey
• omarchy-webapp-handler-zoom
• omarchy-webapp-install
• omarchy-webapp-remove

windows (1)

• omarchy-windows-vm