Hermes Agent Skills

The Skills system is Hermes Agent's core differentiating feature—it is the only agent with a built-in learning loop, capable of creating skills, improving skills through use, and maintaining knowledge across sessions.

What is a skill?

Skills are a set of instructions and tools that define agent behavior. They can:

• Automated workflow— Encapsulating common task patterns
• Cross-session learning— Saving and reusing successful solutions
• Share with the community— Publishing and installing skills created by others
• Self-Improvement— Continuously improving through use

For more information, refer to the Skills tutorial:https://www.example.com/ai-agent/skills-agent.html。

Skills vs. Memory

Rule of thumb: if you would write it into a reference document, it's a skill; if you would put it on a sticky note, it's a memory.

Skill directory structure

All skills are stored in~/.hermes/skills/Directory — this is the only data source.

On initial installation, built-in skills are copied from the repository to this directory. Skills installed via the Hub and skills automatically created by the Agent are also saved here.

~/.hermes/skills/
├── mlops/                     # 分类目录
│   ├── axolotl/
│   │   ├── SKILL.md           # 主指令文件（必须）
│   │   ├── references/        # 补充文档（按需加载）
│   │   ├── templates/         # 输出模板
│   │   ├── scripts/           # 辅助脚本
│   │   └── assets/            # 附属资源
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/            # Agent 自动创建的技能
│       ├── SKILL.md
│       └── references/
├── .hub/                      # Skills Hub 状态
│   ├── lock.json
│   ├── quarantine/            # 安全隔离区
│   └── audit.log
└── .bundled_manifest          # 记录内置技能版本

The only required files for each skill directory areSKILL.mdThe rest of the subdirectories are optional.

The agent can modify or delete any skill—whether built-in, installed from the Hub, or self-created.

Progressive disclosure: a token-efficient loading mechanism

One of the smartest designs in the skill system isProgressive disclosure—The agent does not stuff all skill content into context at once, but loads it in three layers on demand.

Level 0: skills_list()              → [{name, description, category}, ...]
                                       会话启动时加载，约 3,000 tokens
                                       ↓ 只有需要用某个技能时，才继续
Level 1: skill_view(name)           → 完整 SKILL.md 内容 + 元数据
                                       ↓ 只有需要参考文档时，才继续
Level 2: skill_view(name, path)     → 技能内的特定 references/ 文件

The practical significance of this design is very direct:

• You have 50 skills installed, but only 1 was used this session—only the full content of that one consumes tokens.
• The Level 0 skill list (~3,000 tokens) is always loaded at session startup, letting the agent know which skills are available.
• The rest is loaded only when the agent determines it's needed—no usage, no cost.

Progressive disclosure is what distinguishes the skill system fromStuffing all documentation into the system promptThis is the key design. It ensures the skill count can grow indefinitely while the per-session token cost remains essentially constant.

List of built-in skills

Hermes comes with a large set of built-in skills that can be used directly.

Launch hermes from the command line:

hermes

Use the following command to view skill-related commands:

/skills

The following command can view all skills in a session:

/skills browse

View directly in the command line with hermes:

hermes skills list

In the desktop version, click the Skills & Tools menu on the left to view:

Skill Categories

Built-in skills are stored in subdirectories categorized by function:

Optional skills (not installed by default)

Optional skills are released together with hermes-agent, stored inoptional-skills/but are not activated by default and require explicit installation.

These skills typically require additional dependencies or serve niche purposes:

Use skills

Skills have two trigger methods: direct invocation via slash commands and automatic triggering via natural language.

Slash commands for direct invocation

Every installed skill automatically becomes a slash command.

Use directly on any platform (CLI, Telegram, Discord, etc.):

built-inplanA skill is a good example: run/plan [请求]Afterwards, the skill instruction tells Hermes to first check the context, then generate a Markdown-format implementation plan and save it to.hermes/plans/, rather than executing the task directly.

Natural language triggering

Skills can also be triggered through natural conversation; Hermes will useskill_viewAutomatic tool loading:

The Agent will recognize the need for aarxivskill, automatically load it, and then execute.

Search skills by keyword

Installing skills from the Hub

Besides built-in skills, you can also install third-party skills from the agentskills.io community Hub.

Command-line installation

What happens after installation:

1. The skill directory is copied to~/.hermes/skills/
2. appears inskills_listin the output
3. Can be used as a slash command

Installed skills are innew conversationtake effect. To use it immediately in the current session, use /reset to start a new session, or add the --now parameter to immediately refresh the prompt cache (which consumes some extra tokens).

Verify Installation

Add a skill source from a GitHub repository

/learn command: generate a skill from a source with one click

/learnIt's a shortcut to quickly turn what you already know—or a pile of reference materials—into reusable skills, without hand-writing SKILL.md.

It is open-ended: point to anything you can describe, and the agent uses its existing tools to gather material, then generates the skill following standard authoring conventions.

How /learn works

The entire process is divided into three steps:

1. The agent uses existing tools to collect source material (reading files, scraping web pages, analyzing the current conversation)
2. Drafts SKILL.md following the official Skill authoring standards (including ≤60-character description, standard section order, Hermes tool framework, no fabricated commands)
3. Throughskill_manageTool saving — if enabledwrite_approval, approval is requested first

