Skip to content

Skills Guide

Hermes Agent Skills system: format, sources, installation, multi-tenant isolation, and built-in skills.

Overview

Skills are pluggable capability modules for the Hermes Agent, defined via SKILL.md files that contain instructions and behaviors, granting the Agent specialized domain expertise.

SKILL.md Format

Each Skill is defined by a SKILL.md file containing YAML frontmatter and a Markdown body:

---
name: "skill-name"
description: "One-line description"
version: "1.0.0"
author: "author"
tags: ["tag1", "tag2"]
---

# Skill Title

Write detailed instructions, behavior rules, and examples for the Skill here.
The Agent reads this content as part of its system prompt to guide its behavior.

Field Reference

Field Required Description
name Yes Unique Skill identifier used for installation and reference
description Yes Short description for search and display
version No Semantic version number
author No Author information
tags No Tag array for categorization and search

Body Content

The Markdown body is the instruction content the Agent actually reads. It should include:

  • Role definition and behavior guidelines
  • Available tools and operation descriptions
  • Input/output format conventions
  • Example conversations or interaction flows
  • Limitations and notes

Skill Sources

1. Tenant Skills

In the supported SaaS runtime, custom Skills belong to a tenant and are managed through the Skills API or tenant-scoped object storage. The public product no longer loads user-home Skills through a standalone CLI runtime.

2. Built-in Skills

The repository's skills/ directory contains 81 pre-configured Skills in 26 categories:

Category Description Examples
software-development Software development Code review, refactoring, debugging
research Research and analysis Literature review, data analysis
creative Creative writing Storytelling, copywriting
data-science Data science Data cleaning, visualization
devops DevOps CI/CD, containerization
gaming Gaming Game design, NPC dialogue
github GitHub operations PR review, Issue management
productivity Productivity tools Task management, note-taking
red-teaming Security testing Penetration testing, vulnerability analysis
smart-home Smart home Home Assistant control
domain Domain-specific Custom business skills
... ... ...

See the repository's skills/ directory for the complete list.

3. MinIO Tenant Skills (SaaS Mode)

In SaaS multi-tenant mode, each tenant has independent Skills stored in MinIO/S3 object storage:

MinIO Bucket: hermes-skills
├── {tenant-id-1}/
│   ├── .manifest.json          # Skill manifest (hash, source, modification status)
│   ├── _soul/SOUL.md           # Tenant personality file
│   ├── skill-a/SKILL.md
│   └── skill-b/SKILL.md
├── {tenant-id-2}/
│   ├── .manifest.json
│   ├── _soul/SOUL.md
│   ├── skill-c/SKILL.md
│   └── skill-d/SKILL.md

Isolation guarantee: - Each tenant can only access their own Skills - Skill paths are isolated with {tenant-id}/ as prefix - Different tenants can have Skills with the same name but different content

Auto-Provisioning

Triggered automatically when creating a tenant: When a new tenant is created via POST /v1/tenants, the system asynchronously executes:

  1. Skill sync: Copies all 81 built-in skills from the skills/ directory to the tenant's MinIO prefix
  2. Soul creation: Generates a default SOUL.md personality file at {tenant-id}/_soul/SOUL.md
  3. Manifest write: Creates .manifest.json recording each skill's SHA-256 hash and source

Full sync on service startup: When hermesx saas-api starts, it iterates through all tenants for incremental sync: - Newly added built-in skills are automatically installed - Updated built-in skills are overwritten (unless the user has modified them) - User-modified skills (user_modified: true) are not overwritten

Skill Manifest (.manifest.json)

{
  "version": 1,
  "skills": {
    "code-review": {
      "hash": "a1b2c3d4...",
      "source": "builtin",
      "installed_at": "2026-04-29T12:00:00Z",
      "user_modified": false
    },
    "my-custom-skill": {
      "hash": "",
      "source": "user",
      "installed_at": "2026-04-29T13:00:00Z",
      "user_modified": true
    }
  },
  "synced_at": "2026-04-29T12:00:00Z"
}

Configuring MinIO

export MINIO_ENDPOINT="localhost:9000"
export MINIO_ACCESS_KEY="hermes"
export MINIO_SECRET_KEY="hermespass"
export MINIO_BUCKET="hermes-skills"
export MINIO_USE_SSL="false"

Skills Management API

SaaS mode provides a RESTful API to manage tenant skills without directly operating MinIO:

List Skills

curl http://localhost:8080/v1/skills \
  -H "Authorization: Bearer hk_your_api_key"

Upload/Update a Skill

curl -X PUT http://localhost:8080/v1/skills/my-custom-skill \
  -H "Authorization: Bearer hk_your_api_key" \
  -d '---
