Skills System

Skills are on-demand knowledge documents the agent can load when needed. They follow a progressive disclosure pattern to minimize token usage and are compatible with the agentskills.io open standard.

All skills live in ~/.hermes/skills/ — the primary directory and source of truth. On fresh install, bundled skills are copied from the repo. Hub-installed and agent-created skills also go here. The agent can modify or delete any skill.

You can also point Hermes at external skill directories — additional folders scanned alongside the local one.

Using Skills

Every installed skill is automatically available as a slash command:

# In the CLI or any messaging platform:
/gif-search funny cats

/axolotl help me fine-tune Llama 3 on my dataset

/github-pr-workflow create a PR for the auth refactor

/plan design a rollout for migrating our auth provider

# Just the skill name loads it and lets the agent ask what you need:
/excalidraw

The bundled plan skill is a good example. Running /plan [request] loads the skill’s instructions, telling Hermes to inspect context if needed, write a markdown implementation plan instead of executing the task, and save the result under .hermes/plans/ relative to the active workspace/backend working directory.

You can also interact with skills through natural conversation:

hermes chat --toolsets skills -q "What skills do you have?"

hermes chat --toolsets skills -q "Show me the axolotl skill"

Progressive Disclosure

Skills use a token-efficient loading pattern:

Level	Function	Content	Size
Level 0	`skills_list()`	`[{name, description, category}, ...]`	~3k tokens
Level 1	`skill_view(name)`	Full content + metadata	varies
Level 2	`skill_view(name, path)`	Specific reference file	varies

The agent only loads the full skill content when it actually needs it.

SKILL.md Format

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]  # Optional — restrict to specific OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]    # Optional — conditional activation
    requires_toolsets: [terminal]   # Optional — conditional activation
    config:                         # Optional — config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use

Trigger conditions for this skill.

## Procedure

1. Step one
2. Step two

## Pitfalls

- Known failure modes and fixes

## Verification

How to confirm it worked.

Platform-Specific Skills

Skills can restrict themselves to specific operating systems using the platforms field:

Value	Matches
`macos`	macOS (Darwin)
`linux`	Linux
`windows`	Windows

platforms: [macos]           # macOS only (e.g., iMessage, Apple Reminders, FindMy)
platforms: [macos, linux]    # macOS and Linux

When set, the skill is automatically hidden from the system prompt, skills_list(), and slash commands on incompatible platforms. If omitted, the skill loads on all platforms.

Skill Directory Structure

~/.hermes/skills/                    # Single source of truth
├── mlops/                           # Category directory
│   ├── axolotl/
│   │   ├── SKILL.md                 # Main instructions (required)
│   │   ├── references/              # Additional docs
│   │   ├── templates/               # Output formats
│   │   ├── scripts/                 # Helper scripts callable from the skill
│   │   └── assets/                  # Supplementary files
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/                  # Agent-created skill
│       ├── SKILL.md
│       └── references/
├── .hub/                            # Skills Hub state
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest                # Tracks seeded bundled skills

Agent-Managed Skills

The agent can create, update, and delete its own skills via the skill_manage tool. This is the agent’s procedural memory — when it figures out a non-trivial workflow, it saves the approach as a skill for future reuse.

When the Agent Creates Skills

After completing a complex task (5+ tool calls) successfully
When it hit errors or dead ends and found the working path

Skill Bundles

Skill bundles are tiny YAML files that group several skills under a single slash command. When you run /<bundle-name>, every skill listed in the bundle loads at once.

Quick example

# Create a bundle for backend feature work
hermes bundles create backend-dev \
  --skill github-code-review \
  --skill test-driven-development \
  --skill github-pr-workflow \
  -d "Backend feature work — review, test, PR workflow"

Then in the CLI or any gateway platform:

/backend-dev refactor the auth middleware

The agent receives all three skills loaded into one user message, with any text after the slash command attached as a user instruction.

Managing bundles

# List all installed bundles
hermes bundles list

# Inspect one bundle
hermes bundles show backend-dev

# Create a bundle interactively
hermes bundles create research

# Delete a bundle
hermes bundles delete backend-dev

# Re-scan ~/.hermes/skill-bundles/ and report changes
hermes bundles reload

External Skill Directories

If you maintain skills outside of Hermes, you can tell Hermes to scan those directories too:

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

Local precedence: If the same skill name exists in both the local dir and an external dir, the local version wins.
Full integration: External skills appear in the system prompt index, skills_list, skill_view, and as /skill-name slash commands.

Conditional Activation (Fallback Skills)

Skills can automatically show or hide themselves based on which tools are available:

metadata:
  hermes:
    fallback_for_toolsets: [web]      # Show ONLY when these toolsets are unavailable
    requires_toolsets: [terminal]     # Show ONLY when these toolsets are available

Example: The built-in duckduckgo-search skill uses fallback_for_toolsets: [web]. When you have FIRECRAWL_API_KEY set, the web toolset is available and the agent uses web_search — the DuckDuckGo skill stays hidden. If the API key is missing, the web toolset is unavailable and the DuckDuckGo skill automatically appears as a fallback.