Hermes Agent Skills: Key Components and How They Work

For the fifth time this week, you explain to your agent how to create a branch, open a pull request and check that the automated tests pass. It handles the job perfectly. It will have forgotten everything by the next session. Hermes Agent skills exist so that this procedure gets written down once.

A skill is a reusable set of instructions that teaches Hermes Agent how to carry out a specific task, from software development to DevOps, research, media or productivity work. Four components make it up: a SKILL.md file, a YAML metadata block, a dedicated folder and supporting files.

What follows covers each of those components, the line between the skills shipped with Hermes and the ones you install on demand, how a skill asks for an API key without ever writing it down, and how to pick the right skill for your task.

A skill is not just another prompt

A prompt asks for one action, once. A skill describes a procedure the agent finds again every time the same situation comes back. The difference is that the knowledge sticks around, not that the text is longer.

The SKILL.md file states what the skill is for, when to use it, which steps to follow and how to check the result. That last point is the one people skip. Without a success criterion, the agent cannot tell a finished task from a failure nobody noticed.

A skill replaces neither the model nor the built-in tools of Hermes. It tells the agent which workflow to follow, which shell commands to run, which supporting files exist and what configuration the task needs. If the agent itself is still fuzzy to you, start with the definition and inner workings of Hermes Agent.

The four components of a Hermes Agent skill

The SKILL.md file

This is the only required file. Written in Markdown, a formatting language you type as plain text, it holds the purpose of the skill, its instructions, its configuration notes and its constraints.

A good SKILL.md puts the most common case at the top and pushes rare situations down. The agent finds the usual path right away, and the awkward edge cases are still documented further along.

Take a skill built around GitHub pull requests. It walks through creating the branch, making the changes, opening the pull request, reading the automated test results, then handing the work over for review. Hermes replays that sequence on every request of the same kind. If those steps are new to you, our Git & GitHub course covers the vocabulary of branches and pull requests.

The YAML frontmatter

The frontmatter is the metadata block sitting at the very top of the file, between two lines of three dashes, written in YAML. It hands Hermes an identity card for the skill before the instructions begin.

---
name: github-pr-workflow
description: Open a pull request, follow the automated tests and prepare the review.
version: 1.0.0
author: your-name
license: MIT
platforms: [macos, linux]
required_environment_variables:
  - GITHUB_TOKEN
---

The fields name, description, version, author and license make the skill readable before anyone opens it. The description is the text Hermes reads to decide whether to load the skill, so it should describe a situation rather than sell a product.

Other fields control visibility. platforms restricts a skill to macOS, Linux or Windows. A skill can also declare the tools it depends on, or offer itself as a fallback when the main tool is missing.

The skill directory

Every skill lives in its own folder, next to its resources. Skills shipped with Hermes get copied into ~/.hermes/skills/ during installation, usually filed under a category.

~/.hermes/skills/
└── devops/
    └── docker-management/
        ├── SKILL.md
        ├── references/
        ├── templates/
        └── scripts/

That single structure is what makes skills portable. Instructions, helper scripts, reference documents and configuration requirements travel together instead of being scattered across several places.

Supporting files and scripts

Three subfolders come up again and again:

• references/ for long documentation and tables the agent pulls in on demand
• templates/ for reusable output formats
• scripts/ for helper code

Scripts earn their place when a step needs an exact result: parsing JSON, normalizing columns, extracting data. Rewriting that logic inside the prompt on every run gives you a slightly different answer every time.

Hermes exposes the folder path when the skill loads, through the ${HERMES_SKILL_DIR} variable. The SKILL.md can therefore point to ${HERMES_SKILL_DIR}/scripts/parse.py with no hardcoded path. Writing those small helpers takes a few basics, which our Python course covers.

Bundled skills and optional skills

Hermes splits skills into two families. Bundled skills come with the agent and cover the workflows most people need: GitHub, research, note taking, productivity. Optional skills wait inside optional-skills/ until you install them.

The hermes update command resyncs the bundled skills. It respects your local deletions and edits, so a skill you removed does not come back on its own. To bring back a skill you deleted by mistake, run hermes skills reset <name> --restore.

Installing, configuring and removing an optional skill

Official optional skills use an identifier built from their category, such as official/blockchain/solana or official/research/duckduckgo-search. Four steps are enough.

1. Find the full identifier of the skill you want. Bundled skills need nothing, they already sit in ~/.hermes/skills/.
2. Run the installation with hermes skills install. Hermes downloads the skill and adds it to your local library.
3. Fill in whatever configuration it asks for: environment variables, API keys, OAuth credentials or service account files, depending on what the metadata declares.
4. Remove it once it stops being useful, without touching the others.

hermes skills install official/blockchain/solana
hermes skills uninstall solana

Once installed, the skill behaves like any other. Hermes reads its SKILL.md, its metadata, its scripts and its related files, exactly as it does for a bundled skill.

API keys and credentials: what a skill may ask for

Hermes skills store no secret in their text. They declare what they need and let Hermes handle the values, through two separate mechanisms.

required_environment_variables covers secrets that fit in a string: API keys, tokens. Hermes asks the user for the value during setup, then passes it to the scripts without showing it in the clear to the model.

required_credential_files covers secrets that live in a file: OAuth tokens, client secrets, service account JSON files, certificates. When those files exist, Hermes makes them available inside sandboxed environments, locally, in Docker or on a remote machine.

A Python script inside the skill then reads the approved key from os.environ. You do not retype the same value for every execution environment.

Which skill for which task

The useful reflex is to start from the work you already repeat, then look for the matching category. Here are the pairings that come up most often.

The file format is not specific to Hermes. Claude Skills rest on the same idea of a SKILL.md loaded when the task matches, which makes what you learn here transferable from one agent to another.

Your skills only work if the agent is running

A weekly monitoring skill, a ticket triage flow or an incident alert all assume the agent is awake when the work arrives. A sleeping laptop fires no scheduled task.

That is why many people run Hermes on a virtual private server rather than on their own machine. The agent then keeps its memory, its configured skills and its messaging connections, whatever your workstation is doing.

Before going that far, test each skill locally on a small example. Check the output, tighten the instructions, and only then point it at real work. Our Hermes Agent course walks through that setup step by step.

Frequently asked questions

No. Hermes copies those skills into ~/.hermes/skills/ during installation, so they are available with no extra command. Only optional skills, stored in optional-skills/, need an explicit hermes skills install.

Run hermes skills reset <name> --restore. The hermes update command will not do it: it resyncs bundled skills while respecting your local deletions, so it never reinstalls what you removed on purpose.

No. A skill supplies reusable task context: which workflow to follow, which existing tools or shell commands to use, which supporting files to open. The model and the core tools of Hermes stay untouched.

Never inside the SKILL.md file. A key or token is declared in required_environment_variables, and Hermes asks for its value during setup without showing it in the clear to the model. OAuth tokens, certificates and service account JSON files go through required_credential_files.

One is enough. A SKILL.md that spells out the trigger, the steps and the success criterion is a valid skill. The references/, templates/ and scripts/ folders come in only when the agent should improvise nothing.