omarchy-theme-ops

name	omarchy-theme-ops
description	Safely create and maintain custom Omarchy themes with Herdr-aware focus styling.

When to use

Use this skill for end-user Omarchy theme work:

• Creating or tuning themes under ~/.config/omarchy/themes/<theme-name>/.
• Adjusting terminal/app theme templates produced by Omarchy theme application.
• Keeping Herdr focus, tab, and pane styling aligned with the active Omarchy theme.
• Debugging mismatches between Omarchy colors.toml, Ghostty/Kitty terminal colors, and Herdr UI accents.

Do not use it for Omarchy source development.

Safe paths

• Edit custom themes only under ~/.config/omarchy/themes/<theme-name>/.
• Edit automation only under ~/.config/omarchy/hooks/.
• Read ~/.local/share/omarchy/ when needed to understand stock scripts/templates, but never edit it.
• Keep AOC repository Herdr defaults in herdr/config.toml; keep user runtime state in ~/.config/herdr/config.toml.
• Do not rely on .aoc/skills for OMP runtime loading; that path is legacy migration input only.

Theme workflow

1. Pick a slugged theme directory name, e.g. lookout-ember.
2. Create or update ~/.config/omarchy/themes/<slug>/colors.toml and backgrounds in the same directory.
3. If deriving from an image, sample the dominant dark base, readable foreground, warm/cool accents, and ANSI-like functional colors separately. Preserve terminal semantics instead of forcing every highlight into one color.
4. Apply with omarchy theme set "Theme Name". Use OMARCHY_THEME_SKIP_BACKGROUND=1 during palette-only refreshes when the wallpaper should not cycle.
5. Inspect generated files under ~/.config/omarchy/current/theme/ after application; those are generated runtime outputs, not the source of truth.

Required colors.toml keys

Every custom theme should provide:

accent = "#rrggbb"
cursor = "#rrggbb"
foreground = "#rrggbb"
background = "#rrggbb"
selection_foreground = "#rrggbb"
selection_background = "#rrggbb"
color0 = "#rrggbb"
color1 = "#rrggbb"
color2 = "#rrggbb"
color3 = "#rrggbb"
color4 = "#rrggbb"
color5 = "#rrggbb"
color6 = "#rrggbb"
color7 = "#rrggbb"
color8 = "#rrggbb"
color9 = "#rrggbb"
color10 = "#rrggbb"
color11 = "#rrggbb"
color12 = "#rrggbb"
color13 = "#rrggbb"
color14 = "#rrggbb"
color15 = "#rrggbb"

Semantic guidance:

• accent is the theme's active/focus color.
• selection_background may match accent, but can be calmer if selection becomes too loud.
• color4/color12 should remain blue-ish where possible.
• color6/color14 should remain cyan-ish where possible.
• Do not change ANSI cyan solely to fix Herdr focus styling; Herdr focus should use accent.

Herdr focus styling

AOC Herdr should use:

[theme]
name = "terminal"

This keeps panels, text, and backgrounds following the terminal palette generated by Omarchy. Herdr active tab/pane focus is synchronized separately through:

~/.config/omarchy/hooks/theme-set.d/herdr-terminal-accent

The hook reads ~/.config/omarchy/current/theme/colors.toml, extracts accent, writes it to [ui] accent in ~/.config/herdr/config.toml, preserves unrelated settings/keybindings, and reloads Herdr only when a Herdr server is running.

Expected user config shape:

[ui]
accent = "#theme-accent"

[theme]
name = "terminal"

OMP visibility contract

Canonical project skill source is .omp/skills/<name>/SKILL.md.

For this skill to be available to OMP agents, ensure .omp/skills/omarchy-theme-ops/SKILL.md exists and run:

aoc-skill sync --root .

Run skill validation after changes:

aoc-skill validate --root .

Verification

Use focused checks:

omarchy theme current
omarchy theme list
omarchy theme set "Lookout Ember"
herdr server reload-config
aoc-skill validate --root .

Read these files after applying a theme:

• ~/.config/omarchy/current/theme/colors.toml
• ~/.config/omarchy/current/theme/ghostty.conf
• ~/.config/herdr/config.toml
• ~/.omp/agent/config.yml
• .omp/skills/omarchy-theme-ops/SKILL.md

Visual QA checklist:

• Herdr active tab and focused pane border use the theme accent, not muted ANSI cyan/teal unless cyan is intentionally the accent.
• Herdr background/text still follow the terminal palette.
• Ghostty and Kitty generated colors match colors.toml semantics.
• Yazi directory/file colors remain readable; readability is controlled by ANSI slots, not the Herdr UI accent hook.
• Selection background has enough contrast and is not distractingly saturated.