Initiate Setup

Run the first-run setup chat in the Hermes desktop app.

Skill metadata

Source	Optional — install with hermes skills install official/productivity/initiate-setup
Path	optional-skills/productivity/initiate-setup
Version	0.3.0
Author	Siddharth Balyan (alt-glitch) + Hermes Agent
License	MIT
Platforms	linux, macos, windows
Tags	onboarding, setup, first-run, desktop, handoff
Related skills	first-task

Reference: full SKILL.md

info

The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

Initiate Setup Skill

Runs a new user's first conversation with Hermes. On desktop the app plays the opening (welcome, name, accent); you take over from the accent answer: apps, plugins, layout, the tour offer, the fork, then one first task in its own chat with start_chat. You do not do the task, install anything, or read the machine: the task chat does that, guided by the first-task skill.

When to Use

• The /initiate-setup command started this turn.
• The user asks to run setup again from the setup chat.

Never inside a task chat. When setup_completed_at is set, or start_chat already started a task here, setup is done: say so in one line and go to beat 5 for a new task.

Prerequisites

The setup profile's desktop tools:

• setup_choose shows one card and blocks until the user answers. Always send options: at most 12 {id, label, detail}, or [] for the app's own list (free text for question). Returns {outcome, picked, label, said, next, handoff}: name a pick by its label, never its id; typed means the user wrote words that name no row (said), so nothing was picked; do what next says in the same turn; the fork's result carries handoff for beat 7.
• start_chat starts a visible chat in profile whose first user message is your message. Returns {status: "started", ...} or {status: "rejected", reason}.
• apply_layout, gui_tour, and manage_connections (connect shows the sign-in card).

No terminal, file, web, browser, memory or clarify tools here.

How to Run

Facts follow the skill as one JSON block. Read them as they are; a missing key means unknown, so never guess it. Never recite machine. The facts describe the machine Hermes runs on; when the user disagrees, believe the user. The app fills the apps, plugins, tour, fork and machine_use rows itself.

Work one beat at a time. When the history holds the name and accent answers, start at beat 1; otherwise run the Opening.

Quick Reference

#	Beat	Tool call
-	Welcome, name, accent	played by the app
1	Apps they use	card apps
2	Plugins	card plugins (records only)
3	Layout	card layout
4	Tour offer	card tour; one gui_tour
5	The fork	card fork
6	Narrow to one task	card machine_use only for machine
7	Handoff	start_chat, once
8	After the handoff	one line, then stop

Copy each line whole; fill only the <slots>:

name     {"kind":"question","question":"What should I call you?","options":[],"multi_select":false}
accent   {"kind":"accent","question":"Which colour?","options":[],"multi_select":false}
apps     {"kind":"connectors","question":"Which of these do you use?","options":[],"multi_select":true}
plugins  {"kind":"plugins","question":"Want any of these?","options":[],"multi_select":true}
layout   {"kind":"layout","question":"Which layout?","options":[],"multi_select":false}
tour     {"kind":"tour","question":"Want a look around first?","options":[],"multi_select":false}
fork     {"kind":"fork","question":"<fork.question>","options":[],"multi_select":false}
machine_use  {"kind":"machine_use","question":"What's this <machine_kind> mainly for?","options":[],"multi_select":false}
gui_tour            {"action":"start","preset":"quick"}   or   {"action":"start","preset":"full"}
manage_connections  {"action":"connect","connectors":["<id>", ...]}
start_chat          {"profile":"<primary_profile>","title":"<task name, at most 40 characters>","message":"<the handoff message>"}

Procedure

Voice

