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

Hermes Agent treats skills as the default way to teach repeatable workflows. Official documentation describes them as on-demand knowledge documents aligned with the open cluster, where assistants are treated as systems built from inference, retrieval, memory, and tooling rather than as a single chat surface. Install paths, provider wiring, gateway behavior, and the layout of ~/.hermes are all spelled out in the . In real deployments, skills inherit isolation from profiles (separate config, secrets, memories, and skill trees). .

Anatomy of a skill directory

On disk, every skill is a folder under ~/.hermes/skills/, often nested under a category such as devops/ or research/. Hermes expects SKILL.md at the leaf; everything else is optional structure you add when the instructions would otherwise sprawl. The usual pattern is references/ for long tables or vendor docs, templates/ for output skeletons, scripts/ for deterministic helpers, and assets/ for static files the agent should not re-fetch.

That layout mirrors how progressive disclosure works in practice: the agent can stay at the main file until it truly needs a deep appendix. Keeping “happy path” prose in SKILL.md and pushing rarely used detail into references/ is one of the cheapest ways to protect token budgets.

Hermes can also merge in external skill directories via skills.external_dirs in config.yaml. Those paths are scanned for discovery, but the agent still writes through skill_manage into the primary ~/.hermes/skills/ tree. Local names shadow external ones, so if you “fix” a shared skill in your home directory, teammates pulling the same external repo will not see your edit until they remove or rename the local copy—a common source of “it works on my machine” confusion.

SKILL.md frontmatter that survives review

The body of SKILL.md is Markdown; the opening block must be valid YAML between --- delimiters. Real skills accumulate long fenced examples, so the small habits from is a useful contrast read—frontmatter discipline and “load only when relevant” carry over, even when the installer and slash-command wiring differ.

Org-wide rollouts usually pair a private tap or shared Git repo with external_dirs for read-only sharing, while keeping the agent-writable copy under each profile when skill_manage is allowed to mutate skills in place.

Troubleshooting and optimization

When a skill misbehaves, walk this checklist before rewriting prose.

• 
  Visibility — Confirm platforms, requires_*, and fallback_for_* predicates. A skill that “works on my Mac” but not in Linux CI is often a platform guard.


• 
  Name collisions — Duplicate names across local and external directories follow local precedence. Rename or namespace aggressively.


• 
  Discovery layout — A misplaced SKILL.md or wrong category folder can drop the skill from indexing entirely.


• 
  Token load — If sessions feel slow, shorten level-zero descriptions, move depth into references/, and deduplicate giant tables.


• 
  Agent edits — Hermes can create, patch, or delete skills via skill_manage. Treat valuable skills like code: review diffs, export snapshots, and reset bundled skills deliberately when upgrades drift.

A tight regression loop beats rereading the whole file: hermes chat --toolsets skills -q "Use the <skill> workflow to <concrete task>" should show the agent pulling the right disclosure level before it freestyles. If it never invokes skill_view, your When to use text or description probably does not match how people phrase requests.

Official references stay authoritative for behavior changes—the for author-facing rules, the for the shared file format Hermes aligns with.