Hermes Agent Skills: How Procedural Memory Works

Hermes Agent skills are the agent’s procedural memory: markdown files that record how to do a task. Hermes writes them itself after working out a multi-step job, patches them when it hits a new pitfall, and loads one only when a task needs it. Each skill is a SKILL.md folder under ~/.hermes/skills/, in the open Agent Skills format.

Hermes Agent is the MIT-licensed agent from Nous Research, with about 256,000 GitHub stars on 21 October 2026. This page covers how its skills are made, stored, loaded, shared and cleaned up. Facts come from the official Skills System docs, the Curator docs and the v0.22 release notes, checked 21 October 2026. For the fact files and session search, see Hermes Agent memory.

What are Hermes Agent skills?

A Hermes skill is a folder with a SKILL.md file: YAML front matter (name, description, version, tags) and a body with when to use it, the steps, the pitfalls and how to check the result. The agent sees every skill’s name and description, and reads the full file only when a task matches.

The docs put it plainly: when the agent “figures out a non-trivial workflow, it saves the approach as a skill for future reuse.” That’s what separates skills from memory. Memory says what is true (“the user lives in PST”). A skill says how to do something (“how to deploy to Kubernetes”). The Hermes guide’s rule of thumb: “If you’d put it in a reference document, it’s a skill. If you’d put it on a sticky note, it’s memory.”

Skills are not unique to Hermes. The format follows the Agent Skills specification, which Claude Code, Codex and others also read, so a skill folder can move between tools. What Hermes adds is the loop around it: the agent writes and edits its own skills, and a background job prunes the ones nobody uses. The wider idea is covered in procedural memory in AI agents.

How Hermes creates and improves skills

Skills get written in four ways:

1. During a task. The system prompt asks the agent to save a non-trivial workflow with the skill_manage tool. The docs list three triggers: it worked out a multi-step workflow worth repeating, it hit dead ends and found the working path, or you corrected its approach.
2. On a nudge. The default skills.creation_nudge_interval is 15, so Hermes reminds the model to consider saving a skill every 15 tool-calling iterations (per cli-config.yaml.example in the repo, October 2026). Set it to 0 to turn the nudge off.
3. In the background review. After a turn, a forked copy of the agent can save memory or create and patch skills. Since v0.22.0 (14 October 2026), the release notes say “background review can improve any skill,” and corrections go into the skill for that task.
4. On request with /learn. Point it at a folder, a URL, a pasted procedure or “how I just deployed the staging server,” and the agent writes a skill from it. A large source such as a book becomes a short SKILL.md plus one file per topic under references/.

skill_manage has six actions: create, patch (a targeted find-and-replace, the preferred way to update), patch with full content (a rewrite), delete, write_file and remove_file. The docs say a targeted patch “is more token-efficient than a full rewrite.”

Hermes also tells the agent what a good skill looks like: “lessons, not logs.” A pitfall should be a general rule plus a short reason, not the story of the incident. An advisory linter runs on each write and warns on three shapes: a body full of PR or issue numbers, more than 60 reference files, and a SKILL.md body over about 24,000 characters. It warns; it never blocks.

Where skills live and the SKILL.md format

Everything sits in ~/.hermes/skills/, which the docs call “the primary directory and source of truth.” Bundled skills are copied there on install, and hub installs and agent-made skills land there too. Skills are grouped in category folders:

 1~/.hermes/skills/
 2├── devops/
 3│   └── deploy-k8s/
 4│       ├── SKILL.md        # required
 5│       ├── references/     # extra docs, loaded on demand
 6│       ├── templates/
 7│       ├── scripts/
 8│       └── assets/
 9├── .hub/                   # lock.json, quarantine/, audit.log
10├── .usage.json             # view, use and patch counts per skill
11└── .bundled_manifest       # hashes of seeded bundled skills

A minimal SKILL.md, in the shape the docs give:

 1---
 2name: deploy-k8s
 3description: Deploy a service to our Kubernetes cluster
 4version: 1.0.0
 5platforms: [macos, linux]
 6metadata:
 7  hermes:
 8    tags: [kubernetes, deploy]
 9    category: devops
10    requires_toolsets: [terminal]
11---
12
13# Deploy to Kubernetes
14
15## When to Use
16## Procedure
17## Pitfalls
18## Verification

Hermes reads skills from more than one place. When names clash, the docs give the order as project → local (~/.hermes/skills/) → skills.create_dir → external_dirs:

• Project skills in <repo>/.hermes/skills/ or <repo>/.agents/skills/ load only after you run hermes skills trust in that repo, and each one is scanned first. A skill the scanner rates dangerous is quarantined.
• skills.create_dir sends new agent-made skills somewhere else, such as a git-tracked folder.
• skills.external_dirs adds shared folders like ~/.agents/skills. The docs warn these are “not a write-protection boundary”: if Hermes can write there, the agent can edit them.

Each profile has its own skills folder and manifest, so hermes -p coder has a separate library.

How skills get into context

Skills load by progressive disclosure, in three levels:

The Hermes docs estimate the level-0 skill list at about 3,000 tokens (Skills System docs, checked October 2026). The model reads that list and decides which skill to open; Hermes doesn’t document any embedding or ranking step for that choice, so treat selection as the model’s own judgment.

You can also load skills yourself:

• Slash commands. Every installed skill is a command: /github-pr-workflow create a PR for the auth refactor. Up to 5 leading /skill tokens stack in one message.
• Bundles. A YAML file in ~/.hermes/skill-bundles/ groups skills under one command, such as /backend-dev.
• Auto-load. skills.auto_load in config.yaml loads named skills in full at the start of every session.
• Conditional activation. Front matter fields like fallback_for_toolsets: [web] hide a skill when a tool is present, so a free search skill appears only when the paid web tool is missing.

