How to Create Custom Skills and Contribute to the Skills Hub Ecosystem in Hermes Agent

Creating custom skills in Hermes Agent involves authoring a SKILL.md file with YAML front-matter, testing locally with skills_list and skill_view tools, and publishing via GitHub pull requests or the hermes skills publish CLI command after passing a security scan.

Hermes Agent by NousResearch treats skills as self-contained knowledge packages that extend LLM capabilities through a discoverable, secure ecosystem. The Skills Hub provides the infrastructure for sharing these packages, whether through private taps or the public repository, enabling community-driven extensions to the agent's capabilities.

Understanding the Skill Structure and Architecture

A skill in Hermes Agent is fundamentally a directory containing a mandatory SKILL.md file and optional supporting assets. The architecture is designed for progressive disclosure, where metadata is lightweight but full content is accessible on demand.

Required SKILL.md Format

Every skill must contain a SKILL.md file with YAML front-matter followed by markdown content. According to tools/skills_tool.py lines 28-42, the front-matter is parsed by the _parse_frontmatter function and must include:

• name: Unique identifier for the skill
• description: Brief explanation for discovery
• version: Semantic versioning string
• platforms (optional): Array of supported operating systems (linux, darwin, win32)
• metadata (optional): Tags, related skills, and custom attributes

Optional Asset Directories

Supporting files are organized into standard subdirectories as implemented in tools/skills_tool.py lines 75-84:

• references/: External documentation or papers
• templates/: Reusable code templates or prompts
• assets/: Images, data files, or binary resources
• scripts/: Executable automation scripts

These assets are exposed via the skill_view tool with a file_path parameter for granular access.

Authoring Your First Custom Skill

The authoring process follows a three-phase lifecycle: creation, local testing, and publication.

Creating the Directory Structure

Create your skill directory under ~/.hermes/skills/ with appropriate categorization:

mkdir -p ~/.hermes/skills/mlops/axolotl-finetuning
touch ~/.hermes/skills/mlops/axolotl-finetuning/SKILL.md

The directory structure supports nested categories, enabling logical organization of related skills.

Writing the YAML Front-Matter

Edit SKILL.md to include valid front-matter as parsed by _parse_frontmatter in tools/skills_tool.py:

---
name: axolotl-finetuning
description: Fine-tune LLMs using Axolotl with optimized configurations for consumer hardware.
version: 1.2.0
platforms: [linux, darwin]
metadata:
  hermes:
    tags: [ml, training, llm, axolotl]
    related_skills: [llama-cpp-conversion, vllm-deployment]
---

# Axolotl Fine-Tuning Guide

This skill provides step-by-step instructions...

The platforms field is optional but recommended; the skill_matches_platform helper in tools/skills_tool.py lines 94-118 filters skills at load time based on the host OS.

Adding Supporting Assets

Populate optional directories for comprehensive functionality:

mkdir -p ~/.hermes/skills/mlops/axolotl-finetuning/{templates,scripts,references}
cp ~/configs/qlora.yml ~/.hermes/skills/mlops/axolotl-finetuning/templates/
cp ~/scripts/setup_env.sh ~/.hermes/skills/mlops/axolotl-finetuning/scripts/

These files become accessible through the skill_view tool with the file_path parameter.

Testing and Previewing Skills Locally

Before publication, validate your skill using Hermes' progressive disclosure tools to ensure discoverability and content integrity.

Using skills_list for Metadata Discovery

The skills_list function in tools/skills_tool.py lines 70-84 returns only metadata to maintain token efficiency:

from tools.skills_tool import skills_list

# List all skills with metadata only

metadata = skills_list()
print(metadata)

Or via CLI:

hermes skills list

This invokes _find_all_skills (lines 22-73) which walks ~/.hermes/skills/ and applies platform filtering via skill_matches_platform.

Inspecting Full Content with skill_view

For detailed inspection, use skill_view implemented in tools/skills_tool.py lines 30-46:

from tools.skills_tool import skill_view

# View full SKILL.md content

full_skill = skill_view("axolotl-finetuning")
print(full_skill["content"])

# Access specific linked file

template = skill_view("axolotl-finetuning", file_path="templates/qlora.yml")

CLI equivalent:

hermes skills inspect axolotl-finetuning

This validates that your front-matter parses correctly and linked assets are accessible.

Security Scanning with Skills Guard

Every skill undergoes mandatory security analysis before installation or publication. The tools/skills_guard.py module provides scan_skill and should_allow_install functions that check for dangerous commands (e.g., rm -rf, chmod 777) and suspicious patterns such as unauthorized network calls or credential handling.

The scan runs automatically during:

• Local installation via do_install in tools/skills_hub.py
• Publication via do_publish in tools/skills_hub.py lines 50-66

If the scan returns a dangerous verdict, the operation aborts unless explicitly overridden with --force (not recommended for community skills). The format_scan_report function generates human-readable output explaining any detected risks.