/learn is available in CLI, message gateway, TUI, and Dashboard with identical behavior. The Dashboard's Skills page also provides a graphicalLearn a skillpanel, containing three input fields: directory, URL, and free text.

Agent automatically creates skills

This is the most distinctive part of Hermes's skill system: Hermes learns from experience by saving reusable processes as skills.

When it solves a complex problem, discovers a workflow, or is corrected, it can persist this knowledge as skill documents to be loaded in future sessions.

Skills accumulate over time, making the agent increasingly adept at handling your specific tasks and environment.

Trigger timing

After completing a complex task (typically involving more than 5 tool calls), Hermes may proactively propose:

我注意到我们刚才走完了一个完整的 Docker 多阶段构建流程。
要不要我把这个工作流程保存为技能，下次可以直接复用？

Manually ask the agent to create a skill

You can also proactively request it at any time:

Controlling skill write permissions

By default, the agent is free to create and modify skills.

After enabling approval mode, the agent will first request your confirmation every time it wants to create or modify a skill:

With write_approval enabled, you can preview the skill content the agent intends to write before deciding whether to approve. This is an important security boundary—skill files have no signed provenance information and cannot distinguishWritten by the Agent itselfandManually placed in the directory。

SKILL.md format explained in detail

Skills are Markdown files with YAML frontmatter metadata.

The following is the complete format specification, including all optional and required fields:

Field Limits

Conditional activation: intelligent show/hide mechanism

Skills can be filtered based on tools available in the current sessionAutomatically show or hide, no manual management needed.

This is very useful in multi-environment deployments—the same skill list automatically adapts across different environments.

Practical Examples: Built-induckduckgo-searchSkill usedfallback_for_toolsets: [web]。

When you have configured a Firecrawl API Key (web tool set available), this skill is automatically hidden and the agent directly usesweb_search。

When the API Key is missing (web tool set unavailable), the DuckDuckGo skill automatically appears as a fallback.

Skill Bundle: combined loading

A skill pack is a YAML file that combines multiple skills under a single slash command.

Run/<bundle-name>When triggered, all skills listed in the pack load simultaneously—suitable for scenarios where a task always requires the same set of skills.

Create a skill package

When using:

The agent loads all three skills simultaneously and willRefactor authentication middlewareAppended as user instructions.

Skill package file format

Skill packages are stored in~/.hermes/skill-bundles/<slug>.yaml：

Platform-level skill management

Different platforms can enable different skill subsets.

For example, development-related skills don't need to appear on Telegram:

This opens an interactive TUI that lets you enable or disable skills per platform (CLI, Telegram, Discord, etc.).

Manually creating skills: getting started in five minutes

Skills are just Markdown files with YAML frontmatter metadata.

Creating a skill takes less than five minutes, no registration required, just put it in~/.hermes/skills/You can use it.

Step 1: Create a directory

Step 2: Write SKILL.md

Step 3 (optional): Add reference files

Step 4: Test

Security considerations for skills

Write approval gating

Skill files have no signed provenance information—cannot distinguishWritten by the Agent itselfandManually placed in the directory。

Write approval mechanism andpending/Directory management is a key security boundary.

After approval is enabled,write_approval: truecauses all skill write operations (including automatic creation initiated by the agent) to be staged as pending approval; you review before deciding whether to allow the write.

Security scan

Skill content is threat-scanned before loading, detecting malicious patterns such as prompt injection, backdoor installation instructions, etc.

Content matching threat patterns is replaced with[BLOCKED: ...]placeholder, preventing it from reaching the model—the file itself is not deleted, only the threatening content is blocked.

Considerations when installing from the Hub

Skill updates and maintenance

Check and update

Reset built-in skills

If you modified a built-in skill and want to restore the original:

Uninstalling Hub skills

Uninstalling can only remove skills installed via the Hub; built-in skills cannot be uninstalled (but you can stop receiving updates via `hermes skills opt-out`).

Publish skills to the Skills Hub

If you created a valuable skill, you can publish it to agentskills.io to share with the community:

Blueprint: skills + scheduled tasks

Skills can declare a schedule, turning into a shareable automation blueprint:

After installing this skill, run/suggestionsYou can see Hermes automatically propose creating the corresponding scheduled task:

External skill directory

If you maintain skills outside of Hermes—for example, one shared by multiple AI tools~/.agents/skills/Directories — lets Hermes scan these directories simultaneously.

Path Support~expand and${VAR}Environment variable substitution.

Important Rules：

• Local directory (~/.hermes/skills/) takes priority—when skills share the same name, the local version overrides the external version
• External directories are not write-protection boundaries: if the Hermes process has write permissions, the Agent can modify skills in external directories.

Common command quick reference

Create custom skills

Skills are stored in~/.hermes/skills/in the directory. Each skill is one that includesskill.mdDirectory of:

~/.hermes/skills/
└── my-custom-skill/
    └── skill.md

Skill Format

---
name: my-custom-skill
description: 一个有用的技能描述
version: 1.0.0
author: your-username
tags: [utility, example]
---

# 技能指令

您是一个专业的[角色]，擅长[领域]...

## 核心能力

1. 能力 A
2. 能力 B
3. 能力 C

## 使用示例

### 示例 1
[描述]

### 示例 2
[描述]

Skill metadata

Skill command reference