Refine the Omarchy agent skill for installed systems

[Whamp]

Omarchy installs this skill for agents running on users' machines. Most requests involve operating or customizing the user's live system from an arbitrary directory, not developing Omarchy from inside its repository. The skill therefore needs to work as an OS operator manual without relying on repository context.

The current guide centers on customization and keeps routing, command examples, system operations, troubleshooting, and contribution instructions together in the entry file. It also lacks a consistent way to confirm risky actions, verify the requested behavior, and recover from a failed change. Those omissions matter when the agent is acting directly on the user's desktop and configuration.

The revised entry file routes each request to a focused guide. It tells the agent to inspect the installed system, distinguish package-owned files from user-owned state, confirm destructive actions, verify observable behavior, and report anything it could not verify.

Focused guides cover system commands and packages, Hyprland, the Quickshell desktop, themes, terminals, hooks, capture and sharing, troubleshooting, and issue reporting. Each guide defines how to apply the change, verify it, and recover from failure. Upstream source work hands off to a cloned repository and its AGENTS.md instead of carrying repository-development instructions in the installed skill.

Verification (It's just markdown so . . . )

• Parsed the directory as one installable omarchy skill
• Confirmed that every relative Markdown link resolves and SKILL.md routes to every guide

[Copilot]

Pull request overview

Refactors the installed Omarchy agent skill into an OS operations manual with focused routing, verification, safety, and recovery guidance.

Changes:

• Introduces focused guides for system operations, terminals, troubleshooting, and issue reporting.
• Expands customization guides with verification and recovery workflows.
• Separates installed-system operations from upstream development.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
SKILL.md	Defines the core operating loop and guide routing.
system.md	Covers packages, updates, setup, reminders, and power.
troubleshooting.md	Adds diagnosis, recovery, and escalation guidance.
reporting-issues.md	Routes support, bugs, and upstream work.
terminals.md	Adds terminal configuration workflows.
theming.md	Expands theme and font customization guidance.
plugins.md	Expands shell, plugin, menu, and idle guidance.
hyprland.md	Adds structured Hyprland configuration workflows.
hooks.md	Expands hook implementation and recovery guidance.
capture.md	Adds verification and privacy guidance for capture and sharing.
contributing.md	Removes superseded contribution guidance.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (8)

default/agents/skills/omarchy/troubleshooting.md:50

• omarchy reinstall contains interactive gum confirm prompts for both the reinstall and an optional reboot. Chat confirmation does not answer those prompts, so an agent running this from a noninteractive command harness can block or fail unless the guide explicitly launches it in a visible terminal.

Use `omarchy reinstall` only when narrower diagnosis and component recovery
cannot restore the installation. Before running it, obtain confirmation and
state which user configuration and system state it may replace.

default/agents/skills/omarchy/system.md:35

• omarchy-pkg-missing succeeds when any argument is absent, so one removed package can make this check pass while another named package is still installed. Check each package separately before declaring a multi-package removal complete.

`omarchy pkg missing <packages...>` must confirm the named packages are absent.

default/agents/skills/omarchy/theming.md:73

• This completion condition excludes supported font changes in the same guide. omarchy font set updates user-owned terminal configs and ~/.config/fontconfig/fonts.conf, all outside ~/.config/omarchy/, so a successful font request can never satisfy this checklist.

- every changed file is under `~/.config/omarchy/`;

default/agents/skills/omarchy/SKILL.md:137

• A refresh does not always leave a backup: omarchy-refresh-config creates one only for an existing file and deletes it when the old file matches the packaged default. This rule therefore makes a no-op refresh or restoration of a missing file impossible to complete.

A reset is complete only when its backup exists and the restored component has
been applied and verified.

default/agents/skills/omarchy/plugins.md:93

• omarchy refresh shell produces no backup when shell.json is absent or already matches the packaged default. Require confirmation only for an expected backup; otherwise a valid shell recovery cannot meet this completion rule.

Confirm the backup, check the restored JSON, and observe the affected shell
surface before reporting recovery complete.

default/agents/skills/omarchy/troubleshooting.md:46

• Refreshes of missing or already-default files legitimately produce no backup, so requiring one here can leave recovery permanently incomplete even when the command succeeded. Only require a backup when a differing existing file was replaced.

This issue also appears on line 48 of the same file.

Obtain user confirmation immediately before refreshing. State the exact target
path, what customization will be replaced, and where the backup should appear.
Afterward, confirm the backup exists, apply the restored component, and repeat
the original reproduction.

default/agents/skills/omarchy/hyprland.md:110

• omarchy-refresh-hyprland overwrites only the fixed set of standard files listed in that script; it does not reset arbitrary user Lua modules under ~/.config/hypr/. Calling this “all user Lua files” can make an agent incorrectly report that custom modules were reset.

With user confirmation, reset all user Lua files with:

default/agents/skills/omarchy/hyprland.md:117

• Neither refresh is guaranteed to create a backup when its target is missing or unchanged. Requiring a created backup here conflicts with valid successful refreshes; confirm it only when a differing existing file was replaced.

Reset `hyprsunset.conf` separately with `omarchy refresh hyprsunset`. Confirm the
created backup, reload the owner, and repeat the relevant completion checks.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (4)

default/agents/skills/omarchy/SKILL.md:137

• A refresh does not always leave a backup: omarchy-refresh-config creates none when the target is absent and removes it when the existing file already matches the default. Requiring a backup to exist therefore makes a successful no-op or first-time refresh impossible to complete. Require verification only for backups the command reports creating.

A reset is complete only when its backup exists and the restored component has
been applied and verified.

default/agents/skills/omarchy/troubleshooting.md:46

• omarchy-refresh-config does not create a backup when the target was absent and deletes the backup when the old file was identical to the default. This unconditional check incorrectly treats those valid refreshes as failed; verify only a backup actually reported by the command.

Obtain user confirmation immediately before refreshing. State the exact target
path, what customization will be replaced, and where the backup should appear.
Afterward, confirm the backup exists, apply the restored component, and repeat
the original reproduction.

default/agents/skills/omarchy/plugins.md:93

• A shell refresh can legitimately produce no backup when shell.json was absent or already matched the packaged default. An unconditional backup check would prevent the agent from completing recovery in those cases; condition it on the command reporting that a backup was saved.

Confirm the backup, check the restored JSON, and observe the affected shell
surface before reporting recovery complete.

default/agents/skills/omarchy/hyprland.md:117

• Each file refreshed by omarchy refresh hyprland gets a backup only if a differing user file already existed; absent or unchanged files leave no backup. Requiring a created backup makes valid first-time or no-op recovery fail the stated completion rule.

Reset `hyprsunset.conf` separately with `omarchy refresh hyprsunset`. Confirm the
created backup, reload the owner, and repeat the relevant completion checks.

[WhiskeyTuesday]

Flagging one thing in case it's useful — no strong opinion on how (or whether) to address it here.

The new default/agents/skills/omarchy/troubleshooting.md carries an invocation the rewrite otherwise moved away from:

omarchy debug --no-sudo --print
The same diagnostic report is written to `/tmp/omarchy-debug.log`.

That command exits 127 on a production install today — omarchy-debug ships from omarchy-settings into /usr/bin but is not symlinked into /usr/share/omarchy/bin, so the dispatcher can't route it (context in #7185; same symptom in #6977 and #7060). An agent following the guide to gather diagnostics currently gets Unknown Omarchy command.

Two ways this could resolve, both fine:

1. Spell the binary hyphenated in the guide (omarchy-debug --no-sudo --print), which works on both production and dev-link installs regardless of anything else.
2. Leave the routed form as-is. There's a draft PR against the dispatcher (adds a /usr/bin fallback for sibling-package binaries) that would make the routed form work if it lands and is accepted — but that's speculative, so it's really a decision for whoever's shepherding this PR.

Happy to send a small commit for option 1 if that's easier than a follow-up.

[Whamp]

Good catch—thanks for tracing this and for the clear explanation.

Since the skill is intended to reflect behavior on currently installed systems, I changed the troubleshooting guide to use omarchy-debug --no-sudo --print. That works on production today and will remain valid if #9290 is merged.

I also updated the branch against the current quattro. Appreciate the offer.