Skip to content

Tell the agent skill to use omarchy pkg and omarchy update, not pacman - #11466

Open
daja77 wants to merge 2 commits into
omacom:quattrofrom
daja77:skill-package-management
Open

daja77 wants to merge 2 commits into
omacom:quattrofrom
daja77:skill-package-management

Conversation

@daja77

@daja77 daja77 commented Sep 12, 2026

Copy link
Copy Markdown

Why

The manual is explicit that Omarchy owns package management: Other Packages documents omarchy pkg add / omarchy pkg drop, and Updates warns against running pacman -Syu or yay -Syu directly because it risks missing the config updates that support newer library versions. 00-omarchy-update-guard.hook already enforces the update half at the libalpm level.

The installed agent skill did not carry any of that. It named omarchy pkg add twice in passing — one table row and one line in the decision framework — never mentioned omarchy pkg drop, and never said that pacman, yay, and paru are off the supported path. An agent reading it has no reason not to reach for sudo pacman -S.

Its triggers also omitted packages and updates entirely, so the skill often never loaded for "install X" or "update my system" in the first place — the same gap #8257 fixed for ~/.config/systemd/user/.

This surfaced on a real 4.0.3 install: the agent kept offering bare pacman commands, and the user had to point at the manual to correct it.

What

  • Triggers — add packages, updates, and the raw tool names so the skill loads for this work at all.
  • New "Package Management" section — the wrapper table (pkg add / pkg aur add / pkg drop / the fuzzy-finder pickers / present / missing / omarchy update), a pointer to prefer omarchy install ... where an installer exists, and the pacman -Syu prohibition with what omarchy update actually does that a bare upgrade skips.
  • The guard's bypass is documented as the user's to invoke deliberately, not something an agent should reach for on its own.
  • Read-only queries (pacman -Q, -Qi, -Ql, -Qo, -Si, -Ss, -Sl, yay -Ss/-Si) are called out as safe to run directly, so the rule doesn't over-fire on inspection — the skill's own omarchy pkg present/missing are thin wrappers around pacman -Q.
  • Decision framework and examples updated to match.

Docs only; no behavior change.

Related

#6718 restructures the skill and adds a "Packages and Optional Software" section to a new system.md. It lists the same wrappers but does not prohibit the raw tools, mention the update guard, or extend the triggers. This change is scoped to the current SKILL.md so it applies cleanly either way; happy to fold it into system.md instead if #6718 lands first.

Testing

./test/cli passes. ./test/all reports 6 failing files under test/shell.d/ (bar-icon-geometry, config, locate, runtime-smoke, snapper, unowned-system-paths), but all 6 fail identically on the unmodified base commit in this environment — pre-existing and untouched by a markdown-only change.

🤖 Generated with Claude Code

The skill named `omarchy pkg add` twice in passing but never said that
`pacman`, `yay`, and `paru` are off the supported path, never mentioned
`omarchy pkg drop`, and carried no warning against `pacman -Syu`. Its
triggers also omitted packages and updates entirely, so the skill often
did not load for "install X" or "update my system" in the first place.

Add a Package Management section covering the wrappers, the update guard
and its deliberate bypass, and the read-only pacman queries that need no
wrapper. Extend the triggers, the decision framework, and the examples to
match.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@omarchybot omarchybot added the documentation Improvements or additions to documentation label Sep 27, 2026
@phil71x

phil71x commented Sep 28, 2026

Copy link
Copy Markdown

+1 on this. Agents rarely load the skill for system tasks beyond desktop config, even though the skill body covers them. It would help to widen the description to cover general system administration on Omarchy (installing and removing software, default apps, updates, troubleshooting), in whatever form you think fits best.

@omarchybot omarchybot added verified Omarchy Triage has verified that this issue is ready for final review ready Good to merge labels Sep 30, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

Reviewed at a5dda7d, nothing found. This touches one Markdown file, so nothing was run: I checked each thing it names against current quattro, which has not changed this file since the branch point.

  • Every omarchy pkg route in the new table (add, aur add, drop, install, aur install, remove, present, missing) resolves through bin/omarchy to a bin/omarchy-pkg-* command that does what its row says.
  • The list of what omarchy update does matches the stages in bin/omarchy-update.
  • 00-omarchy-update-guard.hook runs omarchy-update-pacman-guard, which refuses any sync that includes -u and accepts exactly the OMARCHY_ALLOW_DIRECT_PACMAN=1 bypass shown. None of the listed read-only queries carry -u, so the guard never stops them.
  • omarchy install --help lists the installers, and the section agrees with manual/29-other-packages.md, manual/30-updates.md and the skill's own Privilege Escalation section.

