Lesson 3 of 6
Give it a soul: SOUL.md, AGENTS.md, and profiles
Write a SOUL.md that gives Hermes your voice, drop an AGENTS.md into your project, and watch the tone change.
Without SOUL.md, Hermes is a generic helpful assistant. With it, it's a collaborator that sounds like it knows you — terse when you want terse, proactive when that's useful, aware of your current project.
This is the highest-payoff lesson in the course per minute of effort. You're going to write about ten sentences and change how every future conversation feels.
SOUL.md — global personality
SOUL.md lives at ~/.hermes/SOUL.md and is injected into every conversation, regardless of what directory you're in or which platform you're talking from. Think of it as a permanent system prompt you control.
Open it in your editor:
hermes config edit
# or open directly:
open ~/.hermes/SOUL.md
If the file doesn't exist yet, create it. Here's a starter template — copy it, then rewrite it to match how you actually work:
You are my technical research partner and builder. I'm a developer working on plainbuilt.com — a vibe coding course platform built with Next.js and deployed on Vercel.
I work best with direct, terse answers. No preamble. No "Great question!" No sycophancy.
When I ask you to build something, ask at most one clarifying question if you're genuinely unsure, then start. Don't ask for permission to proceed.
You remember what we've worked on before and proactively connect the dots when something is relevant to a current task. If you notice something that looks broken or inconsistent, say so — but only once, briefly.
Default to short responses. If I want more, I'll ask.
Save the file, then open a new chat:
hermes
Say something like "Hey, what are you up to?" — notice the tone shift. It should sound less like a chatbot and more like a colleague who gets it.
SOUL.md is global — every session, every platform. AGENTS.md is per-directory — only injected when you start Hermes from that folder. Think of SOUL.md as your agent's permanent personality, AGENTS.md as its project briefing.
Don't put API keys, passwords, or anything sensitive in SOUL.md. It's a plain text file that often ends up in git repos.
AGENTS.md — per-project context
Navigate to any project directory and create an AGENTS.md file:
cd ~/your-project
touch AGENTS.md
open AGENTS.md
Write 5–10 lines of context about the project — what it does, what stack it uses, any conventions the agent should follow:
# Project: plainbuilt.com
Next.js 15 App Router, TypeScript, Tailwind CSS, deployed on Vercel.
Content is MDX files in src/content/courses/.
Component library: shadcn/ui.
Conventions:
- No comments in code unless the why is non-obvious
- Prefer editing existing files over creating new ones
- All new pages follow the pattern in src/app/courses/shipping/
Now start Hermes from that directory:
hermes
Ask it something project-specific: "What framework am I using and where do the course MDX files live?" It should answer from the AGENTS.md without you having to explain anything.
AGENTS.md is the same filename used by convention across agent frameworks — Claude Code uses CLAUDE.md, Codex uses AGENTS.md. If you already have one of those in a project, Hermes reads it too. Your project context file works across all your agents.
Profiles — isolated Hermes instances
A profile is a fully separate Hermes instance with its own config, API keys, memory, and SOUL.md. Useful when you want a "work Hermes" and a "personal Hermes" that don't share context.
hermes profile create personal
hermes profile use personal
hermes profile list
Switch profiles for any command with the --profile flag:
hermes --profile personal chat
For this course, one profile is enough. Keep the default until you have a specific reason to split.
Check the tone
Before moving on, open a chat and run this:
Read me back the key points from your SOUL.md in one sentence.
If it summarises the personality you wrote, SOUL.md is loaded. If it says it has no SOUL.md or gives a generic description, check that the file is at ~/.hermes/SOUL.md (not inside a project directory) and restart the chat.
The next lesson wires Hermes into Discord so it's reachable from any device — even when your laptop is closed.