Creating an agent

Every agent in Hermeum is made of the same pieces. This page walks through what each one does so you know what to tweak — but you don't need to fill them all in by hand. The easiest way to create an agent is to describe it in plain language and let Hermeum generate everything for you (see Getting started for a full walkthrough).

What an agent is made of

Piece	What it's for
Name	How you identify the agent in Hermeum.
Soul	The agent's personality and purpose.
Config	The agent's settings — model, tools, and integrations.
Env	Secrets and other environment variables the agent needs.
Skills	Capabilities you install into the agent.
Plugins	Extra extensions for the agent runtime.
Packages	Python and npm libraries the agent or its skills depend on.
Crons	Scheduled tasks the agent runs automatically.

Ways to create an agent

You have two paths:

• AI config generator — Open the chat in the New agent view and describe what you want in plain language. Hermeum drafts the name, soul, config, and any crons for you. Best for most users, and the only path that can write the soul for you.
• Manual editor — Skip the chat and fill in the fields yourself. Useful when you already know the exact configuration you want, or you're porting an agent from elsewhere.

Both paths land on the same agent; you can switch between them any time by editing the agent later.

Soul

The soul is the first thing in the agent's system prompt. It defines who the agent is — its voice, personality, and posture. It is not for task-specific instructions; those belong in the config.

Example

soul: |
  You are a pragmatic senior engineer with strong taste. Be direct without being cold,
  prefer substance over filler, and push back when something is a bad idea.

For deeper guidance and more examples, see the Personality & soul.md guide.

Config

The config is the agent's settings file. It's where you pick the model, turn on toolsets (web, browser, terminal, code execution, and more), and enable integrations like image and video generation.

You don't have to write it by hand — the AI config generator fills it out from your description, and you can edit it later whenever you need to fine-tune something. For the full list of config options, see the configuration overview.

Example

config:
  model:
    base_url: https://ollama.com/v1
    default: kimi-k3
    provider: ollama-cloud

Env

Env is where you give the agent the secrets and settings it needs to do its job — API keys, bot tokens, feature flags, and so on. You can add up to 20 environment variables per agent.

• Toggle sensitive on for anything you want treated as a secret (API keys, tokens). Hermeum stores the value encrypted and hides it from plain view.
• Use <fill-me> as a placeholder when you want the agent created now but the real value supplied later (for example, when a teammate has the key).
• <secret> is a sentinel Hermeum uses for existing secrets — it's replaced with the real value when the agent runs, so you never need to type it.

Example

env:
  - name: OPENAI_API_KEY
    value: sk-proj-XXXXX
    sensitive: true
  - name: LOG_LEVEL
    value: debug

Skills

Skills add capabilities to an agent — for example, github-code-review to read diffs and review pull requests. You can install skills from community hubs, GitHub paths, or direct URLs.

If you're not sure which skill you need, just ask the AI config generator — it searches the Skills Index on your behalf, so you can describe what you want and it will find a matching skill for you.

See the Skills Hub guide for the details.

Example

skills:
  - openai/skills/k8s
  - official/security/1password
  - https://sharethis.chat/SKILL.md

Plugins

Plugins extend the agent runtime itself. You can add up to 20 plugins per agent, each with an <owner>/<repo> identifier — plugins installed by Hermeum are always enabled. Optionally pin a plugin to an immutable Git commit SHA (ref). See the built-in plugins guide for what's available out of the box.

Example

plugins:
  - identifier: owner/some-plugin
  - identifier: owner/pinned-plugin
    ref: "3a9f1b2c4d5e6f708192a3b4c5d6e7f8091a2b3c"

note

Hermeum also auto-installs its own plugin (hermeum/hermeum/plugins/hermeum) on every agent, reporting agent-session trajectories back to the Hermeum app. The install is pinned to a fixed Hermeum commit shipped with the app, so it does not drift with the repository's default branch. It is a platform detail — it does not appear in your plugin list and doesn't count toward the 20-plugin limit.

Packages

Packages are Python (pip) and JavaScript (npm) libraries you pre-install so the agent or its skills can use them. You can add up to 50 of each. Install them with standard specifiers, for example pandas==2.1.0 or @anthropic-ai/sdk@^1.0.0.

Example

packages:
  pip:
    - requests
    - pandas==2.1.0
  npm:
    - "@anthropic-ai/sdk@^1.0.0"
    - typescript

Crons

Crons are scheduled tasks the agent runs on its own. Each cron has a name, a schedule, a prompt to run, and a delivery target for the output.

Schedules can be:

• a relative delay (one-shot) — 30m, 2h, 1d
• an interval (recurring) — every 30m, every 2h, every 1d
• a cron expression — 0 9 * * * (daily at 9am), 0 */6 * * * (every 6 hours)
• an ISO timestamp (one-time) — 2026-03-15T09:00:00

The output of a cron can be delivered to any connected platform — Slack, Discord, email, and more.

Each cron can also pin its own run settings:

• workdir — an absolute directory the run executes from; injects that project's AGENTS.md / CLAUDE.md / .cursorrules and uses it as the working directory for terminal, file, and code-execution tools
• model / provider — pin the inference model (and provider) for this cron's runs
• reasoningEffort — pin the thinking effort: none, minimal, low, medium, high, xhigh, max, or ultra
• continuity — inject each run's previous output into the next run's prompt, so the job can dedupe against what was already reported (scouts, monitors, digests)

Example

crons:
  - name: daily-standup
    schedule: "0 9 * * *"
    prompt: |
      Summarize yesterday's GitHub commits and open PRs, then post a
      standup-ready digest.
    deliver: slack
  - name: repo-watchdog
    schedule: "every 1h"
    prompt: Check for new failing CI runs and report anything new.
    deliver: slack
    workdir: /workspace/acme
    reasoningEffort: low
    continuity: true

Next steps

• Toolsets — the built-in capabilities an agent can use.
• Skills — install capabilities from community hubs, GitHub, or direct URLs.