Hermes Agent Skill Authoring — SKILL.md Structure and Best Practices

Source: Rost Glukhov, Hermes Agent Skill Authoring — SKILL.md Structure and Best Practices (glukhov.org, 2026-05-04): https://www.glukhov.org/ai-systems/hermes/authoring-hermes-skill/

This is a summary in my own words, not the article itself; read the original for the full text and a complete worked example.

What a skill is

A Hermes skill is a folder of Markdown instructions, in the open agentskills.io format, that the agent loads only when a task needs it. Writing one well is mostly packaging: when it should load, which steps define “done”, and how to spot failure. Setup, the ~/.hermes layout and the CLI are covered in the Hermes documentation; skills inherit isolation from profiles, which are the unit of ownership.

Skill or tool? Use a skill for prose plus commands Hermes already runs (git, curl, a CLI, web_extract); use a tool for auth flows, binary data, streaming, or code that must run identically every time.
- Skills ship without code changes. Start there and promote only the fragile core to a tool.
Skill versus memory: a skill is how to do something and loads on demand; MEMORY.md and USER.md are a small set of settled facts that stay in the prompt.

Layout and frontmatter

Skills live in per-skill folders inside ~/.hermes/skills/<category>/. Each needs SKILL.md; optional subfolders are references/ (long detail), templates/, scripts/ and assets/. Folders listed in skills.external_dirs are discovered too, but a local skill with the same name hides the shared one.

Field	Purpose
`name` (required)	Slash-command and index key; lowercase, hyphens
`description` (required)	All most sessions ever read; write it as a routing rule, not an intro
`platforms`	Hosts the skill appears on; elsewhere it vanishes with no error
`metadata.hermes.requires_` / `fallback_for_`	Show only when tools exist, or only when a preferred one is missing
`required_environment_variables`	Secrets, kept in `.env` and passed to sandboxes but not the transcript
`required_credential_files`	Token or key files mounted into Docker or Modal
`metadata.hermes.config`	Non-secret settings, resolved under `skills.config` in `config.yaml`

version, author, license, tags and related_skills are optional metadata for packaging and cross-linking.

Writing for progressive disclosure

Hermes reads a skill in three steps: the index of names and descriptions, the full SKILL.md on a match, then single reference sections via skill_view. Assume the model reads nothing past the description until it commits.

Body outline: When to use (triggers in users’ words), Quick reference, Procedure (ordered steps), Pitfalls, Verification (what success looks like).
Keep the common path in SKILL.md; move history and big tables to references/.
Path variables ${HERMES_SKILL_DIR} and ${HERMES_SESSION_ID} are filled in on activation.
Inline shell snippets can inject live context, but run on the host and are off unless skills.inline_shell is enabled — a trust decision, not a convenience.
Dependencies: prefer stdlib Python, curl and built-in tools; put fiddly parsing in a scripts/ helper. If a package is unavoidable, cover its install, failure symptom, and a loud check in the matching sections.
Secrets: tell users a key is required and where to set it; messaging front ends (Telegram and the like) will not take them, so point users at hermes setup or .env.

Publishing and troubleshooting

Skills install from the Skills Hub, GitHub, skills.sh, .well-known indexes or raw URLs. Installs are scanned for exfiltration, injection and destructive commands, with trust tiers from builtin to community; some findings can be overridden with --force. Teams typically share a read-only Git repo through external_dirs.

Before rewriting a misbehaving skill, check:

Visibility — platforms and requires_*/fallback_for_* (a skill missing only in Linux CI is usually platforms).
Name collisions — local wins; namespace names.
Placement — a misplaced SKILL.md is never indexed.
Token cost — shorten descriptions, move depth out.
Agent edits — skill_manage can change skills; review diffs and keep snapshots.

Test with hermes chat --toolsets skills -q "Use the <skill> workflow to <task>". If the agent never calls skill_view, the description is not written in the words users actually type. The Hermes docs (Skills System, Creating Skills, Bundled Skills Catalog) stay authoritative when behavior changes.