Hermes Agent Skills: The Practical Guide

What Hermes Agent skills are

Hermes Agent is an open-source, model-agnostic personal AI agent built by Nous Research. It runs as a CLI, a desktop app, a messaging gateway (Telegram, Discord, Slack, WhatsApp), and an IDE integration.

A skill is a folder containing a SKILL.md file plus optional supporting files (scripts, references, templates, examples, assets). SKILL.md tells the agent what a capability does, when to use it, and how — in effect, an on-demand instruction document the agent loads only when it's relevant, rather than stuffing every capability into the system prompt.

Hermes implements this using the agentskills.io open standard, which originated at Anthropic and is now used by a long list of agent products (Claude Code, Cursor, VS Code, Gemini CLI, OpenClaw, and others). That matters practically: a well-formed skill written for one compatible agent is often usable, with little or no change, in another.

Where skills live

All skills resolve from ~/.hermes/skills/, organized by category:

~/.hermes/skills/
├── category/
│   ├── skill-name/
│   │   ├── SKILL.md        # required
│   │   ├── references/
│   │   ├── templates/
│   │   ├── scripts/
│   │   ├── examples/
│   │   └── assets/
└── .hub/

You can add additional search locations — useful for a team-shared skills repo, or a project-local set of skills checked out alongside a codebase — via external_dirs in config.yaml:

skills:
  external_dirs:
    - ~/.agents/skills
    - ${SKILLS_REPO}/skills

The SKILL.md format

The required frontmatter, per the official docs:

---
name: my-skill
description: Brief description (≤60 chars)
version: 1.0.0
platforms: [macos, linux]  # optional
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]      # optional
    requires_toolsets: [terminal]     # optional
    config:
      - key: my.setting
        description: "What this controls"
        default: "value"
---

The name and description fields are the only ones required by the base agentskills.io spec; everything under metadata.hermes is Hermes-specific extension data used for conditional loading and configuration (covered below).

How skills are discovered and loaded

Hermes scans its skill directories at startup and loads every valid SKILL.md it finds — but it doesn't load full skill content up front. It uses progressive disclosure, in three levels, to keep token usage low even with a large skill library installed:

This is the general agentskills.io model (discovery → activation → execution), and it's why a Hermes install with hundreds of skills doesn't meaningfully bloat every conversation — most of that library sits at level 0 until it's actually relevant.

Installing skills: the eight hub sources

Hermes doesn't have one skill registry — it federates across eight source types, all reachable through hermes skills browse / hermes skills search / hermes skills install:

For the full command reference and copy-pasteable examples, see how to install Hermes Agent skills.

Trust tiers

Every skill Hermes can install carries a trust level, and hub installs are scanned before they land on disk:

All hub installs are scanned for data exfiltration, prompt injection, and destructive commands before install completes. This scanning and trust-tier logic is documented behavior from the official docs — we haven't independently audited the scanner's detection accuracy, and you shouldn't treat "scanned" as a substitute for reading a community-tier skill's SKILL.md and scripts yourself before installing. See evaluating skills on GitHub for what to actually check.

What kinds of skills exist

Skills aren't one thing — they differ by where they come from and what they do:

