# How the Hermes Agent Skills System Works and Its agentskills.io Compatibility

> Discover how Hermes Agent's skills system works, storing reusable knowledge and ensuring full agentskillsio compatibility. Learn about its progressive-disclosure implementation.

- Repository: [Nous Research/hermes-agent](https://github.com/NousResearch/hermes-agent)
- Tags: internals
- Published: 2026-03-09

---

**Hermes Agent implements a progressive-disclosure skills subsystem that stores reusable knowledge documents in `~/.hermes/skills/` and fully supports the agentskills.io specification for front-matter metadata and asset organization.**

The NousResearch/hermes-agent repository ships a self-contained skills system that lets the LLM discover, list, and read reusable knowledge documents on-demand. This implementation follows a progressive-disclosure design inspired by Anthropic’s Claude Skills while maintaining strict compatibility with the agentskills.io specification for markdown front-matter and optional asset layouts.

## Core Architecture of the Skills System

### Skill Storage and Directory Structure

All skill folders live under `~/.hermes/skills/`. The directory is created lazily on first use through the `HERMES_HOME` environment variable resolution.

In [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py), the storage paths are defined as:

```python
HERMES_HOME = Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
SKILLS_DIR = HERMES_HOME / "skills"

```

Each skill is a subdirectory containing a [`SKILL.md`](https://github.com/NousResearch/hermes-agent/blob/main/SKILL.md) file and optional supporting files in an `assets/` folder.

### Progressive Disclosure Design

The system uses a tiered disclosure strategy to minimize token usage during skill discovery.

**Tier 1** is implemented in `skills_list()` (lines 71-84 in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py)), which returns only the skill name and description without loading full content.

**Tier 2-3** is handled by `skill_view()` (lines 30-41 in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py)), which loads the full [`SKILL.md`](https://github.com/NousResearch/hermes-agent/blob/main/SKILL.md) and any linked files only when the model explicitly requests them.

### Platform Filtering and Safety

Skills can declare a `platforms:` list in their front-matter. The loader skips incompatible entries using `skill_matches_platform()` (lines 94-118 in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py)).

The system also safeguards against path traversal attacks before reading any linked files, ensuring that requests cannot escape the skill's directory boundary.

## agentskills.io Compatibility Implementation

### Front-Matter Parsing

The markdown files must start with a YAML front-matter block adhering to the agentskills schema. The parser accepts full YAML via `yaml.safe_load` and gracefully degrades to simple key/value parsing if the YAML is malformed.

This logic resides in `_parse_frontmatter()` (lines 126-160 in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py)):

```python
def _parse_frontmatter(content: str) -> dict:
    # Attempts yaml.safe_load first, then falls back to naive parsing

    # Returns dict with name, description, platforms, metadata, etc.

```

Required fields include `name` and `description`. Optional fields such as `license`, `platforms`, and `metadata.hermes.tags` are also recognized.

### Asset Directory Support

The `assets/` folder is explicitly supported as a standard location for supplementary files like images, configurations, or reference data. This matches the agentskills.io asset layout specification documented in the code comments (lines 23-24 in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py)).

### Discovery Mechanism

Skills are discovered via a recursive `rglob("SKILL.md")` scan of the `SKILLS_DIR`, identical to the discovery pattern used by agentskills.io tools to locate skill bundles on disk.

## Tool Registration and CLI Integration

### Core Skill Tools

