The Hermes Skill Loop: When To Trust A Skill It Wrote

A stateless agent solves the same problem from scratch every time. Hermes does not. When it works out a multi-step job worth repeating, it writes the procedure down as a skill, and next time it loads that instead of reasoning it all out again. The skill folder is the thing that makes a month-old instance sharper than a fresh one. It is also the thing that quietly rots if you never look at it.

01. What a skill actually is

a markdown how-to, not code

A skill is a SKILL.md file: frontmatter plus a short procedure written in plain language. No Python, no plugin API. The docs are blunt about what belongs in one: "lessons, not logs." A skill is a generalisable rule with the mechanism attached, not an incident write-up with PR numbers in it.

Skills live in ~/.hermes/skills/, the source of truth, sorted into category folders like devops/deploy-k8s/SKILL.md. You can point Hermes at more directories through config.yaml:

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills

Inside a git repo, it also picks up project-local skills from .hermes/skills/ or .agents/skills/, so a repo can carry its own.

02. When Hermes writes one

roughly, a repeatable job of five-plus steps

The system prompt nudges the agent to create a skill when it "worked out a multi-step workflow worth repeating." In practice: a task that took five or more steps and that you will hit again. It uses one tool, skill_manage, with a small set of actions.

You can also just ask it: "make a skill out of what we just did." Or invoke one by hand with a slash command, and stack several: /github-pr-workflow /test-driven-development fix issue #123 loads both before it starts.

03. Inside a SKILL.md

frontmatter, then four sections

---
name: deploy-k8s
description: Ship a service to the staging cluster
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [devops, kubernetes]
    category: devops
    requires_toolsets: [terminal]
---

## When to Use
## Procedure
## Pitfalls
## Verification

The four body headings are the contract. "When to Use" is what stops the agent loading the wrong skill. "Verification" is what tells it the skill actually worked this time. A skill missing those two is a skill that will misfire.

04. How it loads them back

progressive disclosure, to save tokens

Hermes does not dump every skill into context. It reads them in layers:

• Level 0 skills_list() returns just names, descriptions and categories.
• Level 1 skill_view(name) pulls the full skill only when a task looks like a match.
• Level 2 skill_view(name, path) opens a specific reference file inside it.

This is why a big skill folder does not bloat every message. It also means the description line in the frontmatter is doing real work: that one sentence is how the agent decides whether to look closer.

05. The Curator problem

the agent almost always thinks it did well

The in-agent review loop, the Curator, has a known bias: after a session it tends to conclude it performed well, even when it did not. The same loop that auto-writes skills can also overwrite a manual fix with a worse version. Left alone, the folder fills with confident, mediocre skills the agent then trusts.

The fix is a write gate. In config.yaml:

skills:
  write_approval: true    # default is false

With it on, every skill write is staged under ~/.hermes/pending/skills/ instead of committed, and you clear the queue by hand:

/skills pending          # what is waiting
/skills diff <id>        # the full diff
/skills approve <id>     # apply it, or 'all'
/skills reject <id>      # drop it, or 'all'
/skills approval on|off  # toggle and persist

06. GEPA: fixing skills offline

a separate, optional pass

GEPA, short for Genetic-Pareto Prompt Evolution, is not part of the running agent. It lives in the companion repo NousResearch/hermes-agent-self-evolution and runs as an offline pipeline. It reads execution traces to work out why runs failed, then uses an evolutionary search to propose targeted improvements to prompts and skills.

It is an advanced tool and most people never touch it. The reason to know it exists: the in-agent loop is optimistic by design, so a real "did this actually get better" check has to happen outside the agent. GEPA is that check. Teams running Hermes in production tend to schedule it, then run a second job that scores the output so the optimisation loop cannot game itself.

07. Installing skills others wrote

registries, and the agentskills.io standard

Skills follow the agentskills.io format, so they move between agents. Hermes can install from several places:

hermes skills install official/security/1password
hermes skills install openai/skills/k8s
hermes skills install https://example.com/SKILL.md --name my-skill

Sources include a built-in official tap, Vercel's public directory, direct GitHub repos (OpenAI, Anthropic, HuggingFace and NVIDIA all publish some), any site serving /.well-known/skills/index.json, and plain HTTPS URLs. Every install is security-scanned; --force overrides non-dangerous findings only.

Track them over time with hermes skills check for upstream changes and hermes skills update to reinstall the modified ones. If you edit an installed skill it is marked user-modified and future syncs leave it alone.

08. The weekly five minutes

this is the whole maintenance job

Open ~/.hermes/skills/ once a week. Read the new files. Delete the ones that caught the wrong lesson, fix the one that is nearly right, leave the rest. It takes about five minutes and it is usually two deletes and one tweak.

Before you rely on any new skill for something that matters, run it three to five times. A skill that works once might have worked by accident.

The folder is an asset only if the skills in it are the right lessons. That part is yours.

Do that for two months and the folder becomes a tidy set of procedures the agent runs without re-explaining anything. Skip it and month two is worse than week one. The integrations guide is next.