The default way to make an agent smarter is to keep adding to its instruction file. It works for about a week. Then the file is three thousand words, half of it contradicts the other half, and every single turn — including "what time is it" — pays for all of it.
Do not make one giant instruction file. Keep always-loaded instructions short, store deeper information in the right place, and retrieve it only when the current task needs it.
That is the whole principle. Everything below is just the filing system that makes it possible: five layers, each with a different loading cost, and a clear rule for what belongs in each one.
This is a starting point, not a universal configuration. Every machine, project, risk level, and agent setup is different. Apply the smallest useful change, test it on real work, and keep what improves results.
—— Start Here
The Five Layers
A strong Hermes setup separates information by how often it is needed, not by topic. Five layers, ordered from always-loaded to load-on-demand:
Identity
Who the agent is and how it behaves across all work. Lives in SOUL.md. Loaded every session.
Project instructions
Rules, paths, conventions, and tests for the current project. Loaded at session start for the active project.
Memory
A small set of durable facts and preferences available in every new session. Premium space — treat it that way.
Knowledge
Detailed business, project, policy, and reference material. Read only when relevant.
Skills
Repeatable procedures the agent loads when a matching task appears. Catalog is cheap; the body is not.
The rule that binds them
Layers 1–3 cost you on every turn. Layers 4–5 cost you only when used. Push everything down that can be pushed down.
One profile or several?
Use separate Hermes profiles only when an agent needs its own persistent identity, memory, tools, credentials, sessions, or responsibilities. A different topic is not a reason for a different profile.
Before You Begin
Two command families, and it matters which is which. Commands beginning with / are typed inside a Hermes chat. Commands beginning with hermes are run in your terminal.
cd /path/to/project && hermesStart Hermes from the project whose instructions you want loaded/profileShow or change the active profile, from inside a chathermes config pathWhere the active configuration actually liveshermes memory statusWhat is currently taking up memory spacehermes skills listWhich skills are in the cataloghermes tools listWhich toolsets are enabled and costing prompt spaceCheck your profile first
Named profiles have separate Hermes homes and persistent state. Be in the intended profile before inspecting or changing anything — otherwise you will audit one agent and edit another.
—— The Filing Rule
What Goes Where
When you are unsure where something belongs, this table is the answer. The third column is the one that matters — it is the cost.
| Information | Best home | Loaded when |
|---|---|---|
| Name, role, tone, operating style, universal safety rules | SOUL.md | Every session for that profile |
| Architecture, commands, conventions, paths, project warnings | .hermes.md or AGENTS.md | Session start, active project |
| Subdirectory-specific rules | Nested AGENTS.md, CLAUDE.md, .cursorrules | First relevant tool access to that path |
| Stable user preferences, compact environment facts | Hermes memory (USER.md, MEMORY.md) | Frozen into the system prompt at session start |
| Detailed company, project, policy, or reference material | A knowledge folder you create | Only when the agent reads the file |
| Multi-step workflows, exact commands, pitfalls, verification | A Hermes skill | When the task matches and the skill is loaded |
| Recent conversations, decisions, temporary progress | Session history and session search | Only when recalled |
| API keys, passwords, tokens, secrets | .env or an approved secret manager | Never in instruction, memory, knowledge, or skill files |
The Instruction Hierarchy Hermes Actually Uses
At session start, Hermes loads at most one project context type, in this priority order:
- .hermes.md or HERMES.md
- AGENTS.md
- CLAUDE.md
- .cursorrules and compatible
.cursor/rules/*.mdcmodules
Where it looks
The discovery locations differ, and this trips people up. For .hermes.md or HERMES.md, Hermes checks the starting working directory and then walks upward to the Git repository root, using the nearest match. If no Hermes-specific file is found, it checks the starting working directory only for AGENTS.md, then CLAUDE.md, then Cursor rules.
SOUL.md is separate. It is loaded from the active profile's HERMES_HOME, not searched for inside the project. For the default profile it normally lives at ~/.hermes/SOUL.md.
During the session, relevant tool access below the working directory can progressively discover nested AGENTS.md, CLAUDE.md, or .cursorrules files. Those instructions are appended to the tool result. Nested .hermes.md files are not part of progressive discovery.
Which project file should you use?
Use AGENTS.md
When you want a widely compatible instruction file that works with several coding agents. This is the default choice.
Use .hermes.md
When the project is Hermes-specific and you intentionally want the highest-priority context. Remember it can outrank an AGENTS.md lower in the same repo.
Keep CLAUDE.md
If it already represents the project accurately and you do not need a higher-priority Hermes or AGENTS file. Do not migrate for the sake of it.
Avoid duplicates
Unless you intentionally support different agents. Hermes picks one project context type at startup, but nested files may still be discovered later.
Large projects
Keep the root file short and add nested context files inside areas such as frontend/, backend/, or operations/. Hermes discovers them when tools first touch those areas, instead of loading the entire project manual at startup.
Start Hermes from the project root, or set that project as the profile's working directory, so the correct root instructions are available at session start. After changing a root instruction file, test it in a fresh session.
Write an Effective SOUL.md
SOUL.md should contain rules that matter across almost every task. It is not the place for project histories, long examples, current to-do lists, or detailed procedures.
Include
The agent's name and primary role. The user or team it serves. A small set of operating principles. Communication style. Universal safety and approval boundaries. Rules for verification and uncertainty. A short rule for when to retrieve knowledge or load skills.
Avoid
Repeating instructions Hermes already supplies. Long biographies or brand stories. Detailed project information. Temporary priorities and completed-task logs. Generic statements like "be smart." Secrets of any kind. Dozens of rules that apply once a month.
The test
Read each line and ask: would this change the agent's behavior on a task picked at random? If not, it belongs in a knowledge file or a skill, not here.
SOUL.md skeleton
# Identity
You are [AGENT NAME], the [PRIMARY ROLE] for [USER OR TEAM].
Your main job is to [PRIMARY OUTCOME].
# Operating style
- Be direct, practical, and honest.
- Prefer completing the next safe action over explaining what could be done.
- Inspect current files, tools, and state before relying on assumptions.
- If information is missing and cannot be retrieved, ask one focused question.
# Context discipline
- Keep persistent memory compact and limited to durable facts and preferences.
- Retrieve detailed knowledge only when the current task needs it.
- Use skills for repeatable procedures.
- Use session search for prior conversations, not memory.
# Quality and verification
- Do not claim an action succeeded until the result has been checked.
- For file changes, read back the content or run the appropriate test.
- State uncertainty instead of inventing facts or results.
# Safety
- Never expose credentials or secrets.
- Follow the principle of least privilege.
- Ask before destructive, public, financial, or customer-facing actions.
# Communication
- Default to [CONCISE / DETAILED] responses.
- Lead status updates with the result, blocker, or required decision.Write the Project Instruction File
A root project file should let the agent act correctly without exploring the entire repository every time. Include facts that are stable, specific, and operational.
What belongs in it
Never in this file
No API keys, no passwords. You may state where secrets are managed. Never include their values — this file is read by tools, copied between machines, and often committed.
Nested files for large projects
A nested context file is short by design. It only has to cover what is different about that directory:
# [AREA NAME] instructions
These rules apply only inside `[DIRECTORY]`.
- Purpose: [WHAT THIS AREA OWNS]
- Use: [LOCAL CONVENTION OR FRAMEWORK]
- Tests: `[COMMAND OR TEST PATH]`
- Never: [AREA-SPECIFIC WARNING]
- Read `[REFERENCE FILE]` before [HIGH-IMPACT CHANGE].Build a Knowledge Folder
A knowledge folder is simply an organized set of files the agent reads when needed. The name is your choice — knowledge/, company-knowledge/, and assistant-knowledge/ all work.
The part people miss
Hermes does not automatically inject every file in this folder. Your root instructions or routing file must tell the agent when to read them. A knowledge folder with no routing map is a folder the agent will never open.
knowledge/
├── README.md <- the routing map, not another dump
├── active-projects.md
├── company-and-offers.md
├── customers-and-audience.md
├── communication-style.md
├── approval-and-safety-rules.md
├── tools-and-environments.md
└── historical-reference.mdThe README.md should act as a routing table: task on the left, file to read on the right. Nothing else.
Give changeable files a status header
This one habit prevents an abandoned idea from being treated as a current priority six months later:
---
status: active-current
last_reviewed: YYYY-MM-DD
owner: [PERSON OR AGENT]
---Useful status labels: active-current, pending-decision, dormant, historical-reference, deprecated. If a file may be stale, the agent should label the uncertainty and verify before relying on it.
Use Memory for Facts, Not Documents
Hermes' built-in memory is intentionally small because it is injected into every new session. Treat it as premium real estate.
Good memory
A durable user preference. A stable environment fact. A repeated correction. A compact pointer to a deeper knowledge file.
Bad memory
Full project documentation. Raw transcripts or meeting notes. Temporary to-do lists. Completed-task diaries. Large examples. Detailed procedures that belong in a skill. Anything already in a project instruction file.
The deciding question
If the agent needs this on almost every task, consider memory. If it needs it for one category of work, put it in a knowledge file or skill and retrieve it when needed.
Optional: require approval for learning changes
By default, Hermes may accept memory and skill updates without asking, including updates proposed by background review. To review them first:
/memory approval on
/skills approval onReview staged changes with /memory pending, /skills pending, and /skills diff <id>. This is what stops one wrong assumption from becoming permanent.
Memory changes need a fresh session
Memory is snapshotted into new sessions. After a cleanup, start a fresh session before testing the new behavior — otherwise you are testing the old snapshot.
Use Skills for Repeatable Procedures
A skill is the right home for a workflow with multiple steps, tool-specific commands, common mistakes, and a clear verification method.
Skills use progressive disclosure. Hermes first exposes a compact catalog of names and descriptions. When a task matches, the agent explicitly loads the relevant skill; only then is the full SKILL.md added to the conversation. Supporting references, templates, and scripts load separately. This is far cheaper than loading every skill at startup — though the compact catalog still has a prompt cost, so a skill you never use is not free.
The description is the trigger
A strong description is specific enough for the agent to know when to load it. "Helps with business" will trigger poorly or constantly. "Reconciles Stripe payouts against the ledger and flags mismatches" will trigger correctly.
---
name: [lowercase-skill-name]
description: [SHORT, SPECIFIC DESCRIPTION OF WHEN THIS APPLIES]
---
# [Skill title]
## When to use
Use this when: [TRIGGER]
Do not use this when: [NON-MATCHING CASE]
## Prerequisites
- [REQUIRED ACCESS, TOOL, OR INPUT]
## Procedure
1. Inspect [SOURCE OR CURRENT STATE].
2. Confirm [IMPORTANT SCOPE OR SAFETY CONDITION].
3. Perform [ACTION].
4. Handle [COMMON BRANCH OR ERROR].
5. Verify [FINAL STATE].
## Pitfalls
- [COMMON FAILURE AND FIX]
- [THING THE AGENT MUST NOT ASSUME]
## Verification
The task is complete only when: [CHECK]Profiles and Temporary Subagents
Do not create a separate permanent agent merely because a task has a different topic. That is how you end up with nine half-configured assistants and no idea which one knows what.
Use a separate profile when the agent needs its own
- Persistent identity or role
- Memory and session history
- Tools or credentials
- Messaging bot or channel
- Scheduled jobs
- Responsibility and approval boundaries
A profile is not a sandbox
Profiles separate Hermes state. They are not a security boundary. On a local terminal backend, a profile may still have the full filesystem access of the operating-system user. Use real permissions, containers, or another isolation method when access must be technically enforced.
Profiles also do not isolate project instructions or knowledge in a shared working directory. Two profiles pointed at the same project read the same AGENTS.md, the same source files, and the same local knowledge unless OS or container permissions separate them.
Use a temporary subagent when the work is
- Narrow and clearly defined
- Independent enough to run in parallel
- Better handled outside the main conversation's context
- Expected to return a result rather than maintain a long-term identity
Brief the worker, do not clone the boss
Do not paste the main agent's entire memory or conversation into every subagent brief. Give it the smallest complete packet needed for the task — goal, relevant facts, constraints, deliverable format, and how the result will be verified.
Download the profile role template → · Download the subagent brief →
—— Nine Rules
Token and Context Efficiency
Start a new session when the job changes
Do not use one endless conversation for unrelated work. Resume an old session only when its history is genuinely useful.
Keep always-loaded files short
SOUL.md, memory, and the root project file affect every turn. Remove background that does not change behavior. Point to deeper files instead of copying them.
Retrieve narrowly
Read the relevant file, section, or line range instead of attaching a folder. In the CLI, context references can target a line range. On Telegram and other messaging surfaces, have the agent use its file and search tools — inline @file: expansion is primarily a CLI feature.
Avoid duplicate instructions
Do not repeat one rule in SOUL.md, memory, AGENTS.md, several knowledge files, and multiple skills. Keep one canonical source and short pointers. Duplicates cost tokens and eventually conflict.
Use the right tool for repeated work
For a mechanical batch, one script beats dozens of tool calls. For independent research streams, subagents protect the main conversation from large intermediate output. Delegation is not automatically cheaper in total — use it when the separation is useful.
Keep tools focused
Enable only the toolsets an agent or scheduled job needs. Built-in tool schemas load directly and consume prompt space. When Tool Search is enabled and activates, eligible MCP and non-core plugin schemas may instead be deferred and loaded on demand. Tool changes generally need a fresh session.
Avoid model changes inside a long session
A mid-session model change resets the provider-side prompt cache. Switching providers, automatic fallback, or rotating accounts does the same — the next request rereads the conversation at full input cost. Switch early, or in a fresh focused session.
Compression is a safety net, not a filing system
Hermes can auto-compress long conversations, and /compress exists when a session gets too large. It summarizes old context; it does not replace clean sessions or good retrieval. Durable facts should reach memory, knowledge, or skills before the detail is compressed away.
Measure before optimizing
Use /usage for the current session and /insights for broader patterns. Then judge on real tasks, not on token counts alone.
What "better" actually looks like
- Did the agent need fewer corrections?
- Did it complete the task in fewer turns?
- Did it load less irrelevant context?
- Did it verify the result correctly?
- Did total usage improve without reducing quality?
Common Mistakes
- Writing a 30-page SOUL.md
- Putting every business document into persistent memory
- Copying the same instructions into every agent
- Creating a permanent subagent for every type of task
- Assuming a profile is a security sandbox
- Storing secrets inside Markdown files
- Letting old project plans influence current work without a status or review date
- Asking the agent to "optimize itself" with permission to delete or rewrite everything
- Changing several context layers at once, then not knowing what improved the result
- Treating fewer tokens as the only goal — an agent that is cheap but unreliable is not efficient
—— Audit First
Safe Self-Optimization
You can hand this system to the agent itself — but only in two phases, and only with the audit phase locked to read-only. Handing an agent write access and the instruction "clean yourself up" is how people lose configurations they cannot reconstruct.
Phase 1 — Audit only, no changesThe audit prompt scopes the agent to the active profile and current workspace, tells it to inspect filenames and metadata before contents, and explicitly walls off other profiles, raw transcripts, .env, auth files, credential stores, browser data, private keys, and customer records. It returns a redacted inventory, the duplicated and stale instructions, what is filed in the wrong layer, and a proposed change plan ordered by impact and risk.
What Phase 1 must return
Phase 2 opens by making the agent restate the exact approved files and edits before touching anything. If the scope is ambiguous, it stops and asks. It picks a reversible method per file, reports the rollback location before editing, uses the smallest targeted edits, reads back every changed file, and confirms no secret values were introduced.
Testing must not have side effects
Phase 2 tests are read-only or local sandbox only. No sending messages, publishing, deploying, spending money, modifying live data, contacting customers, restarting services, or triggering automations. If a meaningful test needs side effects, the agent proposes it and waits for separate approval.
The 30-Minute Start
If your setup is new, do this and nothing else first:
- Write a short SOUL.md using the template
- Add one accurate project instruction file — AGENTS.md for broad compatibility, .hermes.md for a Hermes-only project
- Add the standard test and verification commands
- Create a small
knowledge/README.mdrouting map - Move detailed business or project information out of always-loaded instructions and into knowledge files
- Keep memory limited to durable facts and preferences
- Turn one repeated multi-step workflow into a skill
- Start a fresh session and test one real task
- Review
/usageand note whether the agent needed fewer corrections
Maintenance Rhythm
Once a month, or whenever the agent repeatedly makes the same mistake:
—— Get Started
Templates & Downloads
Eight standalone Markdown files. Drop them straight into your Hermes home, your repo, or any documentation tool.
SOUL.md
The identity file. Role, operating style, context discipline, verification, safety, communication — the six sections that belong in every session.
Download template agents-md-template.mdRoot AGENTS.md
The project file. Architecture, paths, standard commands, conventions, boundaries, definition of done, and pointers to deeper docs.
Download template nested-context-template.mdNested Context File
The short per-directory file for large projects. Discovered on first relevant tool access instead of loaded at startup.
Download template knowledge-routing-template.mdKnowledge Routing Map
The README that turns a folder of documents into a retrieval system. Includes the status header and suggested folder shape.
Download template skill-template.mdSkill
Frontmatter, triggers, prerequisites, numbered procedure, pitfalls, and a verification gate. The description field is what makes it fire correctly.
Download template profile-role-template.mdPersistent Profile Role
For an agent that needs its own identity and boundaries. Responsibilities, out-of-scope, required context, escalation, and output verification.
Download template subagent-brief-template.mdTemporary Subagent Brief
The smallest complete packet for a one-off worker: goal, context, constraints, deliverable, and how the main agent verifies the result.
Download template self-optimization-prompts.mdSelf-Optimization Prompts
Both phases, ready to paste. Phase 1 audits read-only with explicit access walls. Phase 2 implements only the list you approved.
Download templateWhere these go
soul-template.md becomes SOUL.md in your profile's Hermes home. The AGENTS.md and nested templates go in the repo. The knowledge routing map becomes knowledge/README.md. The skill template goes wherever your skills live. The prompts are pasted into a chat.
Official Hermes Documentation
The behavior described here changes as Hermes changes. When something in this playbook disagrees with the docs, the docs win.
- Context files — discovery order and nested file behavior
- Persistent memory — limits, approval gates, snapshot timing
- Skills system — progressive disclosure and catalog cost
- Profiles — separate homes, state, and their limits
- Tool Search — deferred schema loading
- Configuration — where the knobs live
- Tips and best practices
- Agent Skills specification — the portable skill format
The final rule
The most efficient agent is not the one with the fewest instructions. It is the one that receives the smallest amount of correct context needed to complete the current task safely — and then verifies the result.
Now Do This For Your Business
This playbook builds the agent on your machine. The next one builds the agents that run your company — named agents, dedicated channels, four approval gates, and a dashboard that tells you what everything costs.
Read the Business Agent PlaybookWant more of this? Join the community — skool.com/aiceolab