The skill list is part of the system prompt, which stays fixed so the provider’s prompt cache keeps working. A skill added mid-chat is announced in a short note on your next message, and the system prompt itself picks it up at the next compaction.

The Skills Hub: installing and sharing skills

The Skills Hub is Hermes’s skill installer. It searches several registries and installs from them with a security scan. In the repo on 21 October 2026, Hermes shipped 58 bundled SKILL.md files under skills/ and 153 optional ones under optional-skills/ (counted from the repo tree).

To install and share a skill:

1. Search with hermes skills search kubernetes (or /skills search in chat).
2. Preview with hermes skills inspect openai/skills/k8s.
3. Install with hermes skills install openai/skills/k8s. The scan checks for data exfiltration, prompt injection, destructive commands and supply-chain signals. --force overrides warnings but never a dangerous verdict.
4. Start a new session (or /reset) so it’s in the skill list.
5. Run hermes skills check and hermes skills update later. Skills you edited locally are skipped unless you pass --force.
6. To share your own, push a GitHub repo with a skills/<name>/SKILL.md layout. Others run hermes skills tap add owner/repo, or install one skill with hermes skills install owner/repo/skills/my-workflow.

Hub operations use the GitHub API, which allows 60 unauthenticated requests per hour, so set GITHUB_TOKEN if installs hit rate limits (Skills System docs, October 2026). Plugins can also ship namespaced skills (plugin:skill), which stay out of the skill list until loaded by name; see Hermes Agent plugins.

Keeping skills healthy: curator, approval and limits

A self-writing skill library grows. The curator docs name the risk: “dozens of narrow near-duplicates that pollute the catalog and waste tokens.” Hermes has three controls.

The curator is a background pass that runs when at least 7 days have passed since the last run and the agent has been idle for 2 hours (Curator docs, October 2026). By default it only prunes: an agent-created skill unused for 14 days becomes stale, and one unused for 30 days moves to ~/.hermes/skills/.archive/. The v0.22.0 release notes (14 October 2026) say unused skills now archive at 30 days, down from 90. An LLM pass that merges overlapping skills into umbrella skills exists but is off by default (curator.consolidate: false); the docs say a full sweep “typically takes 50–100 API calls.” The curator never deletes outright, keeps a per-change ledger, and hermes curator rollback undoes a run or a single edit.

Write approval. With skills.write_approval: true, every skill create, patch or delete is staged under ~/.hermes/pending/skills/ and reviewed with /skills pending, /skills diff <id> and /skills approve <id>. It’s off by default. The docs suggest it for “small models that misjudge what they learned.” A separate content scanner, skills.guard_agent_created, is also off by default.

Pinning. hermes curator pin <skill> stops the curator and the agent from deleting a skill; patches still go through.

The limits worth knowing:

• Context cost. The skill list is about 3k tokens every session, and a loaded SKILL.md stays in context for the rest of the session. The linter flags bodies past about 24,000 characters for that reason.
• Quality drift. The agent edits skills, including ones you wrote or installed. A bad lesson from one session can land in the skill that governs every later run of that task. Turn on write approval if that matters.
• Review cost. The background review replays the conversation. Unless you set max_input_tokens, its input budget is 75% of the review model’s context window, capped at 600,000 tokens (memory docs, October 2026). You can route it to a cheaper model or disable it.
• The curator ignores most skills. It only manages skills marked agent-created, which today means skills the background review made. Skills you or the foreground agent created (including /learn) are left alone unless you run hermes curator adopt.
• Docs disagree on one number. The curator page gives 14 and 30 days in its config, and “30d unused → stale → 90d unused → archived” further down. The config defaults and the v0.22.0 notes both say 30 days to archive.

Because skills are instructions the agent follows, a poisoned skill is an attack path. Hermes’s install scan and project-trust step exist for that reason; the general risk is covered in AI memory injection.

Skills and the other memory layers

Hermes splits memory by job. Skills are one layer of four:

The same background review writes to both memory and skills, which the docs call the “self-improvement loop”: “memory stores small durable facts that should always be in context, while skills store longer procedures that should load only when relevant.” Whether an external memory provider ever sees skill content is not documented; assume it doesn’t.

Other systems learn procedures differently. LangMem’s prompt optimizer rewrites the system prompt itself, to “update system prompts based on conversation logs or agent trajectories” (LangMem docs). That changes every call, where a Hermes skill only loads when relevant. Claude Code, Codex and other Agent Skills clients read the same SKILL.md format, so a skill written for one can usually be dropped into another’s skills folder; see Claude Code memory.

Hindsight sits in the external-provider layer, not the skills layer. It installs with hermes plugins install hindsight and doesn’t write SKILL.md files. What it adds next to skills is learned knowledge that nobody has to write as a procedure: it merges related facts into observations (evidence-backed beliefs with quotes and a proof count), keeps mental models (standing answers it refreshes in the background, read without an LLM call), and answers reasoning questions with reflect. That fits lessons that don’t belong in one skill, such as how a user wants pull requests reviewed across every project. It’s MIT-licensed with every feature in the self-hosted server. The limit: each retain calls an LLM, and Hermes prefetches recall every turn. The Hermes plugin caps recall at 4,096 tokens by default (recall_max_tokens, per Hindsight’s Hermes docs, October 2026); lower it if prompt cost matters. More in Hindsight explained, and the provider comparison is on OpenClaw vs Hermes Agent memory.