hermes-agent/website/docs/user-guide/features/skills.md

sidebar_position, title, description

sidebar_position	title	description
2	Skills System	On-demand knowledge documents — progressive disclosure, agent-managed skills, and the Skills Hub

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/ — a single directory that serves as the 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.

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

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

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 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 (see below)
    requires_toolsets: [terminal]   # Optional — conditional activation (see below)
---

# 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.

Conditional Activation (Fallback Skills)

Skills can automatically show or hide themselves based on which tools are available in the current session. This is most useful for fallback skills — free or local alternatives that should only appear when a premium tool is unavailable.

metadata:
  hermes:
    fallback_for_toolsets: [web]      # Show ONLY when these toolsets are unavailable
    requires_toolsets: [terminal]     # Show ONLY when these toolsets are available
    fallback_for_tools: [web_search]  # Show ONLY when these specific tools are unavailable
    requires_tools: [terminal]        # Show ONLY when these specific tools are available

Field	Behavior
fallback_for_toolsets	Skill is hidden when the listed toolsets are available. Shown when they're missing.
fallback_for_tools	Same, but checks individual tools instead of toolsets.
requires_toolsets	Skill is hidden when the listed toolsets are unavailable. Shown when they're present.
requires_tools	Same, but checks individual tools.

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.

Skills without any conditional fields behave exactly as before — they're always shown.

Secure Setup on Load

Skills can declare required environment variables without disappearing from discovery:

required_environment_variables:
  - name: TENOR_API_KEY
    prompt: Tenor API key
    help: Get a key from https://developers.google.com/tenor
    required_for: full functionality

When a missing value is encountered, Hermes asks for it securely only when the skill is actually loaded in the local CLI. You can skip setup and keep using the skill. Messaging surfaces never ask for secrets in chat — they tell you to use hermes setup or ~/.hermes/.env locally instead.

Skill Directory Structure

~/.hermes/skills/                  # Single source of truth
├── mlops/                         # Category directory
│   ├── axolotl/
│   │   ├── SKILL.md               # Main instructions (required)
│   │   ├── references/            # Additional docs
│   │   ├── templates/             # Output formats
│   │   └── 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 (skill_manage tool)

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
• When the user corrected its approach
• When it discovered a non-trivial workflow

Actions

Action	Use for	Key params
create	New skill from scratch	name, content (full SKILL.md), optional category
patch	Targeted fixes (preferred)	name, old_string, new_string
edit	Major structural rewrites	name, content (full SKILL.md replacement)
delete	Remove a skill entirely	name
write_file	Add/update supporting files	name, file_path, file_content
remove_file	Remove a supporting file	name, file_path

:::tip The patch action is preferred for updates — it's more token-efficient than edit because only the changed text appears in the tool call. :::

Skills Hub

Browse, search, install, and manage skills from online registries and official optional skills:

hermes skills browse                     # Browse all hub skills (official first)
hermes skills browse --source official   # Browse only official optional skills
hermes skills search kubernetes          # Search all sources
hermes skills install openai/skills/k8s  # Install with security scan
hermes skills inspect openai/skills/k8s  # Preview before installing
hermes skills list --source hub          # List hub-installed skills
hermes skills audit                      # Re-scan all hub skills
hermes skills uninstall k8s              # Remove a hub skill
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills snapshot export setup.json # Export skill config
hermes skills tap add myorg/skills-repo  # Add a custom source

All hub-installed skills go through a security scanner that checks for data exfiltration, prompt injection, destructive commands, and other threats.

Trust Levels

Level	Source	Policy
builtin	Ships with Hermes	Always trusted
official	optional-skills/ in the repo	Builtin trust, no third-party warning
trusted	openai/skills, anthropics/skills	Trusted sources
community	Everything else	Any findings = blocked unless --force

Slash Commands (Inside Chat)

All the same commands work with /skills prefix:

/skills browse
/skills search kubernetes
/skills install openai/skills/skill-creator
/skills list