Hermes Agent Skills Explained: Format, Bundled Skills, Tips

What a Hermes Skill Actually Is

The official docs describe skills as "on-demand knowledge documents the agent can load when needed" — procedural memory, in plainer terms. A skill is a markdown file that tells the agent how to do something: when to use the procedure, the steps, the pitfalls, and how to verify the result. It is not code. The agent reads the skill and then uses its normal tools to execute what the skill describes.

Two design decisions make the system work at scale. First, Hermes follows the agentskills.io open standard, so skills are portable across compatible frameworks and shareable through a public hub rather than being locked to one runtime. Second, skills use progressive disclosure: the agent first sees only a lightweight index of names and descriptions (roughly 3k tokens for the whole catalog), pulls a skill's full content only when it decides to use it, and pulls supporting reference files only when those are needed. Ninety-four skills in the catalog does not mean ninety-four skills in the context window.

If you are coming from OpenClaw, the contrast is the first thing you notice. OpenClaw puts the agent's identity and standing instructions in one SOUL.md file; Hermes splits behavior into many small, loadable documents. Neither approach is wrong — we wrote up the full tradeoff in Hermes Agent vs OpenClaw — but it shapes everything else in this post.

The SKILL.md Format: Anatomy of a Skill

Every skill is a directory with one required file, SKILL.md, plus optional supporting folders. Skills live in ~/.hermes/skills/, grouped by category:

~/.hermes/skills/
├── category-name/
│   └── skill-name/
│       ├── SKILL.md        # required
│       ├── references/     # optional deep-dive docs
│       ├── templates/      # optional file templates
│       ├── scripts/        # optional helper scripts
│       └── assets/         # optional images, data files

The SKILL.md itself opens with YAML frontmatter. Three fields are required — name, description, and version — and the optional fields are where the format gets genuinely useful:

• platforms — restrict a skill to macos, linux, or windows, so an AppleScript skill never loads on a Linux VPS.
• metadata.hermes.tags and metadata.hermes.category — how the catalog index gets organized.
• metadata.hermes.requires_toolsets / fallback_for_toolsets — a skill can hide itself when a needed toolset is missing, or only appear as a fallback when a better native toolset is unavailable.
• required_environment_variables — declared credentials with a prompt and help text, so the agent asks for an API key properly instead of failing mid-task.
• metadata.hermes.config — non-secret settings with defaults, for skills that need light configuration.

Below the frontmatter, the body follows a conventional section order: When to Use, Procedure, Pitfalls, Verification. That last section is the one most people skip and should not — a skill without a verification step is how agents confidently report success on tasks that silently failed. For the exact field syntax and edge cases, the official skills docs are the source of truth.

How the Bundled Catalog Is Organized

A fresh Hermes install copies the bundled skills from the repository into ~/.hermes/skills/. At the time of writing the bundled catalog counts 94 skills across 17 categories, and the README advertises 40+ tools alongside them — tools are the primitives (run a command, read a file), skills are the procedures that compose them. A rough map of the categories:

Two operational details matter more than the list itself. First, Hermes tracks bundled skills with a content-hash manifest (~/.hermes/skills/.bundled_manifest) — if you edit a bundled skill, upgrades will not silently overwrite your changes, and hermes skills reset <name> --restore reverts to upstream when you want it back. Second, every skill carries a trust level: builtin ships with Hermes, official comes from the optional catalog, trusted means verified third-party repos, and community is everything else. Hub installs get scanned for prompt injection, data exfiltration, and destructive commands before activating.

The Bundled Skills Worth Your Attention First

Ninety-four skills is a browsing problem, not a starting point. These are the ones we would point a new Hermes user at, grouped by what you are trying to do.

Orchestration and multi-agent work

• kanban-orchestrator — the decomposition playbook for splitting a large goal into a task board, with explicit "anti-temptation" rules that stop the orchestrating agent from doing the work itself instead of delegating it.
• kanban-worker — the other half: how a worker agent picks up a card, the pitfalls, and the edge cases. Together these two encode the cleanest multi-agent pattern in the bundled set.
• claude-code / codex / opencode — the autonomous-ai-agents category lets Hermes drive other coding CLIs as subordinates: hand a feature to Claude Code, a PR review to Codex, and collect the results. If you already pay for those tools, this is the fastest compounding win in the catalog.

Coding

• test-driven-development — forces the write-failing-test-first loop. Agents skip this constantly without it.
• systematic-debugging — a hypothesis-driven debugging procedure instead of the default flail-and-retry. Pairs well with the previous one.
• github-pr-workflow — branch, commit, PR, review-response conventions, so agent-authored PRs look like a teammate's rather than a robot's.
• hermes-agent-skill-authoring — meta but essential: the skill that documents how skills should be written. Read it before writing your own; the agent reads it before writing its own.

Research

• arxiv — search, fetch, and summarize papers without the agent improvising fragile scraping.
• blogwatcher — monitor blogs and feeds for new posts on topics you care about; a natural fit with Hermes's cron scheduling.
• research-paper-writing — structure and conventions for long-form technical writing, useful well beyond actual papers.

Channels and daily glue

• google-workspace — Gmail, Calendar, Drive procedures in one place; the workhorse for an assistant-style agent.
• himalaya — CLI email for setups where you want the agent on a plain IMAP account rather than a Google one.
• obsidian — read and write your vault, which turns a personal Hermes instance into something that compounds with your own notes.