Three public tools are registered in [`toolsets.py`](https://github.com/NousResearch/hermes-agent/blob/main/toolsets.py) under the `"skills_tools"` set:

- `skills_list` – Returns minimal metadata for all compatible skills
- `skill_view` – Loads full skill content and linked files
- `skill_manage` – Provides edit/create operations (optional skills hub)

This registration occurs around lines 43 and 112 in [`toolsets.py`](https://github.com/NousResearch/hermes-agent/blob/main/toolsets.py), making the tools available to the LLM when the appropriate toolset is enabled.

### Slash Commands

The `skill_view` functionality is exposed to users as a `/skill_name` slash command through [`agent/skill_commands.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/skill_commands.py). The `build_skill_invocation_message()` function (lines 107-111) constructs a prompt that automatically includes a "view linked files" hint, guiding the LLM to request additional resources when needed.

## Practical Code Examples

### Listing Available Skills

```python
from tools.skills_tool import skills_list

# Returns a JSON string with minimal metadata

result_json = skills_list()
print(result_json)

```

**Result snippet:**

```json
{
  "success": true,
  "skills": [
    {"name":"axolotl","description":"Fine‑tune LLMs with LoRA"},
    {"name":"vllm","description":"Run inference with vLLM"}
  ],
  "categories":["mlops"],
  "count":2,
  "hint":"Use skill_view(name) to see full content, tags, and linked files"
}

```

### Loading a Full Skill

```python
from tools.skills_tool import skill_view

# Load the entire SKILL.md

skill_json = skill_view("axolotl")
print(skill_json)

```

**Result snippet:**

```json
{
  "success": true,
  "name":"axolotl",
  "description":"Fine‑tune LLMs with LoRA",
  "tags":["fine-tuning","llm"],
  "content":"# Axolotl\n\nFull instructions ...",

  "linked_files":["references/api.md","assets/config.yaml"]
}

```

### Reading Linked Files

```python
from tools.skills_tool import skill_view

# Load a supporting reference file

ref_json = skill_view("axolotl", "references/api.md")
print(ref_json)

```

The function safeguards against path traversal (lines 88-96 in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py)) before reading the file.

### Using Slash Commands

When a user types `/axolotl` in the Hermes CLI, [`agent/skill_commands.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/skill_commands.py) builds a prompt containing:

```text
[This skill has supporting files you can load with the skill_view tool:]
To view any of these, use: skill_view(name="axolotl", file="<path>")

```

## Summary

- **Hermes Agent** stores skills in `~/.hermes/skills/` with lazy directory creation, using a progressive-disclosure architecture to minimize token usage.
- The **agentskills.io** specification is fully supported through YAML front-matter parsing, platform filtering, and `assets/` directory recognition.
- Core functions `skills_list()` and `skill_view()` in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py) implement tiered discovery and safe file loading with path traversal protection.
- Skills are exposed to the LLM through the `"skills_tools"` toolset registered in [`toolsets.py`](https://github.com/NousResearch/hermes-agent/blob/main/toolsets.py) and accessible via slash commands through [`agent/skill_commands.py`](https://github.com/NousResearch/hermes-agent/blob/main/agent/skill_commands.py).

## Frequently Asked Questions

### What is the agentskills.io specification?

The agentskills.io specification defines a standard format for packaging reusable AI skills using markdown files with YAML front-matter. It specifies required fields like `name` and `description`, optional metadata such as `platforms` and `license`, and a directory structure that includes an optional `assets/` folder for supplementary files. Hermes Agent adheres to this specification to ensure interoperability with skill packages from the broader ecosystem.

### How does Hermes Agent prevent token overflow when listing skills?

Hermes Agent implements a **progressive disclosure** pattern through the `skills_list()` function in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py). This function returns only minimal metadata—name, description, and category—without loading the full markdown content. The full skill content and linked files are only retrieved when the LLM explicitly calls `skill_view()`, ensuring that initial discovery consumes minimal tokens regardless of how extensive the skill library grows.

### Can skills be restricted to specific operating systems?

Yes, skills can declare platform compatibility through the optional `platforms:` list in their YAML front-matter. The `skill_matches_platform()` function (lines 94-118 in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py)) filters skills based on the current operating system, ensuring that incompatible skills are hidden from the LLM during discovery. This prevents the agent from attempting to use tools or workflows that require specific hardware or OS features unavailable on the current machine.

### Where are skill files stored and how are they discovered?

Skill files are stored in the `~/.hermes/skills/` directory, which is resolved through the `HERMES_HOME` environment variable or defaults to the user's home directory. Discovery occurs via a recursive `rglob("SKILL.md")` scan performed by `skills_list()` in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py). This pattern matches the agentskills.io discovery mechanism, allowing any compliant skill package dropped into the skills directory to be automatically detected and made available to the LLM.