Hermes Skin Authoring

IDENTITY: Designer.Themer. Create, combine, and troubleshoot Hermes TUI skins via YAML — colors, spinners, branding, ASCII banner art, tool emojis, and gradient color tags. Verify skin content from literal bytes on disk, not session memory. Law: BlockGroupedColorTags — per-character tags inflate source lines 14× causing vertical text wrapping. Group 2-4 chars per tag. WHENUSE: UserAsks{CreateSkin,ModifySkin,CombineSkins,ChangeTheme,CustomSkin,/skin}. ESPECIALLY:ImageToBannerHero{showMultipleWidthsBeforeCommitting}|SkinDeployment{move,copy,rename,replaceDefault}. NoSkip:PostChangeChecklist{nameMatch,configUpdate,noOrphans,/newOrRestart}. REDFLAGS: ActiveSkinVsProfileDefault->DontAssumeReadFileOrAsk|UnquotedQuestionMarkInToolEmojis->YAMLParseError|PerCharColorTagsInBanner->VerticalText{fix:blockGrouped}|/skinMidSession->PartialRender{recommend/new}|BannerHeroInflatesFile->ConsiderOmittingForMinimal. RATIONALIZATIONS: GuessActiveSkinFromConfig->Runtime/skinOverridesConfig|TrustSessionSummaryForSkinContent->ReadLiteralBytesOnDisk|UsePerCharGradientForWelcome->GroupedTagsProduceSameVisualAt65pctShorter. QUICKREF: Create{Method{FromScratch,CombineSkins,CloneModify}}->Build{Colors{hex palette}->Spinner{faces,verbs,wings}->Branding{welcome,goodbye,labels}->ToolEmojis->BannerLogo{pyfiglet+gradient}->BannerHero{jp2a+multiStopGradient}}->Deploy{MoveToDir,UpdateName,UpdateConfig,Restart}->Verify{YAMLValid{pyLoad},NameMatch{CaseSensitive},UnclosedTags,Indentation,RightDirectory,/skinTest}.

Hermes TUI skins are YAML files that define the entire visual identity of the CLI experience — colors, spinners, boot messages, ASCII art banners, tool emojis, and more. This skill covers the full skin YAML schema, how to create new skins, combine elements from multiple existing skins, switch between them, and troubleshoot common issues.

Where Skins Live

Skins are stored in YAML files. The canonical locations (in load order):

1. Global skins: ~/.hermes/skins/ — available to all profiles
2. Per-profile skins: ~/.hermes/profiles/<name>/skins/ — available only to that profile

Both directories function identically. The name of the skin is the name: field in the YAML frontmatter, not the filename (though they should match for clarity).

How the Desktop App Consumes Skins

The desktop app's Themes page merges THREE sources (verified in apps/desktop/src/themes/):

