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

> Learn how to create custom skills and contribute to the Hermes Agent Skills Hub. Follow our guide for authoring, testing, and publishing your own skills.

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

---

**Creating custom skills in Hermes Agent involves authoring a [`SKILL.md`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/SKILL.md) file with YAML front-matter followed by markdown content. According to [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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:

```bash
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`](https://github.com/NousResearch/hermes-agent/blob/main/SKILL.md) to include valid front-matter as parsed by `_parse_frontmatter` in [`tools/skills_tool.py`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py):

```yaml
---
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`](https://github.com/NousResearch/hermes-agent/blob/main/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:

```bash
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`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py) lines 70-84 returns only metadata to maintain token efficiency:

```python
from tools.skills_tool import skills_list

# List all skills with metadata only

metadata = skills_list()
print(metadata)

```

Or via CLI:

```bash
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`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py) lines 30-46:

```python
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:

```bash
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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_hub.py)
- Publication via `do_publish` in [`tools/skills_hub.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_hub.py) lines 122-152:

```bash
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:

```bash
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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_hub.py):

```bash
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`](https://github.com/NousResearch/hermes-agent/blob/main/SKILL.md) exists and parses correctly
2. **Security Scan** – runs `scan_skill` via [`tools/skills_guard.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_hub.py) (lines 42-55):

```bash
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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/tools/skills_tool.py) to verify discoverability and content loading before publication.
- **Security Validation**: All skills undergo mandatory scanning via [`tools/skills_guard.py`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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`](https://github.com/NousResearch/hermes-agent/blob/main/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.