feat: expand hermes-agent-setup skill + tell agent about it in STT notes

Skill now covers full CLI usage (hermes setup, hermes skills, hermes tools, hermes config, session management, etc.), config file reference, and expanded gateway commands. Agent context notes for STT failure now mention the hermes-agent-setup skill is available to help users configure Hermes features.
2026-03-18 03:05:17 -07:00
parent 9c0f346258
commit 764825bbff
2 changed files with 177 additions and 24 deletions
--- a/skills/dogfood/hermes-agent-setup/SKILL.md
+++ b/skills/dogfood/hermes-agent-setup/SKILL.md
@@ -1,14 +1,14 @@
 ---
 name: hermes-agent-setup
-description: Help users configure Hermes Agent — enable tools, set up voice/STT/TTS, install dependencies, and troubleshoot. Use when someone asks to enable features, configure voice, or when the system detects missing config.
-version: 1.0.0
+description: Help users configure Hermes Agent — CLI usage, setup wizard, model/provider selection, tools, skills, voice/STT/TTS, gateway, and troubleshooting. Use when someone asks to enable features, configure settings, or needs help with Hermes itself.
+version: 1.1.0
 author: Hermes Agent
-tags: [setup, configuration, tools, stt, tts, voice, hermes]
+tags: [setup, configuration, tools, stt, tts, voice, hermes, cli, skills]
 ---

 # Hermes Agent Setup & Configuration

-Use this skill when a user asks to enable features, configure voice messages, set up tools, or troubleshoot configuration.
+Use this skill when a user asks about configuring Hermes, enabling features, setting up voice, managing tools/skills, or troubleshooting.

 ## Key Paths

@@ -16,6 +16,116 @@ Use this skill when a user asks to enable features, configure voice messages, se
 - API keys: `~/.hermes/.env`
 - Skills: `~/.hermes/skills/`
 - Hermes install: `~/.hermes/hermes-agent/`
+- Venv: `~/.hermes/hermes-agent/.venv/` (or `venv/`)
+
+## CLI Overview
+
+Hermes is used via the `hermes` command (or `python -m hermes_cli.main` from the repo).
+
+### Core commands:
+
+```
+hermes                          Interactive chat (default)
+hermes chat -q "question"       Single query, then exit
+hermes chat -m MODEL            Chat with a specific model
+hermes -c                       Resume most recent session
+hermes -c "project name"        Resume session by name
+hermes --resume SESSION_ID      Resume by exact ID
+hermes -w                       Isolated git worktree mode
+hermes -s skill1,skill2         Preload skills for the session
+hermes --yolo                   Skip dangerous command approval
+```
+
+### Configuration & setup:
+
+```
+hermes setup                    Interactive setup wizard (provider, API keys, model)
+hermes model                    Interactive model/provider selection
+hermes config                   View current configuration
+hermes config edit              Open config.yaml in $EDITOR
+hermes config set KEY VALUE     Set a config value directly
+hermes login                    Authenticate with a provider
+hermes logout                   Clear stored auth
+hermes doctor                   Check configuration and dependencies
+```
+
+### Tools & skills:
+
+```
+hermes tools                    Interactive tool enable/disable per platform
+hermes skills list              List installed skills
+hermes skills search QUERY      Search the skills hub
+hermes skills install NAME      Install a skill from the hub
+hermes skills config            Enable/disable skills per platform
+```
+
+### Gateway (messaging platforms):
+
+```
+hermes gateway run              Start the messaging gateway
+hermes gateway install          Install gateway as background service
+hermes gateway status           Check gateway status
+```
+
+### Session management:
+
+```
+hermes sessions list            List past sessions
+hermes sessions browse          Interactive session picker
+hermes sessions rename ID TITLE Rename a session
+hermes sessions export ID       Export session as markdown
+hermes sessions prune           Clean up old sessions
+```
+
+### Other:
+
+```
+hermes status                   Show status of all components
+hermes cron list                List cron jobs
+hermes insights                 Usage analytics
+hermes update                   Update to latest version
+hermes pairing                  Manage DM authorization codes
+```
+
+## Setup Wizard (`hermes setup`)
+
+The interactive setup wizard walks through:
+1. **Provider selection** — OpenRouter, Anthropic, OpenAI, Google, DeepSeek, and many more
+2. **API key entry** — stores securely in the env file
+3. **Model selection** — picks from available models for the chosen provider
+4. **Basic settings** — reasoning effort, tool preferences
+
+Run it from terminal:
+```bash
+cd ~/.hermes/hermes-agent
+source .venv/bin/activate
+python -m hermes_cli.main setup
+```
+
+To change just the model/provider later: `hermes model`
+
+## Skills Configuration (`hermes skills`)
+
+Skills are reusable instruction sets that extend what Hermes can do.
+
+### Managing skills:
+
+```bash
+hermes skills list              # Show installed skills
+hermes skills search "docker"   # Search the hub
+hermes skills install NAME      # Install from hub
+hermes skills config            # Enable/disable per platform
+```
+
+### Per-platform skill control:
+
+`hermes skills config` opens an interactive UI where you can enable or disable specific skills for each platform (cli, telegram, discord, etc.). Disabled skills won't appear in the agent's available skills list for that platform.
+
+### Loading skills in a session:
+
+- CLI: `hermes -s skill-name` or `hermes -s skill1,skill2`
+- Chat: `/skill skill-name`
+- Gateway: type `/skill skill-name` in any chat

 ## Voice Messages (STT)