The full lists live in the official bundled skills catalog and the separate optional-skills catalog. Skill bundles are worth knowing about too: a YAML file in ~/.hermes/skill-bundles/ groups several skills under one slash command — the docs' example is a /backend-dev bundle loading code review, TDD, and PR workflow together.

Installing and Invoking Skills

Invocation is either explicit — /skill-name do the thing as a slash command — or implicit, where the agent consults its skill index and loads what fits the task. Asking "what skills do you have?" in plain conversation works too.

For skills beyond the bundled set, the CLI supports several sources:

# official optional catalog
hermes skills install official/category/name

# any GitHub repo with a skills/ directory
hermes skills install owner/repo/skills/skill-name

# a raw SKILL.md by URL
hermes skills install https://example.com/SKILL.md --name my-skill

# team/private skills repo as a tap
hermes skills tap add org/skills-repo

If you have not set up Hermes itself yet, our Hermes Agent setup guide covers install through first conversation. And note that skills are only one of two extension surfaces — Hermes also speaks MCP natively, which is the better fit when the capability you need is a live external service rather than a procedure. We cover when to reach for which in the Hermes Agent MCP guide.

Self-Updating Skills: Supervise, Don't Worship

The feature Hermes is famous for is that the agent manages its own skills. Through the skill_manage tool it can create a new skill, patch an existing one with a targeted old-string/new-string edit, rewrite one wholesale, or delete one. It is prompted to do this after completing complex multi-step tasks, after recovering from an error, after a user correction, and after discovering a non-trivial workflow. The reflection loop then revisits and revises skills as the agent keeps working.

This is genuinely useful and genuinely needs supervision. Self-authored skills inherit whatever the agent believed at the moment of writing — including workarounds that only succeeded by coincidence, and assumptions about your environment that stop being true next month. Drift compounds quietly: a skill patched five times by the agent can end up encoding a procedure nobody on your team would recognize or endorse.

The practical regimen is boring and effective: keep ~/.hermes/skills/ under git, skim the diffs of agent-authored changes the way you would skim a junior engineer's runbook edits, and revert what you do not endorse. The format helps here — patches are small and SKILL.md is plain markdown, so review is a two-minute job, not an archaeology project. Treat the learning loop as a draft generator with a human merge step and it is one of the best things about Hermes. Treat it as autonomous and you will eventually debug a failure caused by a skill nobody wrote.

Writing Your First Skill

The fastest path: read the bundled hermes-agent-skill-authoring skill, copy the structure of a bundled skill in the same category as yours, and keep version one small. A minimal but complete skill looks like this:

---
name: deploy-checklist
description: Pre-deploy verification steps for our Next.js app
version: 0.1.0
metadata:
  hermes:
    category: devops
    tags: [deploy, vercel]
---

## When to Use
Before any production deploy of the main web app.

## Procedure
1. Run the test suite; abort on any failure.
2. Check that env vars referenced in the diff exist in the
   deployment platform (list them explicitly).
3. Build locally before pushing.

## Pitfalls
- New env vars silently missing in production is the #1 failure.

## Verification
- Deploy preview returns 200 on / and on the changed routes.

A few rules that separate skills that work from skills that decorate the catalog:

• One job per skill. If your "When to Use" section needs the word "or" more than once, split it.
• Write the description for the index, not for humans. The agent decides whether to load your skill from the name and description alone — make them discriminating.
• Pitfalls are the payload. Procedures are usually derivable; the pitfalls section is where your hard-won knowledge lives and where most of the value is.
• Always include Verification. Give the agent a concrete way to know it succeeded, or it will declare success on vibes.
• Push big content into references/. The SKILL.md should stay lean; progressive disclosure means reference files cost nothing until they are actually needed.

The Local-Model Caveat

Skills are model-agnostic on paper — they are markdown loaded into context. In practice, skill quality is gated by the model executing them. Most skills terminate in tool calls, and tool-call fidelity is exactly where weaker local models fall over. In our own testing, gemma4:26b mangled tool arguments — truncating file paths mid-call — which means even a perfectly written skill fails at execution time in a way that looks like the skill's fault. The Qwen family has been the reliable local choice for agent harnesses in our experience.

The debugging heuristic: if a skill works on a hosted frontier model and fails locally, check the raw tool calls before touching the SKILL.md. And if you are running Hermes against Ollama, make sure the model is loaded with a real context window — skills plus the catalog index plus conversation do not fit in a default 4K context.

Skills vs SOUL.md: Two Philosophies of Agent Knowledge

OpenClaw's bet is that an agent's identity, rules, and standing knowledge belong in one human-curated SOUL.md file, with markdown memory alongside it. Everything is in one place, everything is auditable, and nothing changes unless you change it. Hermes's bet is that agent knowledge should be modular, loadable on demand, and partly self-maintained. One file you fully control versus many files the agent helps maintain — that is the actual philosophical line between the frameworks, more than any feature checklist.

If you are moving from OpenClaw to Hermes, the migration story is honest in both directions. Hermes ships a native hermes claw migrate command (with --dry-run and preset options) that imports SOUL.md, memories, and user-created skills. Our free soul-to-hermes converter handles the structural SOUL.md-to-personality/skill split and — the part we think matters most — gives you a manual-cleanup checklist for what no converter can decide for you: which standing instructions should become always-on personality versus on-demand skills. The full walkthrough is in our SOUL.md migration guide.

If you are still deciding which framework fits your project, start with the full comparison — and if the OpenClaw side wins, the CrewClaw template gallery is the fastest way to see what a finished SOUL.md-based agent looks like before you write your own.

Related Guides

Frequently Asked Questions