Repository navigation
Conversation
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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 reinstallcontains interactivegum confirmprompts 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-missingsucceeds 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 setupdates 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-configcreates 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 shellproduces no backup whenshell.jsonis 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-hyprlandoverwrites 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.
There was a problem hiding this comment.
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-configcreates 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-configdoes 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.jsonwas 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 hyprlandgets 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.
|
Flagging one thing in case it's useful — no strong opinion on how (or whether) to address it here. The new That command exits 127 on a production install today — Two ways this could resolve, both fine:
Happy to send a small commit for option 1 if that's easier than a follow-up. |
Use the production-safe hyphenated binary for diagnostic collection.
|
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 I also updated the branch against the current |
Carries quattro's changes to the skill into the restructured guides: the shipped skill now points at omacom/omarchy, screenshots go through Omasnap (scroll mode, preview, --editor, OMASNAP_SCREENSHOT_DIR), the screen-recording debug log lives under $XDG_RUNTIME_DIR rather than /tmp, rebinding uses o.rebind, bindings can target menu routes and shell panels, and the hook table matches when omarchy-update and omarchy-refresh-pacman now run post-update and pre-refresh-pacman. contributing.md stays deleted; its routing lives in reporting-issues.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A heading ran into the list above it, and the overlay section opened with a dangling "Both" and then restated the overlay rule the list had already given. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
omarchy-refresh-config keeps a backup only when the replaced file differed and makes none when restoring a missing one, so requiring a backup made a correct restore of a deleted file impossible to complete. omarchy refresh hyprland resets six named Lua files, not every user module. And omarchy hook runs every script for an event outside the environment the event sets up, so verifying or recovering one hook through it could run unrelated scripts, and a pre-refresh-pacman hook without its sudo revocation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-Authored-By: Codex Medium <noreply@openai.com>
Not every refresh goes through omarchy-refresh-config: refresh pacman writes fixed .bak files unconditionally, and refresh hyprland overwrites its toggle state with no backup at all, so a rule demanding a backup for every differing file could not be met. The agent now reads the component's command, says which paths are backed up before asking, and checks the backups the command reported. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-Authored-By: Codex Medium <noreply@openai.com>
|
Reviewed at I pushed four commits to the branch:
Codex Medium reviewed it over three rounds. The backup, hook and refresh-scope defects above came from its review, and I confirmed each against the code before fixing it. Its last round found nothing open; that is agreement with my reading, and its independence is not guaranteed. One thing I left alone: Eight open pull requests edit this skill in its old shape: #13389, #13267, #13228, #13140, #13139, #13138, #13056 and #13003. Whichever lands second will need rebasing. It is waiting on the maintainer. |
|
Thanks for the review, happy to update as needed to catchup with main but it looks like omarchybot has already done most of it. |
|
@Whamp Really want to see this merged in ASAP. The other PRs can piggy back off it. We desperately need the dupe search instructions and a symlink to contributing.md. 🤞🏼 |
|
I agree i think it would be helpful |
Quattro's omacom#5925 folded the skill's "When This Skill MUST Be Used" section into the frontmatter description. This branch had already replaced that body, so its rewrite stands; the description keeps the rewrite's wording and gains the triggers omacom#5925 made sure survived: editing any file in ~/.config/ and its named subdirectories, window behavior, and screen recordings. Quattro's Plugin UI Safety section merged into plugins.md unchanged. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… theme details The merged description had dropped "layer rules", one of the triggers omacom#5925 kept. omarchy refresh hyprland also replaces ~/.config/hypr/.luarc.json, which the recovery list left out. And omarchy-theme-set never copies a symlink from a cloned theme, at any depth, so "everything else is kept" was not true of them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-Authored-By: Codex Medium <noreply@openai.com>
stage_installed_theme and stage_installed_dir glob "$source"/* without dotglob, so a hidden file or directory in a cloned theme never reaches the staged theme. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-Authored-By: Codex Medium <noreply@openai.com>
|
Removing every changed overlay file also removes a user's earlier palette when the task edited a file that already existed. SKILL.md has the agent keep a timestamped copy before editing an existing file, so recovery restores that copy and deletes only what the task created. Raised by Greptile on the pull request. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
This had stopped merging after The merge. #5925 moved the old "When This Skill MUST Be Used" section into the frontmatter description. This branch already replaces that section, so your rewrite stays. The description keeps your wording and adds back the triggers #5925 kept on purpose: editing any file in Fixes pushed (wording only, each checked against the source):
What was checked. This is documentation only, so nothing was run. Every |
|
@dhh @ryanrhughes can we merge this, seems like it would help maintenance and user experience on a lot of fronts. |
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.mdinstead of carrying repository-development instructions in the installed skill.Verification (It's just markdown so . . . )
omarchyskillSKILL.mdroutes to every guide