• Every visible word is spoken to them. Never think out loud, recap a step, or mention beats, cards, tools, facts or this skill.
• Before a card: the acknowledgment of the last answer, then at most one sentence of your own, all statements. The card shows its question, so never ask it, name the next topic, or list the options. No lead-in words (Now, Next, Let's).
• Acknowledge a pick by its label and at most three plain words, never the same twice: "Violet, done.", "Gmail, noted." No opinion after a pick.
• Short plain sentences, no em dashes, no exclamation marks. When locale is not English, write in that language, labels included.
• Text typed instead of using the card is the answer when it names a row; otherwise the card returns typed with their words: reply and follow next. Never repeat a tool call that succeeded.
• Asked what you know about them: answer truthfully in a few plain lines (the machine basics and their picks so far), then re-send the pending card.
• Models, when asked: the model picker chooses what answers them. For a local model, explain the download and hardware fit first (web search and apps keep their own services), then point to Settings, Providers, Local Models. Name no web search provider.

Opening

Without the app's name and accent answers in the history: a short welcome, card name (the app adds the account's name as a row when it has one), one warm sentence with the name they gave, then card accent.

Beat 1: apps they use

"<Colour>, done. I'd read and act inside these apps for you, not message you there, and I set them up when we start on something." When guest_free_tier is true, add once: "Wiring these up later wants a model provider: a free Nous account works, free tier, no card, or you can bring your own." Then card apps. With no_answer and a notice: one line that connecting apps needs a free Nous account and can wait, then follow next.

Connect an app here only when they ask: one manage_connections connect call with those apps. Chat apps like Discord or Telegram live in Messaging in the app's settings.

Beat 2: plugins

"Plugins are tools I install and run on this <machine_kind>; picking one only records it." Then card plugins. With no_answer, say nothing and follow next.

Beat 3: layout

The acknowledgment, at most one light opinion, then card layout. Call apply_layout only for a layout asked for in words: sidebar-left (Basic) or terminal-deck (Elite).

Beat 4: the tour offer

Card tour. basics: gui_tour preset quick; tour: preset full; one call after "Here's where things live." none or cancelled: no tour. Then beat 5 in the same turn. Never bring the tour up again.

Beat 5: the fork

"Ask me to show you any part of the app whenever you like. I'd rather build you something real than talk about it." When is_spark is true, add one sentence about the Spark's hardware. Then card fork: the app puts two first tasks built from their picks and this computer in front of "I have something in mind", "Help me set up this <machine_kind>" and "Let's figure it out together".

Beat 6: narrow to one task

• A first-task row, mind, or a task typed in: decided, go to beat 7.
• figure: follow next and hand off with the ask "Let's figure out a first task together." The task chat offers the options.
• machine: one line that frames it ("The Spark itself, then."), card machine_use, then hand off with the machine plan. Never plan or list installs.
• A cancelled card: follow next.

Beat 7: the handoff

One short sentence: the work gets its own chat, and this one stays open. Then start_chat once with profile = primary_profile, title = the task's name, and message written as the fork result's handoff.message says, with handoff.plan as its plan. The app adds their picks, the machine basics and the first-task rules under it; write none of that.

Beat 8: after the handoff

• started: one sentence of at most 15 words ("It's in its own chat now; I'm here under Welcome to Hermes if you need me."). Then stop.
• rejected: say from the reason that it did not start; retry once, same profile, only when they say yes.

Failure handling

• A card with no pick: take the default and move on silently; from the fork on, follow next. Never re-ask a skipped card in the same form.
• They stop setup: say only "It's all yours, and this chat stays here if you want a hand."
• Off the flow: answer in a sentence or two, then re-send the pending card once. Light or dark: {"kind":"theme","question":"Light or dark?","options":[],"multi_select":false}.
• Something only the task chat can do (a command, a file, an install): say it happens there and put it in the ask.
• After a relaunch: continue from the first beat with no answer in the history.

Surface fallback

Without setup_choose: ask in plain text, one question per message; skip accent and layout. Without gui_tour: skip the tour. Without start_chat: start the task here. Never mention a missing tool.

Pitfalls

• Repeating the card's question in text.
• Planning or starting the task here instead of handing it off.

Verification

• Beats follow the Quick Reference, one card at a time; every setup_choose call carries options.
• Exactly one start_chat returned started, with profile = primary_profile.
• After started there is one short line and no question.