1. Built-in presets — hardcoded in the app (presets.ts: nous, etc.)
2. User themes — pasted via the app UI, stored in renderer localStorage (user-themes.ts, key hermes-desktop-user-themes-v1). Desktop-only; CLI/TUI never see these.
3. Backend-synced skins — the shared path. The Hermes backend resolves $HERMES_HOME/skins/*.yaml and pushes them to the desktop over JSON-RPC (gateway.ready, skin.changed; backend-sync.ts). skin.ts converts the skin palette into a desktop theme: it seeds from the load-bearing keys (background, foreground, accent, error) and derives all glass/shadcn surfaces by mixing toward bg/fg. A skin is single-mode; desktop picks .dark from background luminance.

Practical consequences:

• The desktop does NOT read YAML files itself — the backend does and pushes them. New skins not appearing → restart the backend/gateway and reload the app.
• Relaunch mechanics (macOS): the app is launched with hermes desktop from a terminal. Quit with Cmd+Q (closing just the window or terminal can leave the backend alive), then rerun hermes desktop. Skins are read at runtime by the backend on connect (gateway.ready) — no app rebuild ever needed for skin changes. If new skins still don't show after relaunch, a stale backend is still running: hermes gateway restart (or pkill -f hermes as the nuclear option) and relaunch.
• One skin file themes all three surfaces (CLI, TUI, desktop). There is no separate "desktop theme" file format; community "desktop theme packs" (e.g. CliffWade/hermes-desktop-theme-pack, 24 WCAG-AA-checked YAMLs) are just plain skins installed to ~/.hermes/skins/.
• $HERMES_HOME is profile-aware: if the desktop is connected to a profile's backend (e.g. senna), it sees ~/.hermes/profiles/senna/skins/, not the root ~/.hermes/skins/. Skins installed globally that don't show in the desktop usually means the desktop backend runs under a profile home — copy/symlink the YAMLs into the profile skins dir.
• Skins carry terminal-only keys (banner/spinner/completion) that the desktop converter ignores — a palette-only skin still works fine on desktop.

Skin YAML Schema

A skin has these top-level sections. All are optional — missing fields fall through to defaults.

name (string, required)

The skin identifier. Used with /skin <name> and hermes config set display.skin <name>.

description (string)

A one-liner describing the aesthetic, shown in skin listings.

colors (map of hex color strings)

The largest and most configurable section. Key color groups:

Color values can be:

• Quoted: "#A855F7" or "#8B0000"
• Single-quoted: '#D4A017'
• Unquoted: #6B21A8

Custom color keys can be added (e.g., blade_glow: "#EF0131") and referenced in the banner_logo or banner_hero sections, but they have no effect on UI chrome — the standard keys drive the actual terminal rendering.

spinner (map of arrays)

spinner:
  waiting_faces:         # Spinner frames while waiting for response
    - (☾)
    - (⚔)
  thinking_faces:        # Spinner frames while model is thinking/reasoning
    - (☾)
    - (⚔)
  thinking_verbs:        # Status text shown alongside spinner
    - entering the gate
    - drawing steel
  wings:                 # Paired bracket decorations around spinner
    - - ⟪☾
      - ☾⟫
    - - ⟪⚔
      - ⚔⟫

• waiting_faces and thinking_faces: usually 4-5 unique symbols each.
• thinking_verbs: 10-12 phrases that cycle. Should be present-tense actions.
• wings: each entry is a 2-element array [left, right]. Cycle randomly.

branding (map of strings)

branding:
  agent_name: "Shadow Monarch"     # Shown in the UI header
  welcome: "[#A855F7]A[/]RISE."   # Boot message with optional tag-based gradient coloring
  goodbye: "The dungeon has closed."  # Shown on exit
  response_label: " ☾ MONARCH "   # Badge before responses
  prompt_symbol: "☾ "             # Prefix at the input prompt
  help_header: "(☾) Commands"     # Header for /help output

Tag-based gradient coloring in welcome/goodbye: The welcome and goodbye strings support inline color tags for per-character gradients:

"[#A855F7]A[/][#A758F4]R[/][#A65CF2]I[/]SE."

Each character (or group) is wrapped in [#HEX]text[/]. By interpolating hex values between a start and end color, you create a smooth gradient across the message. The gradient technique:

1. Choose start and end hex colors
2. Generate N intermediate hex values (one per character/group)
3. Wrap each character: [#COLOR]char[/]

Quick Python one-liner for generating gradient welcome text:

python3 << 'PYEOF'
def lerp_color(c1, c2, t):
    r1, g1, b1 = int(c1[1:3], 16), int(c1[3:5], 16), int(c1[5:7], 16)
    r2, g2, b2 = int(c2[1:3], 16), int(c2[3:5], 16), int(c2[5:7], 16)
    r = int(r1 + (r2 - r1) * t)
    g = int(g1 + (g2 - g1) * t)
    b = int(b1 + (b2 - b1) * t)
    return f"#{r:02X}{g:02X}{b:02X}"

text = "Connection established. Neural link active."
c1, c2 = "#D4A017", "#8B0000"  # gold -> blood red
result = ""
for i, ch in enumerate(text):
    t = i / (len(text) - 1) if len(text) > 1 else 0
    color = lerp_color(c1, c2, t)
    result += f"[{color}]{ch}[/]"
print(result)
PYEOF

Example gradients from existing skins:

• Netrunner: Connection established. Neural link active. — teal #00897B → white #FFFFFF over ~40 characters
• Solo Leveling Boss: ARISE. The system has chosen. — purple #A855F7 → cyan #7FFFD4 over ~30 characters
• Kensei: Steel drawn. State your objective. — gold #D4A017 → blood-red #8B0000 over ~25 characters
• ONI: Connection established. Neural link active. Blade drawn. State your objective — or /help for protocols. — gold #D4A017 → blood-red #8B0000 over ~86 characters

tool_prefix (string)

Character/string prepended to tool output lines. Convention: pipe-like characters.

• Netrunner: ▏
• Solo Leveling Boss: │
• Kensei: │

tool_emojis (map of tool-name → emoji/string)

tool_emojis:
  terminal: ☾
  web_search: ⫷
  read_file: 巻
  write_file: ⚔
  search_files: ⌖
  execute_code: ⚡
  memory: 心
  clarify: '?'
  mixture_of_agents: 衆
  todo_write: ▰
  task: ⟨⟩

Each tool type gets an icon shown inline during execution. These are purely cosmetic. You can define icons for any tool, or leave tools unassigned (they get default icons).

YAML pitfall: The ? character has special meaning in YAML (it starts a mapping key). Always quote it: clarify: "?" or clarify: '?'. Failure to quote will produce a YAML parse error.

banner_logo (block string, |- style)

ASCII art shown as the primary banner on startup. Supports inline color tags ([#HEX]text[/]). Usually a text-based logo (wordmark or ASCII art name).

Example pattern:

banner_logo: |-
  [#A855F7]
       ███████╗██╗  ██╗ █████╗ ██████╗  ██████╗ ██╗    ██╗
       ██╔════╝██║  ██║██╔══██╗██╔══██╗██╔═══██╗██║    ██║
       ...[/]

For simple text logos, use pyfiglet to generate ASCII art banner text, then apply grouped-gradient color tags. This produces a wordmark that fills the hero width (~80 chars) rather than a narrow 20-char logo.

Quick pipeline:

1. Install pyfiglet in a venv: python3 -m venv /tmp/figlet_v && /tmp/figlet_v/bin/pip install pyfiglet
2. Find fonts that fill banner width: FigletFont.getFonts() filtered to ~40-80 char width, 5-9 line height (see references/banner-logo-pyfiglet.md for font selection table)
3. Generate text: Figlet(font='roman', width=90).renderText('NAME')
4. Apply grouped gradient color tags (block_size=3, gold→blood-red or your palette colors)
5. Add a decorative separator line (e.g., ━━━ ⚔ ☾ ◎ ━━━) with a fixed accent color — do NOT gradient the separator
6. Verify source lines stay under ~250 bytes each to avoid TUI wrapping
7. Validate YAML

See references/banner-logo-pyfiglet.md for the full step-by-step pipeline, font selection guide, and a worked example ("SEN" in roman font).

banner_hero (block string, |- style)

Extended ANSI/unicode art shown below the banner_logo during startup. Supports both inline color tags AND terminal-format colored Braille/symbol art using the standard terminal color tag syntax.

Banner_hero can contain:

• Braille-pattern art (using ⠀ characters with color tags)
• Extended unicode block art
• Decorative borders and frames with custom characters
• Mixed text and visual elements
• Image-to-ASCII converted art from tools like jp2a

It is typically the largest section of a skin file (the solo-leveling-boss banner_hero is ~18KB).

Generating banner_hero art from images: See the ascii-art skill for details. The common pipeline:

1. Find a reference image. For generic art (silhouettes, masks, swords), try openclipart.org. For a specific character (anime, game, manga), see references/finding-character-reference-images.md — the canonical wiki reference matters more than resolution.
2. Verify the image with vision_analyze — confirm it actually shows what you need before converting. This catches fan art that doesn't match the canonical design.
3. Download the 800px+ PNG version
4. Convert with jp2a --width=68 --invert image.png
5. Wrap the output in [#ACCENT_COLOR]...[/] inside the YAML |- block

Pitfall: Don't trust image filenames or alt text — many wallpaper sites mislabel fan art. Always verify with vision_analyze that the image actually shows the intended character with the correct features (body shape, expression, accessories).

User-submitted image workflow (interactive width preview): When the user provides their own image (local file path) for a banner_hero, do NOT commit to a single width up front. The user needs to see options:

1. Check the image file: file <path> to confirm format and dimensions. Portrait/manga-style AI art from Stable Diffusion (txt2img) is common — 1152×1920 portrait works well.
2. If the vision API can't analyze the image (model doesn't support vision, file too large, format issue), do NOT stall — convert with jp2a directly. The ASCII output serves as both preview AND silhouette inspection.
3. Convert at multiple banner widths using jp2a --width=<N> --invert <path> and count lines with wc -l:
   • width=68 → ~55-60 lines (most detail, tall banner)
   • width=60 → ~48-52 lines (middle ground)
   • width=50 → ~40-44 lines (solid banner height)
   • width=40 → ~30-35 lines (compact, clean silhouette)
4. Show the user the line counts and a visual preview at each candidate width.
5. Let them choose before proceeding to color-tagging and injection.
6. Once chosen, wrap the ASCII in color tags and inject into the banner_hero: block.

Multi-stop gradient wrapping (advanced): Instead of wrapping all 57 lines in a single [#ACCENT]...[/], apply a per-line gradient using a Python multi-stop lerp. This gives the art depth — e.g., dark at the top, bright accent in the middle, gold at the bottom:

def lerp_color(c1, c2, t):
    r1, g1, b1 = int(c1[1:3], 16), int(c1[3:5], 16), int(c1[5:7], 16)
    r2, g2, b2 = int(c2[1:3], 16), int(c2[3:5], 16), int(c2[5:7], 16)
    r = int(r1 + (r2 - r1) * t)
    g = int(g1 + (g2 - g1) * t)
    b = int(b1 + (b2 - b1) * t)
    return f"#{r:02X}{g:02X}{b:02X}"

# Multi-stop color gradient: (hex, position) pairs
colors = [("#8B0000", 0.0), ("#C0392B", 0.4), ("#E34234", 0.65), ("#D4A017", 1.0)]

def multi_stop(t):
    for i in range(len(colors)-1):
        c1, p1 = colors[i]; c2, p2 = colors[i+1]
        if p1 <= t <= p2:
            return lerp_color(c1, c2, (t - p1) / (p2 - p1))
    return colors[-1][0]

lines = ["... jp2a output line ..."]  # 57 lines
for i, line in enumerate(lines):
    t = i / (len(lines) - 1)
    color = multi_stop(t)
    print(f"  [{color}]{line}[/]")

This produces distinct hex values per line so every row has a unique color in the gradient, creating a smooth transition across the full art.

Choosing stops for the palette: Match the skin's existing colors — pull from the skin's colors: section. Common patterns:

Patching the result into the skin file: Use the patch tool with the full banner_hero: |- block (from banner_hero: |- through the last [/]) as old_string and the new gradient-wrapped block as new_string. The patch tool's built-in YAML linter will validate automatically.

Recoloring an existing banner_hero from another skin (per-character palette remapping):

When you want to use banner_hero art from a different skin in your target skin's color palette, the source likely uses per-character multi-tag coloring (e.g., [#203050]%[/][#203060]%%%[/]...). There are two approaches:

Approach A: Per-character remapping (preserves shading/depth — preferred)

Parses every [#HEX]char[/] pair, maps the original color's luminance to the target gradient, and re-wraps in 4-char block-grouped tags. The figure retains its 3D depth — dark shadows become dark wine, bright highlights become gold.

Uses scripts/per-character-palette-remap.py (included in this skill):

# Quick one-shot from a script call:
python3 ~/.hermes/profiles/senna/skills/hermes/hermes-skin-authoring/scripts/per-character-palette-remap.py \
  ~/.hermes/skins/solo-leveling-boss.yaml \
  /tmp/new-banner.txt

Then patch the output into the target skin using the patch tool with the current banner_hero block as old_string and the file contents as new_string.

The algorithm:

1. Parse each character's [#ORIG_HEX]char[/] tag from the source banner
2. Convert ORIG_HEX to HSL, extract luminance L (0.0 = dark, 1.0 = bright)
3. Map L to a position in the target gradient: dark→first stop, bright→last
4. Interpolate to get the new hex value in the target palette
5. Group consecutive characters into blocks of 4 (controls source line length)
6. Wrap each block: [#NEW_HEX]block_text[/]

See references/per-character-palette-remap.md for the full worked example (solo-leveling-boss → senna fire palette, 41 lines, 621 tags, 0 balance errors).

Approach B: Per-line single tag (simpler, more compact)

When file size is a concern or the art is blocky/abstract (not a detailed figure), strip tags and wrap each entire line in one color:

1. Extract the banner_hero block from the source skin using read_file
2. Write a Python script that reads those lines, strips ALL [#HEX] and [/] tags with regex (re.sub(r'\\[/?[^\\]]*\\]', '', line)), giving you the raw character content per line
3. Apply a multi-stop gradient by wrapping each line in a single [#COLOR]raw_line[/] tag (one color per line)
4. Patch into the target skin

~3KB for 41 lines vs ~8.5KB for per-character. Use this when the original art doesn't have fine shading worth preserving.

Image format conversion (macOS): When a user provides a WebP image for jp2a conversion and PIL/Pillow isn't available, use macOS's built-in sips:

sips -s format png input.webp --out output.png

This avoids needing to install Pillow globally or in a venv. Works on any macOS system (Intel or Apple Silicon).

Pitfall: Do not guess what width the user wants based on the source image dimensions alone — the banner container's width is fixed (~68 chars), not the image's. Always offer options. Pitfall: For multi-stop gradients, ensure the Python script generates the full YAML block correctly before patching — count the output lines and verify the last line closes with [/]. Patch failures from mismatched old_string are hard to debug. Pitfall: When producing the full skin block for patching, include the banner_hero: |- key line in both old_string and new_string — the patch operates on literal text, not YAML structure. Omitting the key line makes the match ambiguous. Pitfall: When recoloring an existing multi-tag banner_hero, the recolor script must produce lines with exactly one [#HEX]...[/] tag per line (not multiple per line). Verify with a simple grep pattern count before patching — mismatched tag counts cause YAML parse errors or invisible banner output.

See references/user-image-to-banner-hero.md for a worked example converting a 1152×1920 Stable Diffusion portrait into a 57-line 4-stop gradient banner hero.

Banner line-height guidance:

See references/banner-hero-examples.md for technique patterns: how Braille art is built, how gradient borders work, and how to construct a simple hero block.

Color tags in banner art and terminal-width wrapping

A critical gotcha: per-character color tags inflate the source line length dramatically, which causes the TUI's banner display to wrap long lines — projecting each character onto its own row. This makes text appear vertical and misaligned.

Math: Each [#HEX]char[/] tag adds ~14 bytes of markup for 1 rendered character. A 53-character English quote becomes ~700 source bytes. If that exceeds the TUI's banner container width, every character wraps independently → vertical text.

Fix: block-grouped color tags. Instead of one tag per character, group 2-4 characters under each tag with the same gradient interpolation:

# Per-character (BAD — 689 source bytes for 53 rendered chars):
[#D4A017]A[/][#D49A18] [/][#D5951A]m[/][#D68F1C]a[/][#D78A1D]n[/]...  # 53 tags

# Block-grouped (GOOD — 221 source bytes, same visual):
[#D19916]A ma[/][#CB8D14]n wi[/][#C68112]thou[/][#C07510]t co[/]...   # 14 tags

The rendered output is identical — same smooth gradient — but the source line fits within the banner container.

Choosing block size:

A reusable script scripts/gradient-color-tags.py is included in this skill. Use it instead of hand-writing grouped tags.

See references/banner-hero-examples.md for technique patterns: how Braille art is built, how gradient borders work, and how to construct a simple hero block.

How to Create a New Skin

Method 1: From Scratch

1. Create a new YAML file in ~/.hermes/skins/ or ~/.hermes/profiles/<profile>/skins/
2. Set a unique name: and description:
3. Define the colors: section (start with an existing skin's palette and adjust)
4. Define spinner:, branding:, tool_emojis:, banner_logo:, banner_hero:
5. Switch to it: /skin <name> from within a session, or hermes config set display.skin <name> then restart

Method 2: Combine Elements from Multiple Skins (as in this session)

1. Decide which elements to pull from each source skin

2. Copy the colors: section from the dominant aesthetic, or create a hybrid palette

3. Copy spinner: from one source (or build a hybrid from multiple)

4. Write a new branding.welcome: using the tag-gradient technique, optionally inspired by the netrunner-style boot sequence

5. Create tool_emojis: by selecting your preferred symbols from each source

6. For banner_logo: and banner_hero: — either use one from a source, create a new one, or omit for a minimal skin.

   To copy a banner_hero between skin files using patch (common operation):

   • Read both source and target skin files with read_file to see the exact content
   • Identify the boundaries of the banner_hero: |- block in both files. The block starts with the banner_hero: |- line itself and ends with the closing [/]) tag on its own line
   • Use patch with the target file's current banner_hero block as old_string and the source file's full block (from banner_hero: |- through [/]) as new_string — include the opening key line so the match is unambiguous
   • Verify the patch succeeded by re-reading the target file with read_file
   • Important: The old_string must match the file content exactly — whitespace, indentation, and trailing spaces count. Copy-paste from the file read, don't retype.

7. Test with /skin <name> — if it works, it will load immediately (new session). If it fails, check YAML validity.

Worked example: the ONI skin — see references/oni-skin-session.md for the full merge of solo-leveling-boss, kensei, and netrunner skins into a single oni-themed skin.

Method 3: Clone and Modify

1. Copy an existing .yaml to a new name: cp kensei.yaml my-custom.yaml
2. Change name: and description: at the top
3. Swap colors one at a time
4. Replace spinner symbols and verbs
5. Rewrite branding strings
6. Customize tool_emojis

Verifying a Skin Loads Correctly

# Start a session with the new skin
hermes --profile <profile> --skin <name>
# OR in-session:
/skin <name>
# Then /reset to apply changes fully

If the skin doesn't load:

1. Check the YAML is valid: python3 -c "import yaml; yaml.safe_load(open('path/to/skin.yaml'))"
2. Check the name: field matches (case-sensitive)
3. Check the file is in the right directory (~/.hermes/skins/ or per-profile)
4. Check for unclosed color tags — every [#HEX] must have a matching [/]
5. Check for YAML indentation errors (especially in banner_hero block strings)
6. Check for unquoted ? in tool_emojis (clarify: ? → clarify: "?")

Skin Deployment & Lifecycle

Beyond creating and editing a skin, you'll need to deploy it to the right location, rename it, and keep config in sync.

Moving a Skin Between Locations

Skins can live in global (~/.hermes/skins/) or per-profile (~/.hermes/profiles/<name>/skins/) directories. To move a skin:

1. Copy the YAML file to the target directory
2. Remove it from the source directory
3. Update display.skin in the relevant profile config if the skin name changed
4. Restart the session for the change to take effect

Per-profile skin files take priority over global ones with the same name: field. Be deliberate about placement.

Bulk-Importing a Skin Pack (collision hazard)

When installing a public skin pack (cp skins/*.yaml ~/.hermes/skins/), same-named files are silently OVERWRITTEN — no warning, no merge. Real incident 2026-08-03: importing bchop-studio/hermes-skins-pack clobbered the local netrunner (7.2K full skin with banner_hero/branding/spinner) with the pack's minimal 1.3K palette-only variant. The original survived only because the senna profile skins dir still mirrored it — recovery was cp ~/.hermes/profiles/senna/skins/netrunner.yaml ~/.hermes/skins/.

Before a bulk import:

1. Diff pack names against ls ~/.hermes/skins/ (and per-profile dirs) FIRST.
2. For each collision, decide which version wins — pack skins are usually minimal complete-palette YAMLs (~1.3K, no banner_hero/spinner/branding), so the richer local skin typically wins. Keep the pack's file only if you want the stripped look.
3. Copy with cp -i (prompts per overwrite) or exclude colliding files explicitly.
4. Verify after import: every file's name: field matches its filename (grep -m1 '^name:' *.yaml), and spot-check a couple of colors you expected.
5. Profile skins dirs mirror globals by default, so a clobbered global skin is usually recoverable from the matching per-profile dir — check there before reaching for git or re-downloads.

Fleet-Wide Sharing via Symlink (multi-profile setups)

Problem: $HERMES_HOME is profile-aware, so profiles only see their own skins/ dir — skins installed to the root ~/.hermes/skins/ are invisible to other profiles' CLIs and to a desktop app connected to a profile backend.

Fix (done fleet-wide 2026-08-04): replace each profile's skins dir with a symlink to the root:

cd ~/.hermes/profiles
for p in */; do
  p=${p%/}; s="$p/skins"
  [ -L "$s" ] && continue                                    # already linked
  if [ -d "$s" ]; then
    if [ -n "$(ls -A "$s")" ]; then cp "$s"/*.yaml ~/.hermes/skins/; mv "$s" "$s.bak"
    else rmdir "$s"; fi
  fi
  ln -s ~/.hermes/skins "$s"
done

Pitfall — same-name/different-content collision: when merging a profile dir into root, a filename may exist in both with DIFFERENT skins inside (real case: senna.yaml — profile's dragon palette vs root's netrunner-imperial palette). Don't silently overwrite. Rename the divergent one (senna-imperial.yaml, and update its name: field to match), keep both. Check with diff -q per file before copying; identical files need no action.

After symlinking, one canonical set serves every profile and the desktop app regardless of which profile's backend it connects to. Keep the .bak dir until verified, then delete.

Renaming a Skin

Renaming requires three coordinated changes — skipping any one breaks the skin:

1. Change the name: field in the YAML file (this is what Hermes actually loads by)
2. Rename the file (optional but recommended for clarity — mismatched name/filename works but causes confusion later)
3. Update display.skin in the profile's config.yaml to the new name

# Before:
#   ~/.hermes/profiles/senna/skins/oni.yaml  → name: oni
#   config.yaml → skin: oni
# After:
#   ~/.hermes/profiles/senna/skins/senna.yaml → name: senna
#   config.yaml → skin: senna

Replacing a Profile's Default Skin

Each profile usually has a default skin named after the profile (e.g., senna.yaml in the senna profile's skins directory). To replace it with a different skin:

1. Delete the old default skin file (senna.yaml) from the profile skins directory
2. Delete any other old skin files you're replacing (e.g., oni.yaml)
3. Copy the new skin into the profile skins directory as the default name (senna.yaml)
4. Update the name: field in the YAML to match the new filename
5. Verify display.skin in the profile's config.yaml is set to the new name
6. Start a new session with /new to apply

Example from a real session — replacing the senna profile's default skin with an updated oni-themed skin:

# Clean up old files
rm ~/.hermes/profiles/senna/skins/oni.yaml
rm ~/.hermes/profiles/senna/skins/senna.yaml

# Write the new skin as the profile default
# (write the updated content to senna.yaml with name: senna)

# Update config
# config.yaml: skin: oni → skin: senna

Config Visibility vs Runtime Override

There are two channels for setting the active skin, and they behave differently:

• /skin does not write to config.yaml. If a user sets a runtime skin and then restarts, the config default is used.
• display.skin in config sets the default for all new sessions. Changing it requires a restart.
• If you rename a skin or change its location, update display.skin in config — otherwise the next session will fail to find the old name and fall back to defaults.
• To see the active skin: read config.yaml line containing skin: and/or observe the banner on startup.

Checklist: After Any Skin Structure Change

• Skin file exists in the intended directory
• name: field in YAML matches the intended skin name
• display.skin in profile config.yaml matches the name
• No orphaned skin files left in old locations
• /new or session restart confirms the skin loads without error

Community Tools

hermes-mod (npx -y hermes-mod): Web-based visual skin editor by cocktailpeanut (Pinokio creator). Good for quick scaffolding and image-to-banner conversion without touching YAML. Does NOT support per-character gradients or per-profile skins — use our skill for advanced work. See references/hermes-mod-gui-tool.md for full review.

Pitfalls

• Active skin vs profile default — don't guess. When a user asks about colors or wants to customize, do not assume the profile's default skin (e.g., senna.yaml for the senna profile) is what they're seeing. The active skin may have been switched at runtime via /skin <name>. A user may have loaded the oni skin in a previous session and it persists. Read the active skin file directly or ask "which skin are you using?" before making changes. Setting display.skin in config only changes the default — the runtime /skin command overrides it session-to-session and does not update config.

• banner_hero can inflate file size dramatically. The solo-leveling-boss skin is 24KB, of which ~18KB is banner_hero. Consider omitting banner_hero for a minimal skin.

• Color tag mismatch in banner strings. Forgetting a closing [/] in a long welcome gradient causes all subsequent text to be colored, breaking the display. Always pair [#HEX] with [/].

• Skin name vs filename. The skin is loaded by name: field, not the filename. Two files with the same name: cause ambiguity. Keep them consistent.

• Profile vs global. A skin in ~/.hermes/profiles/senna/skins/ takes priority over the same name in ~/.hermes/skins/. Be deliberate about placement.

• Per-skin custom color keys. You can define extra color keys (e.g., blade_glow, blade_edge) for use in banner_art, but they don't affect the TUI chrome. Only the standard colors.* keys drive actual UI rendering.

• Wings format is a 2-element list. Each entry in spinner.wings must be [left_bracket, right_bracket]. If formatted as a flat list of strings, the spinner code will error silently.

• Unquoted ? in YAML. The ? character starts a mapping key in YAML. In tool_emojis, always quote: clarify: "?" or clarify: '?'.

• Raw [#HEX]...[/] markup visible in terminal output = the string went through plain print() instead of the rich console. Symptom seen 2026-07-27: user closed Hermes and the goodbye gradient printed as literal color tags. Cause: _print_exit_summary in cli.py printed the goodbye with print(goodbye), while the welcome banner renders via self._console_print() (rich, parses markup). Fix: route through self._console_print(goodbye) with a plain-print fallback (patched locally at cli.py ~L13704; note this is a local fork patch — an upstream hermes update may revert it, worth an upstream PR). Diagnose rule: grep the render path for print( vs _console_print(.

• Per-character color tags cause vertical text in banners. When banner_hero or banner_logo lines use one [#HEX]char[/] tag per character, the source line length balloons ~14× the rendered width. If the source exceeds the TUI banner container width, each character wraps to its own row → text appears vertical and misaligned. Fix: use block-grouped color tags (2-4 characters per tag) via scripts/gradient-color-tags.py.

• Gradient welcome text too long. Very long welcome strings (~100+ characters) generate huge YAML values. Consider truncating the message or using shorter words. 60-90 characters is manageable.

• Verify skin content directly — don't reconstruct from memory or session summaries. When checking whether a skin file contains expected changes (banner_hero art, specific hex codes, branding text), always read_file the actual YAML. Session summaries can be stale, describe a version at a different path, or reference changes that were later overwritten. Trust the literal bytes on disk, not the assistant's reconstruction of what happened in past sessions.

• Em dash characters in YAML. The em dash (—) can cause encoding issues when pasted from Python output. Verify it survived into the YAML file. Check that \\u2014 (Python escape) rendered as the actual — character, not a literal backslash-u string.

• /skin mid-session may not fully render all color elements. The banner, spinners, and branding switch immediately, but prompt, response_text, and session_label colors may stay on the old values until a fresh session. If a user reports "colors didn't change" after /skin, the skin file is likely correct — recommend /new or a full terminal restart (Ctrl+C + hermes).

• /new can produce an asyncio RuntimeWarning. Under some Hermes TUI versions, /new prints: RuntimeWarning: coroutine 'run_in_terminal.<locals>.run' was never awaited. This is non-fatal — the session may or may not have restarted cleanly. If the user reports this, recommend exiting with Ctrl+C or /exit and restarting from the terminal with hermes.

Existing Skins Reference (this user's setup)

IMPORTANT: This table describes the skin's intended aesthetic. Always verify on-disk availability with ls ~/.hermes/skins/ and ls ~/.hermes/profiles/<profile>/skins/ before suggesting or switching — skins may have been renamed, replaced, or removed since this table was last updated.

2026-08-03 fleet update: bulk-imported 49 skins from bchop-studio/hermes-skins-pack (50-skin public pack, MIT) into ~/.hermes/skins/. Only name collision was netrunner (local richer version kept). The 49 pack skins are minimal complete-palette YAMLs (~1.3K each — colors + prompt symbol only, no banner_hero/spinner/branding). Notable for the user's noir/game taste: dragon-blood, shadow-thief, forge-master, arcane-tome, void-sunset, chrome-rain. Install path for more packs: see Bulk-Importing above.

2026-08-04 fleet update: installed 24 more skins from CliffWade/hermes-desktop-theme-pack (WCAG-AA-checked palettes, 6 categories; "desktop theme pack" is a misnomer — plain skins) into ~/.hermes/skins/ (no collisions). Same day: all 23 profiles' skins dirs replaced with symlinks to root — see Fleet-Wide Sharing above. Root's old senna.yaml (different skin, same name) survives as senna-imperial.yaml; senna profile originals backed up at ~/.hermes/profiles/senna/skins.bak.

See references/skin-details.hybridization-era.md for the source-skin analysis that fed into the oni skin, and references/oni-skin-session.md for the full build log. See references/finding-character-reference-images.md for how to find and verify canonical images of specific characters (anime, manga, games) for banner_hero conversion — includes a ranked source list and verification workflow.