How to Create a Custom Hermes Skin (Step-by-Step YAML Guide)
Hermes ships with a handful of built-in looks, but the real fun starts when you design your own. A custom Hermes skin is just a YAML file that tweaks colors, banners, spinner art, and tool emojis. You do not need to write code or rebuild Hermes — you just drop a file into the right folder and switch to it.
This guide walks through making your first Hermes CLI theme from scratch. If you would rather start with something ready-made, browse the live skins on hermesskins.io/skins first.
What a Hermes skin actually controls
Skins only change appearance, not behavior. Inside a skin YAML file you can set:
- Colors for the banner, response box, status bar, prompts, and menus.
- ASCII/Unicode banners shown at startup and in the header.
- Spinner faces and verbs while the agent is thinking.
- Branding text like the agent name, welcome message, and prompt symbol.
- Tool emojis that appear next to tool calls.
Everything else — how Hermes reasons, which tools it can use, and how it answers — stays the same. Think of a skin as a coat of paint over the same engine.
Where Hermes stores skins
Custom skins live in:
~/.hermes/skins/<name>.yaml
Hermes also comes with built-in skins. You can list and preview the current skin at any time by typing:
/skin
To try a skin for the current session only, run:
/skin mytheme
To make it permanent, edit ~/.hermes/config.yaml:
display:
skin: mytheme
A minimal working skin YAML
Create a file at ~/.hermes/skins/cyberminimal.yaml with the contents below. Any keys you leave out inherit from the default skin, so this is enough to see a real change.
name: cyberminimal
description: A minimal dark cyber theme for learning Hermes skin YAML
colors:
banner_border: "#00ff9d"
banner_title: "#00ff9d"
banner_accent: "#ff00ff"
banner_dim: "#555555"
banner_text: "#e0e0e0"
ui_accent: "#00ff9d"
ui_label: "#ff00ff"
ui_ok: "#00ff9d"
ui_error: "#ff4444"
ui_warn: "#ffaa00"
prompt: "#e0e0e0"
input_rule: "#333333"
response_border: "#00ff9d"
status_bar_bg: "#111111"
status_bar_text: "#e0e0e0"
status_bar_strong: "#00ff9d"
status_bar_dim: "#555555"
status_bar_good: "#00ff9d"
status_bar_warn: "#ffaa00"
status_bar_bad: "#ff4444"
status_bar_critical: "#ff0000"
voice_status_bg: "#111111"
completion_menu_bg: "#1a1a1a"
completion_menu_current_bg: "#333333"
completion_menu_meta_bg: "#111111"
completion_menu_meta_current_bg: "#444444"
session_label: "#ff00ff"
session_border: "#333333"
branding:
agent_name: "Cyberminimal Agent"
welcome: "System online. Type a message or /help for commands."
goodbye: "Session closed."
response_label: " Cyberminimal "
prompt_symbol: "> "
help_header: "Cyberminimal Commands"
spinner:
waiting_faces:
- "(◈)"
- "(◇)"
- "(◈)"
thinking_faces:
- "(◐)"
- "(◓)"
- "(◑)"
- "(◒)"
thinking_verbs:
- "compiling style"
- "rendering pixels"
- "tuning palette"
wings:
- ["⟪", "⟫"]
- ["‹", "›"]
tool_prefix: "│"
tool_emojis:
terminal: "◈"
web_search: "◎"
web_fetch: "◉"
read_file: "◐"
write_file: "◑"
patch: "◒"
search_files: "◓"
execute_code: "⌁"
browser_navigate: "▸"
delegate_task: "⇄"
mixture_of_agents: "∞"
memory: "◍"
clarify: "?"
cronjob: "↻"
process: "⚙"
todo: "☐"
skill_view: "◈"
skills_list: "◈"
text_to_speech: "◉"
vision_analyze: "◐"
banner_logo: |
[#00ff9d]┌─────────────────────────────────────┐[/]
[#00ff9d]│ C Y B E R M I N I M A L A G E N T │[/]
[#555555]└─────────────────────────────────────┘[/]
banner_hero: |
[#ff00ff] _ _ ____ ____ _ _ ____ _ _ ___[/]
[#ff00ff] |__| |__| [__ |__| |___ | | | [/]
[#00ff9d] | | | | ___] | | |___ |__| | [/]
[#555555] minimal theme loaded [/]
Save the file, then run /skin cyberminimal inside Hermes. You should immediately see the new colors and banner.
The most useful keys to customize
You do not need to memorize every key. Start with these high-impact ones, then add detail later.
| Key group | What it changes |
|-----------|-----------------|
| colors.banner_* | The top banner border, title, accents, dim text, and body text. |
| colors.ui_* | Accent color, labels, success/error/warning indicators. |
| colors.prompt and colors.input_rule | The prompt text and the horizontal rule under it. |
| colors.response_border | Border around the agent's response box. |
| colors.status_bar_* | The bottom status bar background, text, and state colors. |
| branding.agent_name | The name shown in the banner and status bar. |
| branding.welcome / branding.goodbye | Greeting and farewell strings. |
| branding.response_label | Label on the agent's response box. |
| branding.prompt_symbol | The character(s) before your input. |
| spinner.waiting_faces / thinking_faces | Animated faces while waiting or thinking. |
| spinner.thinking_verbs | Phrases shown while the agent is working. |
| banner_logo / banner_hero | Large ASCII/Unicode art shown at startup. |
For the complete schema, refer to the official Hermes skins documentation.
Install and activate your skin
- Save your YAML file to
~/.hermes/skins/<name>.yaml. - Inside Hermes, run
/skin <name>to try it immediately. - To keep it across restarts, add this to
~/.hermes/config.yaml:
display:
skin: <name>
If something looks wrong, check the YAML indentation and make sure every color starts with #. Hermes will fall back to the default skin if the file cannot be parsed.
Study existing skins for inspiration
The fastest way to level up is to look at skins other people have built. Each item page on hermesskins.io links to a downloadable YAML file you can open and adapt.
- Catppuccin — a soft pastel theme with a full color palette and custom spinner art.
- Neonwave — a synthwave look with neon pinks and cyans.
- Pirate — a simple black-and-white theme, good for understanding a minimal skin.
- DOS — a retro cyan-on-black terminal style.
- Bubblegum '80s — bright pastels and fluorescent accents.
- Empire — a detailed sci-fi theme with deep space colors.
Open any of these in a text editor, change a few hex colors, and save it under a new name. You will learn the structure faster by editing a working file than by starting from a blank page.
Prefer a visual editor?
If YAML is not your thing, the community project hermes-mod provides a web UI for tweaking skin values. You can run it with:
npx -y hermes-mod
It is optional, but useful for previewing color changes before you copy the YAML into ~/.hermes/skins/.
Share your skin with the community
Once you have a skin you like, you can share it so other Hermes users can install it in one step. The marketplace accepts a single .yaml file.
- Upload your skin at hermesskins.io/upload.
- Browse what is already live at hermesskins.io/skins.
- If you also built a skill, list it at hermesskins.io/skills.
A good skin submission includes a clear name, a one-line description, and a preview image if you have one. Keep it legal and value-adding — only upload skins you have permission to share.
Quick reference cheatsheet
# ~/.hermes/skins/mytheme.yaml
name: mytheme
description: One-line description shown in listings
colors:
banner_border: "#hex"
banner_title: "#hex"
banner_accent: "#hex"
banner_dim: "#hex"
banner_text: "#hex"
ui_accent: "#hex"
ui_label: "#hex"
ui_ok: "#hex"
ui_error: "#hex"
ui_warn: "#hex"
prompt: "#hex"
input_rule: "#hex"
response_border: "#hex"
branding:
agent_name: "My Agent"
welcome: "Hello."
goodbye: "Goodbye."
response_label: " My "
prompt_symbol: "❯ "
help_header: "Commands"
spinner:
waiting_faces: ["(◈)", "(◇)"]
thinking_faces: ["(◐)", "(◓)"]
thinking_verbs: ["thinking..."]
Related reads
- Browse all Hermes skins
- Browse all Hermes agent skills
- The Best Hermes Skins and Skills to Try First
- Submit your own Hermes skin or skill
- Official Hermes skin docs
- Community skin pack on GitHub
Last updated: 2026-07-03. Skin syntax verified against Hermes skins documentation and community examples.