# Add Theme

> Add a theme pack or match a wallpaper to an existing theme in the dotfiles theme system (bin/theme). Use when the user pastes a theme repo URL or image, says "add this theme", "new theme pack", or wants another entry for theme next to cycle.

- Skill: `nicknisi/add-theme` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nicknisi/add-theme`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nicknisi/add-theme/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: nicknisi (https://skillmd.com/u/nicknisi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nicknisi/add-theme

---


# Add a theme pack

One command themes everything: `bin/theme <name>` renders the pack into
`~/.local/state/theme/current/theme/` and nudges every consumer. A pack is
`themes/<name>/` and needs only:

- `colors.toml` — the contract. Either style:
  semantic (`mode`, `accent`, `background`, `foreground`, `muted`, `red`,
  `bright_red`, `dark_background`, ...) or ANSI (`accent`, `background`,
  `foreground`, `color0`-`color15`). `bin/theme-color -f colors.toml --all`
  shows the full set after aliasing and derivation; anything missing is
  mixed from what is there.
- `backgrounds/` — images. `theme <name> [N]` picks the Nth (sorted by
  name), `theme bg next` cycles. Name them `<index>-<description>.<ext>`;
  the fzf picker previews the filename.
- `theme.conf` — `TAGLINE="one line of whimsy"` (printed on switch, shown
  in the tmux cheat sheet). Optional but every pack has one.
- `icons.theme` — optional, a GTK icon theme name (Yaru-* is common);
  applied on Linux only if that icon set is installed.

Every app file (ghostty, kitty, wezterm, tmux, nvim, btop, starship, pi,
claude, hyprland borders, hyprlock, wofi, sketchybar, borders, slack) is
rendered from `themes/templates/*.tpl`. A pack may ship a file under the
same name to hand-tune one app (`hyprland.lua` for a gradient border,
`btop.theme`, ...); it wins over the template. Do NOT hand-author the rest.

Work directly in the repo (subagent worktrees don't see uncommitted
theme files and have flipped the user's live theme by running theme from
the wrong tree — do NOT run theme for validation until told, and never
from a worktree).

## Sources

- **An existing theme repo** (any `themes/<name>/` laid out as above):
  copy `colors.toml`, `backgrounds/`,
  `icons.theme`. Skip `neovim.lua`, `vscode.json`, `preview*.png`,
  `unlock.png`, `shell*.toml`, `keyboard.rgb`, `chromium.theme`. Keep a
  shipped `btop.theme`; keep a shipped `hyprland.lua` only if it is plain
  `hl.config` (the `o.window(...)` helper style some repos use does not
  exist here). An
  older theme with only `alacritty.toml` and no `colors.toml`: transcribe
  its `[colors.*]` into ANSI-style `colors.toml`.
- **Just a wallpaper**: first run `bin/theme adopt <image>`. It compares the
  extracted palette with every existing pack and, when the closest score is
  60 or lower, copies the image into that pack's `backgrounds/` with the next
  numeric prefix. A weaker match changes nothing and prints the three closest
  packs. Then use `bin/theme from-image <name> <image>` to create a new pack;
  it writes `colors.toml` + `backgrounds/` + an empty `theme.conf`. Both
  commands use heuristic hue mapping, so eyeball the result.

Then write `theme.conf` with a TAGLINE in the house style (see
`themes/*/theme.conf`: short, lower-case, a little wry).

## Validate (no theme run)

```
bin/theme-color -f themes/<name>/colors.toml --all        # no error, sane mode
bin/theme-color -f themes/<name>/colors.toml --name <name> --render /tmp/x themes/templates/*.tpl
jq empty /tmp/x/*.json; bash -n /tmp/x/*.sh
ghostty +validate-config --config-file=/tmp/x/ghostty.conf
```
A rendered file containing `{{` means a template names a key the resolver
does not produce; fix the template, not the pack.

## Hand verification to the user or ask before switching

`theme <name> [N]`, then: `tmux show-option -gqv @thm_pink` == accent;
`cat ~/.local/state/theme/current/mode`; `jq -r .theme ~/.claude/settings.json`
== `custom:<name>`. Linux: `hyprctl getoption general:col.active_border`,
`gsettings get org.gnome.desktop.interface color-scheme`. macOS: sketchybar
border colour, wallpaper after a few seconds. Pi applies on next launch.

## Commit on the active theme branch and push.

## Removing a theme

`git rm -r themes/<name>/`, then `theme <other>`. The rendered
`~/.pi/agent/themes/<name>.json` and `~/.claude/themes/<name>.json` can go
too.