Hermes Agent skills: write, install, supervise

A skill is a document loaded on demand

An agent that knows everything is expensive on every turn, because everything it knows sits in its context permanently. Skills answer that by keeping the knowledge on disk and loading it only when it is useful. The documentation calls this progressive disclosure, and it comes in three levels.

Level 0 is the only one the agent pays on every conversation. That is what lets you keep thirty skills installed without the bill moving, as long as none is opened. The practical consequence matters more than the mechanism: the description you write in the frontmatter is the only thing the agent sees before deciding. A vague description gives you a skill that never triggers.

Every skill lives under ~/.hermes/skills/, described in the documentation as the primary directory and source of truth. The format follows the open agentskills.io standard, so a skill written for Hermes Agent is not locked to Hermes Agent.

The SKILL.md format and what the frontmatter decides

A skill is a folder containing a mandatory SKILL.md file, plus optional subfolders: references/ for long documentation, templates/ for output formats, scripts/ for helpers, examples/ and assets/. The folder name becomes the skill's identifier.

The file opens with YAML frontmatter. Only two fields are mandatory, the rest decides when the skill shows up.

The body follows a four-part shape in the official examples: when to use, procedure, pitfalls, verification. Verification is the section most often skipped, and it is the only one that lets the agent know whether it succeeded.

Four conditional fields decide visibility based on available tooling. They avoid offering a procedure the agent cannot run.

The fallback_for_toolsets case is the most useful and the least obvious: it is how you write the fallback procedure. If the web toolset is there, the skill stays invisible. If it is missing, it appears and explains how to do it another way.

A skill can finally declare the environment variables it needs, with a prompt label and a help link. Once set, the documentation states they are passed through automatically to the execute_code and terminal sandboxes. That is convenient, and it is also the moment to look at what the skill is asking for, since the secret will follow.

Installing from the hub: eight sources, four trust levels

Installing goes through hermes skills install, and the source decides almost everything. Eight are documented.

The default GitHub taps are openai/skills, anthropics/skills, huggingface/skills and NVIDIA/skills. Everything arriving through the hub goes through a security scanner looking for data exfiltration, prompt injection, destructive commands and supply-chain signals. The scan result is then weighed against the source's trust level.

The thing to remember about --force: it lifts caution-level blocks, never a dangerous verdict. When the scanner genuinely rules, the flag does nothing, and that is the behaviour you want.

Three commands cover daily use. hermes skills check reports what moved upstream, hermes skills update reinstalls what changed, and hermes skills audit re-runs the scanner over what is already installed. The last one is the forgotten one: a skill that was safe on install day does not necessarily stay safe after its origin repository updates.

Stop writing SKILL.md by hand

The /learn command takes a source and turns it into a skill, without you writing the file. The documentation presents it as the fast way to turn something you already know, or a pile of reference material, into a reusable skill. Four call shapes are documented.

• a code folder, with an angle: /learn the REST client in ~/projects/acme-sdk, focus on auth + pagination
• a documentation URL: /learn https://docs.example.com/api/quickstart
• what the agent just did: /learn how I just deployed the staging server
• a dictated procedure, in plain language

The implementation detail that matters: /learn adds no extra tool to the model. It builds a standards-guided prompt and hands it to the agent as a normal turn, which saves the result with the skill_manage tool. That is why the command behaves identically in the CLI, the messaging gateway, the TUI and the dashboard.

Bundles cover the other need, loading several skills at once. A YAML file under ~/.hermes/skill-bundles/ lists the skills and can add a shared instruction, prepended to the loaded content. You manage them with hermes bundles create, list, show, delete and reload.

Two behaviours to know before leaning on them. A bundle takes precedence over an individual skill when slugs collide, which can silently mask a skill you thought you were calling. And a missing skill inside a bundle is skipped rather than fatal, so a bundle referencing an uninstalled skill keeps working quietly, with a piece missing.

On the calling side, up to five skills can be invoked in one message. Parsing stops at the first token that is not an installed skill, which keeps a file path starting with a slash from being swallowed along the way.

When the agent writes its own skills

Hermes Agent can create, modify and delete skills on its own, through the skill_manage tool. The documentation lists four triggers: after a complex task of at least five tool calls, on discovering a non-trivial workflow, after hitting errors and finding the path that works, and when you correct it.

The documentation recommends patch over edit for a cost reason: only the changed text appears in the tool call. On a skill of several thousand words corrected often, the difference shows on the bill.

The default behaviour is to write freely. That is the setting to change first if the agent runs on a shared machine or in production. The approval gate turns on with skills.write_approval set to true, and every write then lands under ~/.hermes/pending/skills/ waiting for your call.

• /skills pending lists what is staged
• /skills diff <id> shows the full diff
• /skills approve <id> applies it, all for everything
• /skills reject <id> drops it, all for everything
• /skills approval on toggles the gate

One naming trap is worth flagging: the skills.guard_agent_created setting looks like an approval gate and is not one. It is a content scanner looking for dangerous patterns, and the documentation states the two settings are independent. Turning one on gives you nothing of the other.

The five things that break

None of these is a project defect. They are documented behaviours that surprise people who meet them in production rather than on the page.

• The GitHub limit of 60 requests per hour. Hub operations go through the GitHub API, and without a token you are capped at 60 requests hourly. A GITHUB_TOKEN in the .env file raises it to 5,000. It is the first failure you hit installing a batch of skills at once.
• External directories protect nothing. You can add folders through skills.external_dirs, with tilde and variable expansion. The documentation says explicitly this is not a write-protection boundary: the agent modifies existing skills in place, wherever they sit.
• Local precedence is silent. If the same name exists locally and in an external directory, the local version wins. A shared team repository can therefore be neutralised on one machine without anyone seeing an error.
• Non-existent paths are skipped quietly. A typo in external_dirs produces no warning, just skills that never appear.
• Profile isolation applies to skills too. Each profile has its own .bundled_manifest under its own HERMES_HOME, so a reset run on one profile leaves the others alone. Handy once you know, baffling while you wonder why the command did nothing.

On removal, a reassuring nuance: hermes skills opt-out only stops future seeding and deletes nothing already on disk. The --remove flag is what erases, and only bundled skills that were left unmodified.

The rule we apply at our clients fits in one sentence: a skill installed from a community source gets read before it is enabled, the way you would read a dependency added to the project. The scanner catches a lot, it does not catch a plausible procedure that sends your data to the wrong place.