Skip to content

Refine the Omarchy agent skill for installed systems - #6718

Open
Whamp wants to merge 13 commits into
omacom:quattrofrom
Whamp:refine-omarchy-skill
Open

Whamp wants to merge 13 commits into
omacom:quattrofrom
Whamp:refine-omarchy-skill

Conversation

@Whamp

@Whamp Whamp commented Aug 11, 2026 •

Copy link
Copy Markdown
Contributor

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 AI balanced review requested due to automatic review settings August 11, 2026 19:26

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread default/agents/skills/omarchy/SKILL.md Resolved
Copilot AI review requested due to automatic review settings August 11, 2026 20:33

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 AI review requested due to automatic review settings August 11, 2026 22:09

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown

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 added 2 commits August 30, 2026 21:26
Use the production-safe hyphenated binary for diagnostic collection.
@Whamp

Whamp commented Aug 31, 2026

Copy link
Copy Markdown
Contributor Author

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.

omarchybot and others added 4 commits September 28, 2026 03:00
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>
@omarchybot omarchybot added verified Omarchy Triage has verified that this issue is ready for final review ready Good to merge labels Sep 28, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at 07a815a4. This is documentation only, so nothing was run. Every command, flag, path and behaviour the rewritten skill names was checked against bin/, config/ and default/ on quattro, and it holds up. The routing, the ownership table and the Privilege Escalation section that the root AGENTS.md points at are all intact.

I pushed four commits to the branch:

  • Merged quattro. The branch conflicted in five files, because quattro has changed the skill since this was written. I carried those changes into the new layout:
    • links point at omacom/omarchy
    • screenshots go through Omasnap: scroll mode, the preview, --editor, OMASNAP_SCREENSHOT_DIR
    • the screen-recording debug log is under $XDG_RUNTIME_DIR, not /tmp
    • o.rebind, plus { menu = ... } and { panel = ... } bindings
    • the hook table now matches where omarchy-update and omarchy-refresh-pacman actually run post-update and pre-refresh-pacman
  • theming.md: a heading ran into the list above it, and the overlay section opened with a dangling "Both".
  • Backup rules. The skill required a backup before a reset counted as complete. omarchy refresh config makes none when it restores a missing file, and none when the content was identical. refresh hyprland overwrites its toggle state with no backup at all. The agent now reads the refresh command first and says which paths will be backed up.
  • Hooks. omarchy hook <name> runs every script for that event, outside the environment the event sets up. A pre-refresh-pacman hook run that way loses its sudo revocation, so verification and recovery no longer tell the agent to run it unconditionally. refresh hyprland is also described as resetting its six named Lua files, not every user module.

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: theming.md's "any *.lua" is dropped from an installed theme is already on quattro. omarchy-theme-set filters only the theme's top level, so nested Lua files are kept.

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.

@omarchybot omarchybot added ready Good to merge and removed ready Good to merge labels Sep 28, 2026
@Whamp

Whamp commented Sep 28, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the review, happy to update as needed to catchup with main but it looks like omarchybot has already done most of it.

@codenamekt

Copy link
Copy Markdown

@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. 🤞🏼

@Whamp

Whamp commented Oct 1, 2026

Copy link
Copy Markdown
Contributor Author

I agree i think it would be helpful

@omarchybot omarchybot removed ready Good to merge verified Omarchy Triage has verified that this issue is ready for final review labels Oct 11, 2026
omarchybot and others added 3 commits October 11, 2026 08:07
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>
@omarchybot omarchybot added the verified Omarchy Triage has verified that this issue is ready for final review label Oct 11, 2026
@greptile-apps

greptile-apps Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 5/5

[Low impact] The PR appears safe to merge; the follow-up fixes the earlier theme recovery issue.

Summary

The PR turns the installed Omarchy skill into a guide for operating the user's live system.

  • Agents follow one path to operate a live Omarchy system.
  • The system guide covers packages, updates, setup, reminders, and power actions.
  • The Hyprland guide covers configuration, checks, and recovery.
  • The Quickshell guide covers bar, plugin, menu, and idle changes.
  • The theme guide explains selecting, customizing, and restoring themes.
  • The terminal guide covers user settings and checks for Alacritty, Foot, Kitty, and Ghostty.
  • The hook guide explains event scripts, testing, and recovery.
  • The capture guide adds checks for screenshots, recordings, and OCR.
  • The sharing guide covers consent and receipt checks for file transfers.
  • The troubleshooting guide adds a path from diagnosis to recovery or escalation.
  • Issue reporting and upstream development now have separate routes.

Reviews (2) · Last reviewed commit: "Reverse an overlay by restoring what was..." · Reviewed by Greptile

@omarchybot omarchybot added the ready Good to merge label Oct 11, 2026
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>
@omarchybot

Copy link
Copy Markdown
Collaborator

This had stopped merging after quattro moved, so I merged quattro into the branch and re-checked the skill against current code. It is at 452bdc27 now.

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 ~/.config/ and the subdirectories it names, window behavior, layer rules and screen recordings. The Plugin UI Safety section from #7792 merged into plugins.md unchanged.

Fixes pushed (wording only, each checked against the source):

  • hyprland.md: omarchy refresh hyprland also replaces ~/.config/hypr/.luarc.json, so it is now in the recovery list.
  • theming.md: omarchy-theme-set drops symlinks at any depth from a cloned theme, and its globs skip hidden files and directories, so "everything else is kept" now names both exceptions.
  • theming.md: Greptile's comment on reversing an overlay is right. Deleting every changed overlay file also deletes a user's earlier palette if the task edited a file that was already there. Recovery now restores the timestamped copy SKILL.md already says to keep, and deletes only files the task created.

What was checked. This is documentation only, so nothing was run. Every omarchy command and executable the skill names exists on quattro. The behaviour it describes still matches the files quattro changed since the last review: hook placement in omarchy-update and omarchy-refresh-pacman, the screen recording debug log, factory reset's @factory requirement, and cloned-theme staging. Nothing outside the skill still links to the removed contributing.md. Codex Medium reviewed the merge and each fix over four rounds. It found the layer-rules, .luarc.json and hidden-file problems, and its last round was clean. CI is green. It is waiting on the maintainer.

@omarchybot omarchybot removed verified Omarchy Triage has verified that this issue is ready for final review ready Good to merge labels Oct 11, 2026
@Whamp

Whamp commented Oct 17, 2026

Copy link
Copy Markdown
Contributor Author

@dhh @ryanrhughes can we merge this, seems like it would help maintenance and user experience on a lot of fronts.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants