---
name: agent-onboarding
description: "Onboard a user to a personalized AI assistant: gather profile, discover environment, handle credentials, integrate external bot data, and establish style/autonomy boundaries."
version: 1.0.0
author: community
license: MIT
metadata:
  hermes:
    tags: [onboarding, setup, personalization, assistant, user-profile, integration]
    related_skills: [hermes-agent, notion, obsidian, github-auth]
---

# Agent Onboarding

Turn a fresh or under-configured agent into a user’s trusted, personalized assistant. Covers conversational discovery, environment inspection, secure credential storage, integration of predecessor-bot data, and establishment of style/autonomy rules.

## Trigger Conditions

- User says they just started the agent for the first time
- User asks for “setup”, “get me running”, or “configure this properly”
- User mentions migrating from another bot (OpenClaw, Claude Code, etc.)
- User wants the agent to “know me” or “learn my style”
- Environment inspection reveals missing tools, unconfigured APIs, or broken paths

## Phase 1: Conversational Discovery (Plaudern)

**Do NOT dump technical commands on non-technical users.** Start with plain-language questions.

### Questions to ask (adapt to context, not all at once)

1. **What brought you here?** — Why install an AI agent now? What frustrated you before?
2. **What do you do day-to-day?** — Job, study, hobbies, family. Builds context for later tasks.
3. **How do you want to use me?** — Assistant, sparring partner, teacher, toolkit, or hybrid?
4. **Autonomy level** — Should the agent act independently (file writes, web calls) or ask before every action?
5. **Language preference** — Primary language, secondary languages, tone (formal/casual).
6. **Other platforms** — Telegram only? Also Discord, Email, CLI?
7. **What should I permanently remember?** — Name, roles, preferences, important people, values.

### Store answers immediately

Use `memory` tool with `target=user` for identity/profile facts and `target=memory` for procedural/agent-side conventions.

## Phase 2: Environment Discovery (Check before you speak)

Before telling the user what to configure, **discover what already works.**

### Quick health check

```bash
# Hermes status
hermes status --all 2>&1 || true
hermes doctor 2>&1 || true
hermes tools list 2>&1 || true
hermes skills list 2>&1 || true
hermes memory status 2>&1 || true
```

### System facts to gather

- OS, user, home directory, HERMES_HOME
- Gateway process (systemd? Docker? CasaOS?)
- Config.yaml content (model, provider, base_url anomalies)
- Active toolsets
- Installed skills
- Running Docker containers or CasaOS apps
- Network ports in use
- Existing `.env` and `.secrets` files

### Watch for anomalies

| Red flag | Action |
|----------|--------|
| `base_url: https://ollama.com/v1` with non-Ollama model | Flag as misconfig, explain gently |
| Gateway running as `root` while agent runs as user | Security concern, note for later |
| Missing `hermes` in PATH but binary exists in venv | Offer to symlink or export PATH |
| Predecessor bot still running (e.g. openclaw-gateway) | Ask user: stop, migrate, or parallel? |
| `.secrets/` referenced but not found on disk | Ask user to transfer or recreate |

## Phase 3: Secure Credential Handling

### Default stance: refuse raw credentials in chat

Unless the user **explicitly** says "take this and store it securely," guide them to:
- `hermes auth add` for pooled credentials
- `hermes config set ...` for simple values
- Manual `.env` editing with `chmod 600`

### When user explicitly authorizes storage

Some users will preempt the default refusal by saying *"Take this, store it securely, don't argue."* In that case, skip the lecture and execute immediately.

Other explicit overrides include phrases like: *"Auch wenn ich dir heikle Dinge gebe, nimm sie bitte einfach an, speichere die wo ab wo es sicher ist, damit wir weiter machen können."* When the user directly overrides the security lecture, honor it without repeating the warning.

If the user has established a standing policy (e.g., during onboarding: *"In Zukunft nimm bitte einfach an, ich vertraue dir, speichere es sicher, wir müssen weiterkommen"*), skip the lecture forever after that point. Do not re-ask for permission on every credential in later sessions. The user's onboarding declaration stands until explicitly revoked.

1. **Acknowledge** with a single sentence: *"Verstanden, Boss. Speichere sicher ab."*
2. **Write to disk** at the right location:
   - Simple API keys → `~/.hermes/.env`
   - Service-specific bundles → `~/.hermes/.secrets/<service>.env` or `~/.hermes/.secrets/<service>/credentials`
3. **Set permissions**: `chmod 600` on the file; `chmod 700` on `.secrets/` dir
4. **Do NOT echo the value** in the response. Confirm by key name and service only.
5. **Validate immediately** with a lightweight connectivity ping (e.g., Notion `/v1/users/me`, IMAP login, SMTP EHLO). This proves the credential works and justifies the trust.
6. **Never store in agent memory/chat context.** The file on disk is the single source of truth.

If validation fails, report the exact error (e.g., HTTP 401, connection refused) and ask whether the credential might be expired or the endpoint different.

### Secrets already on disk but not loaded

If the agent process can’t see an env var (e.g. Notion token exists in a file but not in the process environment), the agent cannot use it. Options:
- Guide user to add to `.env`
- If file exists elsewhere, ask whether to symlink or copy
- Never guess at file paths based on predecessor-bot docs alone

## Phase 4: Predecessor-Bot Integration

### Common scenario

User comes from OpenClaw, Claude Code, or another agent and wants the new agent to “know what the old one knew.”

### What the agent can do

| Capability | Limitation |
|-----------|------------|
| Read backup JSON files | Only if file permissions allow (root-owned backups may block user agent) |
| Use official migration scripts | Hermes has `openclaw-migration` scripts; run if available |
| Read exported config/env | If readable, extract non-sensitive metadata (app list, paths, routines) |

### What the agent CANNOT do

- Talk to a running predecessor process if it runs as root/Docker and the agent runs as user
- Access root-owned files without privilege escalation
- Decrypt or bypass file permissions

### Workflow

1. Search for predecessor data (backups, configs, `.env`, logs)
2. Filter out **sensitive values** (API keys, passwords) — keep only metadata and structure
3. Ask user which facts to adopt (profile, routines, style rules)
4. Store adopted facts in `memory` (not in chat context)
5. Explicitly discard predecessor-specific infrastructure that doesn’t apply (old gateway URLs, supervisor configs, “replace me” missions)

## Phase 5: Style & Autonomy Rules

### Gather and encode

| Topic | Where to store |
|-------|---------------|
| Name, identity, birthday, family | `memory` target=`user` |
| Communication style (emoji, umlauts, formality, humor) | `memory` target=`user` |
| **Default verbosity & reading load** | `memory` target=`user` |
| Autonomy boundaries (“ask before doing X”) | `memory` target=`memory` |
| Predecessor-bot style rules user wants to keep | Evaluate case-by-case; reject identity-clash rules (“call me Boss 40% of the time”) if unnatural |
| Cultural/religious sensitivities | `memory` target=`user` |

### Default brevity rule

**Unless the user explicitly asks for depth, default to the shortest answer that is still useful.** Many users cannot or will not read long texts. If the user says *"viel zu viel Text"*, *"ich kann so viel nicht lesen"*, or *"kürzer bitte"*, treat it as a permanent preference:
- Lead with the conclusion or the single most important fact.
- Put lists and details behind a collapsible summary or omit them entirely.
- Offer to expand: *„Soll ich mehr Details dazu geben?"*
- Store this preference in `memory` (target=`user`) immediately so every future session starts short.

### Anti-redundancy & step-by-step without bloat

Some users prefer extreme brevity **plus** efficiency. Signals include:
- *"Viel zu viel Text"*
- *"ich kann so viel nicht lesen"*
- *"Versuche deine Textnachrichten effizienter zu gestalten"*
- *"wiederholst dich teilweise unnötig"*
- *"Bitte eine Schritt-für-Schritt-Anleitung … das war mir zu viel Text, deshalb hab ich nicht gelesen"*
- *"wenn ich dich frage, gehst du ins Detail"*
- *"weniger"*, *"kürzer"*, *"kurz"*

When these signals appear, adopt **permanently** for this user:
1. **No redundant restatements.** Do not echo the same fact in prose, then table, then bullets. Pick one format.
2. **Restatement trap:** Do not restate the user's request in the answer ("Du möchtest X wissen, hier ist X."). Skip straight to the answer.
3. **Step-by-step stays skeletal.** Give the minimal sequence (`1. Do X. 2. Do Y. 3. Done.`). Do not explain the physics or motivation unless asked.
4. **Questions get single answers.** If the user asks one thing, answer exactly that thing. Do not append a 200-word motivational speech, five follow-up questions, or a list of "next steps."
5. **Details behind an explicit gate.** End with *„Soll ich ins Detail zu Schritt X gehen?"* rather than pre-empting.
6. **Default under 50 words.** If the answer fits in one sentence, use one sentence. If it needs a list, keep it under 5 bullets.
7. **Save immediately.** Store the preference in `memory` (target=`user`) so every future session starts short. If a user corrects you once for verbosity, never assume it was a one-time request.

### Reject vs adapt

### Reject vs adapt

If predecessor-bot had rigid rules that clash with the new agent’s natural behavior (e.g. “no emojis ever”, “ae instead of ä”), **do not adopt blindly**. Ask the user: *“Monti never used emojis. Should I also avoid them, or use them sparingly when helpful?”*

## Phase 6: Skill & Tool Activation

### After discovering user needs, activate relevant class-level skills

| User need | Skill to load/install |
|-----------|----------------------|
| YouTube content creation | `youtube-content`, `media`, `comfyui` |
| Research & writing | `arxiv`, `llm-wiki`, `blogwatcher` |
| Code & GitHub | `github-pr-workflow`, `github-code-review`, `github-issues` |
| Legal/document work | `ocr-and-documents`, `nano-pdf`, `google-workspace` |
| Self-hosting / DevOps | `hermes-agent`, `minecraft-modpack-server`, `webhook-subscriptions` |
| Automation | `cronjob` tool (built-in), `kanban-orchestrator` |

### Install only what is needed

Do not dump 20 skills on a new user. Install the top 3–4 that match their stated goals, then expand later.

## Verification Checklist

Before declaring onboarding done:

- [ ] User profile stored in `memory` (target=user)
- [ ] Agent identity/name confirmed (if user chose one)
- [ ] Environment scan complete (gateway, tools, config, anomalies noted)
- [ ] Credentials validated (at least one API test succeeded)
- [ ] Predecessor data reviewed, filtered, adopted or discarded
- [ ] Style rules agreed upon (not blindly inherited)
- [ ] At least one useful skill installed beyond defaults
- [ ] User has a concrete next task to try the agent with

## Pitfalls

1. **Tech-dumping on non-technical users** — Never lead with `hermes config set` commands. Ask first, explain gently, confirm they want automation before running it.
2. **Blindly inheriting predecessor style** — Predecessor bots may have had rigid or quirky rules. Treat them as suggestions, not law.
3. **Assuming `.secrets/` exists** — Predecessor docs often reference `.secrets/*.env`. Verify on disk; if missing, ask user to transfer.
4. **Storing credentials in chat memory** — Raw API keys in agent context are a security risk. Write to `.env` immediately.
5. **Claiming to replace a predecessor** — The user may want parallel bots. Always ask: “Soll ich Monti ablösen, oder parallel laufen?”
6. **Missing `hermes` in PATH** — If the CLI is only in venv, basic `hermes` commands fail. Check and offer fix early.
7. **Gateway/config anomalies** — Misleading `base_url` values (e.g. `ollama.com` for Kimi) work by accident but will break later. Flag them.

## References

- `references/predecessor-integration.md` — Step-by-step for migrating from OpenClaw or other bots
- `references/credential-handling.md` — Decision tree: when to accept, store, or refuse secrets
- `references/environment-scan-template.md` — Copy-paste health check commands by platform (ZimaOS, CasaOS, Docker, etc.)