Codex Medium reviewed the same diff as a second opinion. It found nothing wrong and agreed on each point above. It had access to this review's reasoning, so its agreement is not guaranteed to be independent.

Related, and not duplicates: #6718 restructures the skill and adds its own packages section, and #11804 changes the Privilege Escalation section to have agents retry with pkexec instead of handing a command back to the user. That sits uneasily beside this PR's "run these in a visible terminal". Whichever lands second will need reconciling with the others.

Nothing is waiting on you. This now waits on the maintainer.

@omarchybot omarchybot removed ready Good to merge verified Omarchy Triage has verified that this issue is ready for final review labels Oct 11, 2026
The only conflict was the skill's trigger list, which quattro widened (window behavior, widgets, fonts, screen recording, appearance changes) while this branch added the package-management triggers. Keep quattro's list and append the package sentence to it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@omarchybot omarchybot added the verified Omarchy Triage has verified that this issue is ready for final review label Oct 11, 2026
@omarchybot

Copy link
Copy Markdown
Collaborator

This stopped merging cleanly once quattro widened the skill's trigger list, so I merged quattro into the branch as 472700a. The only conflict was the description: triggers: I kept quattro's longer list and added your package sentence after it, so nothing from either side is lost. The rest of your change came across unchanged. It is a merge commit, not a rebase, so your commit is untouched.

omarchy update has been largely rewritten since this was opened, so I re-checked everything the new section says against current quattro rather than relying on the earlier review. It all still holds:

  • Every omarchy pkg row maps to a bin/omarchy-pkg-* command that does what the row says.
  • Each step listed for omarchy update (snapshot, keyrings, system and AUR packages, migrations, post-update hooks, mise, orphan pruning, restart check) is still in the new bin/omarchy-update.
  • 00-omarchy-update-guard.hook still refuses a sync with -u. The bypass shown is the same one the guard prints. None of the read-only queries trigger it.
  • "Run these in a visible terminal" agrees with the skill's current Privilege Escalation section.

Nothing was run, since this is one Markdown file. Codex Medium reviewed the merged result as a second opinion and found nothing wrong. It had access to this review's reasoning, so its agreement is not guaranteed to be independent.

Overlaps for whoever lands second: #9227 rewrites the same decision-framework line to require an explicit request before any AUR install, and #6718, #11804 and #14499 also touch package or privilege guidance in this skill.

This now waits on CI finishing and then on the maintainer. Nothing is needed from you.

@greptile-apps

greptile-apps Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerConfidence Score: 4/5

[Low impact] Updates agent skill documentation for package management.

This appears safe to merge, with a non-blocking improvement to the removal guidance.

Findings

  1. P2 Removal leaves setup behind ▶

Summary

This documentation-only change tells agents to use Omarchy’s package and update commands.

  • The Omarchy skill guides package work through Omarchy commands.

Acknowledgment: daja77 explicitly intends to document the update guard’s bypass for the user to invoke deliberately, not for an agent to use on its own.

Reviews (1) · Last reviewed commit: "Merge quattro into skill-package-managem..." · Reviewed by Greptile

Comment on lines +215 to +217
When Omarchy ships an installer for the software, prefer it over a bare
`omarchy pkg add` — it also wires up configuration, services, and launcher
entries. Check `omarchy install --help` before falling back to `omarchy pkg`.

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.

P2 Removal leaves setup behind

The new guidance prefers dedicated installers, but only points to omarchy pkg drop for removal. For software with a dedicated remover, this can leave broken settings behind. For example, dropping voxtype-bin leaves its user service enabled and can leave voxtype selected as the dictation backend.

Prefer dedicated removers too: check omarchy remove --help before falling back to package removal.

Suggested change
When Omarchy ships an installer for the software, prefer it over a bare
`omarchy pkg add` — it also wires up configuration, services, and launcher
entries. Check `omarchy install --help` before falling back to `omarchy pkg`.
When Omarchy ships an installer for the software, prefer it over a bare
`omarchy pkg add` — it also wires up configuration, services, and launcher
entries. Check `omarchy install --help` before falling back to `omarchy pkg`.
Likewise, prefer a dedicated remover when one exists so services, settings,
and launcher entries are cleaned up. Check `omarchy remove --help` before
falling back to `omarchy pkg drop`.

Knowledge Base Used: Package management and curated installs

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

@jandrusk

Copy link
Copy Markdown

Good alignment with the manual's omarchy pkg / omarchy update guidance. Related skill/doc fixes in flight: #13817 / #14129 (omarchy-debug wording) and the #7185 dispatcher cluster that #11425 also hits. This change still stands on its own.

@omarchybot omarchybot removed the verified Omarchy Triage has verified that this issue is ready for final review label Nov 19, 2026
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.

4 participants