@@ -73,9 +183,9 @@ Hermes can reply with voice when users send voice messages.
 - `/voice tts` — voice reply to all messages
 - `/voice off` — text only (default)

-## Enabling/Disabling Tools
+## Enabling/Disabling Tools (`hermes tools`)

-### Interactive tool config (requires terminal):
+### Interactive tool config:

 ```bash
 cd ~/.hermes/hermes-agent
@@ -83,11 +193,11 @@ source .venv/bin/activate
 python -m hermes_cli.main tools
 ```

-This opens a curses UI to enable/disable toolsets per platform.
+This opens a curses UI to enable/disable toolsets per platform (cli, telegram, discord, slack, etc.).

 ### After changing tools:

-Use `/reset` in the chat to start a fresh session with the new toolset. Tool changes do NOT take effect mid-conversation (this preserves prompt caching).
+Use `/reset` in the chat to start a fresh session with the new toolset. Tool changes do NOT take effect mid-conversation (this preserves prompt caching and avoids cost spikes).

 ### Common toolsets:

@@ -96,10 +206,10 @@ Use `/reset` in the chat to start a fresh session with the new toolset. Tool cha
 | terminal | Shell command execution |
 | file | File read/write/search/patch |
 | web | Web search and extraction |
-| browser | Browser automation |
+| browser | Browser automation (needs Browserbase) |
 | image_gen | AI image generation |
 | mcp | MCP server connections |
-| voice | Text-to-speech |
+| voice | Text-to-speech output |
 | cronjob | Scheduled tasks |

 ## Installing Dependencies
@@ -109,22 +219,43 @@ Some tools need extra packages:
 ```bash
 cd ~/.hermes/hermes-agent && source .venv/bin/activate

-pip install faster-whisper    # Local STT
+pip install faster-whisper    # Local STT (voice transcription)
 pip install browserbase       # Browser automation
-pip install mcp               # MCP servers
+pip install mcp               # MCP server connections
 ```

-## Setup Wizard
+## Config File Reference

-For first-time setup or full reconfiguration:
+The main config file is `~/.hermes/config.yaml`. Key sections:

-```bash
-cd ~/.hermes/hermes-agent
-source .venv/bin/activate
-python -m hermes_cli.main setup
+```yaml
+# Model and provider
+model:
+  default: anthropic/claude-opus-4.6
+  provider: openrouter
+
+# Agent behavior
+agent:
+  max_turns: 90
+  reasoning_effort: high    # xhigh, high, medium, low, minimal, none
+
+# Voice
+stt:
+  enabled: true
+  provider: local           # local, groq, openai
+tts:
+  provider: elevenlabs      # elevenlabs, openai, kokoro, fish
+
+# Display
+display:
+  skin: default             # default, ares, mono, slate
+  tool_progress: full       # full, compact, off
+  background_process_notifications: all  # all, result, error, off
 ```

-## Gateway Commands
+Edit with `hermes config edit` or `hermes config set KEY VALUE`.
+
+## Gateway Commands (Messaging Platforms)

 | Command | What it does |
 |---------|-------------|
@@ -136,19 +267,34 @@ python -m hermes_cli.main setup
 | /reasoning [effort] | Set reasoning level |
 | /sethome | Set home channel for cron/notifications |
 | /restart | Restart the gateway (picks up config changes) |
+| /status | Show session info |
+| /retry | Retry last message |
+| /undo | Remove last exchange |
+| /personality [name] | Set agent personality |
+| /skill [name] | Load a skill |

 ## Troubleshooting

 ### Voice messages not working
 1. Check stt.enabled is true in config.yaml
 2. Check a provider is available (faster-whisper installed, or API key set)
-3. Restart gateway after config changes
+3. Restart gateway after config changes (/restart)

 ### Tool not available
-1. Check if the toolset is enabled for your platform (run `hermes tools`)
+1. Run `hermes tools` to check if the toolset is enabled for your platform
 2. Some tools need env vars — check the env file
 3. Use /reset after enabling tools

+### Model/provider issues
+1. Run `hermes doctor` to check configuration
+2. Run `hermes login` to re-authenticate
+3. Check the env file has the right API key
+
 ### Changes not taking effect
 - Gateway: /reset for tool changes, /restart for config changes
 - CLI: start a new session
+
+### Skills not showing up
+1. Check `hermes skills list` shows the skill
+2. Check `hermes skills config` has it enabled for your platform
+3. Load explicitly with `/skill name` or `hermes -s name`