Publishing and Contributing to the Skills Hub

Hermes Agent supports both private distribution through custom taps and public contribution to the official Skills Hub.

Private Distribution via Custom Taps

For internal or proprietary skills, register a private GitHub repository as a tap using the TapsManager class in tools/skills_hub.py lines 122-152:

hermes skills tap add myorg/private-skills-repo

This stores the tap configuration in ~/.hermes/skills/.hub/taps.json. Once added, browse and install private skills:

hermes skills browse --source github
hermes skills install myorg/private-skills-repo/path/to/skill

Contributing to the Official Hub via Pull Request

To make skills available to all Hermes users, contribute to the optional-skills/ directory in the main repository:

1. Fork the NousResearch/hermes-agent repository
2. Add your skill under optional-skills/<category>/<skill-name>/
3. Ensure SKILL.md follows the front-matter specification
4. Submit a pull request

The CI pipeline automatically recognizes skills in optional-skills/ as official optional skills with source=official and trust=builtin status.

Automated Publishing with hermes skills publish

For streamlined contribution, use the built-in publish command implemented in tools/skills_hub.py:

hermes skills publish ~/.hermes/skills/my-category/my-skill \
    --to github \
    --repo NousResearch/hermes-agent

The do_publish function (lines 50-66) executes:

1. Validation – confirms SKILL.md exists and parses correctly
2. Security Scan – runs scan_skill via tools/skills_guard.py (line 86)
3. GitHub Operations – _github_publish (lines 119-165) forks the repository, creates a branch, uploads files to optional-skills/, and opens a pull request with scan results

If the security scan detects dangerous patterns, the publish aborts (line 89) unless --force is specified.

Installing Skills from the Hub

Once published, users install skills via the do_install function in tools/skills_hub.py (lines 42-55):

hermes skills install NousResearch/hermes-agent/optional-skills/mlops/axolotl-finetuning

The installation process:

1. Resolution – _resolve_short_name (lines 32-66) maps short names to full identifiers
2. Fetch – Retrieves the bundle from the appropriate SkillSource (GitHub, ClawHub, etc.)
3. Quarantine & Scan – scan_skill validates safety before permanent installation
4. Placement – Moves files to ~/.hermes/skills/ and records provenance in HubLockFile (lines 155-188)
5. Audit – Appends entry to the installation audit log

Summary

• Skill Structure: Create a directory with a mandatory SKILL.md file containing YAML front-matter and markdown content, plus optional references/, templates/, assets/, or scripts/ directories.
• Local Testing: Use skills_list and skill_view from tools/skills_tool.py to verify discoverability and content loading before publication.
• Security Validation: All skills undergo mandatory scanning via tools/skills_guard.py to detect dangerous commands and suspicious patterns before installation or publishing.
• Distribution Options: Share skills privately through custom taps managed by TapsManager in tools/skills_hub.py, or contribute publicly via GitHub pull requests to the optional-skills/ directory.
• Automated Publishing: The hermes skills publish command handles forking, branch creation, file uploads, and pull request generation through _github_publish in tools/skills_hub.py.

Frequently Asked Questions

What file format is required for creating a custom skill in Hermes Agent?

Every custom skill requires a SKILL.md file at the root of the skill directory. This file must contain YAML front-matter (parsed by _parse_frontmatter in tools/skills_tool.py lines 26-38) followed by markdown content. The front-matter must include name, description, and version fields, with optional platforms and metadata fields for filtering and categorization.

How does Hermes Agent ensure custom skills are safe before installation?

Hermes Agent implements mandatory security scanning through tools/skills_guard.py before any installation or publication. The scan_skill function checks for dangerous shell commands (such as rm -rf or chmod 777) and suspicious patterns including unauthorized network calls or credential handling. If the scan returns a dangerous verdict, the do_install or do_publish functions in tools/skills_hub.py abort the operation unless explicitly overridden with the --force flag.

What is the difference between private taps and the official Skills Hub?

Private taps allow distribution of proprietary or internal skills through custom GitHub repositories registered via hermes skills tap add, managed by the TapsManager class in tools/skills_hub.py lines 122-152. These store configuration in ~/.hermes/skills/.hub/taps.json and remain separate from public distribution. The official Skills Hub refers to the optional-skills/ directory in the main NousResearch/hermes-agent repository, where contributed skills become available to all users with source=official and trust=builtin status after merging via pull request.

How do I publish a skill using the Hermes CLI instead of manual GitHub operations?

The hermes skills publish command automates the entire contribution workflow through the do_publish function in tools/skills_hub.py lines 50-66. After validating the skill and running a security scan, the _github_publish function (lines 119-165) automatically forks the target repository, creates a feature branch, uploads all skill files to the optional-skills/ directory using the GitHub Contents API, and opens a pull request with a pre-filled description including security scan results.

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