• Bundled skills — ship with Hermes by default (builtin trust), covering common tasks out of the box.
• Optional official skills — maintained in the optional-skills/ folder of the main repo but not installed by default; add them with hermes skills install official/....
• Hub/community skills — installed from any of the eight sources above, spanning everything from document generation (PowerPoint, presentation creation) to SaaS integrations (Composio's connector skill for Gmail, Sheets, Slack, CRMs) to development workflow discipline (structured brainstorming, TDD, systematic debugging).
• Knowledge-base skills — created via /learn from a large source (a book, a docs site, a whole SDK). These get a lean SKILL.md carrying the core mental model, with the bulk of the material indexed under references/ and loaded chapter-by-chapter via level-2 skill_view calls, so token cost stays proportional to what's actually asked.
• Agent-authored skills — created or edited by Hermes itself through its learning loop (next section), not installed from anywhere.

Skills vs. tools vs. plugins vs. MCP, in Hermes specifically

These four terms get conflated constantly in third-party writeups. In Hermes they're distinct:

The practical distinction: a skill rarely adds new low-level capability by itself. It packages judgment and process — when to use which tool, in what order, with what caveats — around capabilities the agent (via tools, plugins, or MCP) already has.

Conditional activation

Skills can hide or surface themselves depending on what's available in the current environment:

metadata:
  hermes:
    requires_toolsets: [terminal]   # only show when terminal is available
    fallback_for_toolsets: [web]    # only show when web toolset is unavailable
    requires_tools: [terminal]      # check for a specific tool
    fallback_for_tools: [web_search]

The documented example: a DuckDuckGo search skill stays hidden while Firecrawl's web toolset is active, and only surfaces as a fallback if that toolset isn't available. This keeps overlapping skills from competing for the same job — the agent only sees the one relevant option for the current setup.

Skill bundles: stacking multiple skills under one command

A bundle groups several skills under a single slash command, stored as YAML at ~/.hermes/skill-bundles/<slug>.yaml:

name: backend-dev
description: Backend feature work
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Always start by writing failing tests first.

Invoke it with /backend-dev refactor the auth middleware, and all three skills load together with the extra instruction applied. You can also stack skills ad hoc without a bundle file, up to five at once: /skill1 /skill2 /skill3 instruction. /bundles lists what's available.

The learning loop: skills that write themselves

This is the feature that most distinguishes Hermes from a typical skills-compatible agent, and it's the part most third-party "best skills" roundups skip entirely.

Creating skills from experience. /learn <path-or-url> turns a local source or a documentation URL into a new skill. Re-running /learn against updated material folds the new content into the existing skill instead of duplicating it.

Self-editing via skill_manage. Hermes has a dedicated tool for modifying its own skill library:

Approval gating. By default this can happen autonomously; you can require a human check first:

skills:
  write_approval: true

With that set, proposed changes land as staged writes under ~/.hermes/pending/skills/ instead of applying immediately:

/skills pending      # list staged writes
/skills diff <id>    # view the full diff
/skills approve <id> # apply it
/skills reject <id>  # drop it

Editorial note: we have not run Hermes ourselves and can't independently characterize how reliable agent-authored skills are in practice, or how often write_approval: true catches something worth catching. This section describes documented mechanics, not tested outcomes. If you're running Hermes on anything you care about, turning on write_approval before you trust it with unattended self-editing seems like the obviously conservative default — but that's our inference, not a benchmark result.

Bundled-skill update protection

On install, Hermes records a content hash for every bundled skill at ~/.hermes/skills/.bundled_manifest. On update:

• If you haven't touched a bundled skill, upstream changes apply cleanly.
• If you have modified it, your version is preserved permanently and skipped in future syncs — no silent overwrite of local edits.

You can also opt a fresh install out of bundled-skill seeding entirely:

hermes skills opt-out              # stop future seeding, keep what's installed
hermes skills opt-out --remove     # also delete unmodified bundled skills
hermes skills opt-in --sync        # re-enable and re-seed

Common setup questions

Do I need to restart Hermes after adding a skill manually? Skills are scanned at startup; a skill dropped into ~/.hermes/skills/ needs a restart (or the equivalent reload path in your interface) to be picked up as far as the documented behavior goes — we did not verify whether the CLI hot-reloads mid-session.

Can two skills fight over the same task? This is what requires_toolsets / fallback_for_toolsets exist to prevent — see Conditional activation above. Beyond that, the docs don't specify explicit conflict-resolution rules between two unrelated skills with overlapping descriptions, so overly broad description fields are worth avoiding when writing your own.

Where should I start looking for skills? See the best Hermes Agent skills for a criteria-based shortlist, and Hermes Agent skills on GitHub for how to evaluate a repository yourself.

Limitations and caveats

• Skill "popularity" has no public telemetry attached to it — the only observable signals for a community skill are GitHub stars, forks, and commit recency. Any ranking based on more than that is guessing.
• Security scanning on hub installs is Hermes's own automated check, not a manual audit. Treat community-tier skills as unaudited by default.
• The exact override semantics of --force on scan findings, and the full behavior of write_approval, are documented in one place (the official docs) and we have not cross-verified them against a second independent source or our own testing.
• This page describes the system as documented at the official docs site and corroborated against source files in the NousResearch/hermes-agent GitHub repository as of August 2026. Hermes is under active development; check the official skills docs if you're reading this much later.

Sources

• Hermes Agent — Skills System (official docs)
• NousResearch/hermes-agent (GitHub)
• agentskills.io — the open standard Hermes implements