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

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, the storage paths are defined as:

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

Each skill is a subdirectory containing a 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), 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), which loads the full 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).

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):

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

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

from tools.skills_tool import skills_list

# Returns a JSON string with minimal metadata

result_json = skills_list()
print(result_json)

Result snippet:

{
  "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

from tools.skills_tool import skill_view

# Load the entire SKILL.md

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

Result snippet:

{
  "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

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) before reading the file.

Using Slash Commands

When a user types /axolotl in the Hermes CLI, agent/skill_commands.py builds a prompt containing:

[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 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 and accessible via slash commands through 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. 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) 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}