name: "my-custom-skill"
description: "Custom business skill"
version: "1.0.0"
---

# My Custom Skill
...'

Uploaded skills are automatically marked as user_modified and will not be overwritten by subsequent built-in skill syncs.

Delete a Skill

curl -X DELETE http://localhost:8080/v1/skills/my-custom-skill \
  -H "Authorization: Bearer hk_your_api_key"

For detailed API reference see the API Reference documentation.

Direct Upload via mc CLI (Advanced)

mc alias set hermes http://localhost:9000 hermes hermespass
mc cp ./my-skill/SKILL.md hermes/hermes-skills/{tenant-id}/my-skill/SKILL.md

Or batch upload using the seed script:

./scripts/seed_minio_skills.sh

4. Skills Hub

Hermes supports discovering and installing Skills from an online Hub.

Default Hub Sources

Source Type Trust Level Description
agentskills.io URL community Community Skill marketplace
hermes-official GitHub trusted Official optional Skills

Discover and Install Skills

Hub discovery is exposed through SaaS control-plane workflows. Standalone hermes skill ... commands are no longer supported public interfaces.

Installation process: 1. Resolve SKILL.md from a trusted Hub source 2. Run security scan based on trust level 3. Upload the Skill to the tenant through PUT /v1/skills/{name} or the tenant MinIO/S3 prefix 4. Update the tenant .manifest.json object for audit and sync tracking

Security Scanning

Skills installed from the Hub undergo security scanning:

Trust Level Scan Intensity Failure Handling
builtin No scan Install directly
trusted Standard scan Warn but allow installation
community Strict scan Block suspicious Skills

Scan checks include: - Dangerous instructions (e.g., attempting to execute system commands) - Sensitive data access patterns - Injection attack patterns

When the security scan decision is InstallBlock, the Skill file is automatically deleted.

Tenant Manifest

Installed Skills are recorded in the tenant manifest object:

MinIO/S3: {tenant-id}/.manifest.json

[
  {
    "name": "code-review",
    "source": "https://agentskills.io/api/skills/code-review",
    "installed": "2026-04-29T12:00:00Z"
  }
]

The tenant manifest is used to: - Track installed Skills and their sources - Support batch updates and version management - Audit Skill installation history

Skill Isolation in SaaS Mode

In the SaaS multi-tenant environment, Skills implement complete tenant isolation:

Load Priority

1. Tenant-specific Skills (MinIO: {tenant-id}/skill-name/)
2. Global shared Skills (local skills/ directory, copied to MinIO via auto-sync)

Skill Injection in Chat

When a user sends a chat request, the system automatically loads all installed skills for the tenant from MinIO and injects the skill list into the system prompt:

## Available Skills
- code-review: Code review assistant
- debugging: Debugging expert
- my-custom-skill: Custom business skill

Isolation Testing

The project includes a complete Skill isolation test script:

# Run Skill isolation tests
./scripts/test_real_skill_isolation.sh

Tests verify: - After assigning different Skills to different tenants, each tenant's Agent behaves as expected - Cross-tenant access to other tenants' Skills does not occur - Skill content changes do not affect other tenants

Example: Assigning Different Personalities to Tenants

# Tenant A: pirate style
mc cp pirate-skill/SKILL.md hermes/hermes-skills/tenant-${TENANT_A}/pirate/SKILL.md

# Tenant B: scientist style
mc cp scientist-skill/SKILL.md hermes/hermes-skills/tenant-${TENANT_B}/scientist/SKILL.md

Both tenants call the same Chat API, but the Agent exhibits different personalities and expertise.

Creating Custom Skills

1. Create a Skill File

mkdir -p ./my-custom-skill
cat > ./my-custom-skill/SKILL.md << 'EOF'
---
name: "my-custom-skill"
description: "Custom business Skill"
version: "1.0.0"
author: "your-name"
tags: ["custom", "business"]
---

# My Custom Skill

## Role
You are a professional XX assistant.

## Behavior Guidelines
- Always use professional terminology
- Keep answers concise and accurate

## Output Format
Output results in Markdown format.
EOF

2. Upload to the SaaS API

curl -X PUT http://localhost:8080/v1/skills/my-custom-skill \
  -H "Authorization: Bearer hk_your_api_key" \
  --data-binary @./my-custom-skill/SKILL.md

3. Verify Loading

curl http://localhost:8080/v1/skills \
  -H "Authorization: Bearer hk_your_api_key"

Or directly via MinIO:

mc cp ./my-custom-skill/SKILL.md \
  hermes/hermes-skills/${TENANT_ID}/my-custom-skill/SKILL.md