Chapter 2 Skills Development

Skills are the primary way to extend Hermes Agent. No source code changes needed, no Python classes to write — a single Markdown file is all it takes to teach Cuttlefish a new skill.

Skill vs Tool: Which to Choose?

	Skill	Tool (Plugin)
Format	Markdown document	Python code
Source modification	Not required	Required
Development difficulty	Low	Medium-High
Use cases	Workflow guidance, API integration	New tool types, low-level capabilities
Sharing method	Skills Hub / GitHub	PR to main repository

Rule of thumb: Skills handle 90% of use cases. Only consider a Tool plugin when you need to register an entirely new tool type.

Directory Structure

~/.hermes/skills/
└── my-skill/
    ├── SKILL.md              # Required: skill instructions
    ├── references/           # Optional: reference docs
    │   └── api-reference.md
    ├── templates/            # Optional: template files
    │   └── config.yaml
    ├── scripts/              # Optional: helper scripts
    │   └── helper.py
    └── assets/               # Optional: resource files

Official Skills are organized by category under skills/:

skills/
├── research/
│   └── arxiv/
│       ├── SKILL.md
│       └── scripts/search_arxiv.py
├── productivity/
│   └── ocr-and-documents/
│       ├── SKILL.md
│       └── references/
└── ...

SKILL.md Complete Format

markdown

---
name: my-skill
description: A one-line description of the skill (shown in search results)
version: 1.0.0
author: Your Name
license: MIT

# Platform restrictions (optional)
platforms: [macos, linux]

metadata:
  hermes:
    tags: [category, subcategory, keyword]
    related_skills: [other-skill]

    # Conditional activation
    requires_toolsets: [web]           # Only shown when web toolset is available
    requires_tools: [web_search]       # Only shown when web_search tool is available
    fallback_for_toolsets: [browser]   # Shown as fallback when browser toolset is unavailable
    fallback_for_tools: [browser_navigate]

    # Non-secret configuration
    config:
      - key: my.setting
        description: "Configuration description"
        default: "sensible-default"
        prompt: "Configuration prompt"

# Environment variables (secrets)
required_environment_variables:
  - name: MY_API_KEY
    prompt: "Enter your API Key"
    help: "Get it at https://example.com"
    required_for: "API access feature"
---

# Skill Title

Brief introduction.

## When to Use

Trigger conditions — when should the Agent load this skill?

## Quick Reference

Common commands or API call cheat sheet.

## Steps

Step-by-step instructions for the Agent to follow.

## Caveats

Known failure modes and how to handle them.

## Verification

How the Agent can confirm the operation succeeded.

Frontmatter Field Reference

Basic Fields

Field	Required	Description
`name`	✅	Skill identifier, lowercase + hyphens
`description`	✅	Description shown in search results
`version`	❌	Semantic version number
`author`	❌	Author name
`license`	❌	Open source license

Platform Restrictions

yaml

platforms: [macos]          # macOS only
platforms: [macos, linux]   # macOS + Linux
platforms: [windows]        # Windows only
# Omit → all platforms

Skills on incompatible platforms are automatically hidden from the system prompt, skill list, and slash commands.

Conditional Activation

yaml

metadata:
  hermes:
    requires_toolsets: [web]              # Requires these toolsets to be shown
    requires_tools: [web_search]          # Requires these tools to be shown
    fallback_for_toolsets: [browser]      # Only shown when these toolsets are unavailable
    fallback_for_tools: [browser_navigate] # Only shown when these tools are unavailable

Logic rules:

Field	Hidden When
`requires_toolsets`	Any listed toolset is unavailable
`requires_tools`	Any listed tool is unavailable
`fallback_for_toolsets`	Any listed toolset is available
`fallback_for_tools`	Any listed tool is available

Environment Variables (Secrets)

yaml

required_environment_variables:
  - name: MY_API_KEY
    prompt: "Enter your API Key"
    help: "Get it at https://example.com"
    required_for: "API access"

Automatically handled on load:

Local CLI: Secure prompt for input (not exposed to the model)
Gateway/chat: Display local setup instructions
Auto-injected into execute_code and terminal sandbox

Configuration Items (Non-Secret)

yaml

metadata:
  hermes:
    config:
      - key: output_dir
        description: "Output directory"
        default: "~/output"
        prompt: "Set output directory"

Stored under skills.config in config.yaml, automatically injected into the Agent context on load.

Writing Best Practices

1. Progressive Disclosure

Put the most commonly used flows first, edge cases and advanced usage at the bottom:

markdown

## Quick Start (90% of use cases)
...

## Advanced Usage
...

## Troubleshooting
...

This saves tokens — common tasks only load the first half.

2. No External Dependencies

Prefer:

Python standard library
curl (built-in)
Existing Hermes tools (web_extract, terminal, read_file)

If external dependencies are necessary, clearly document the installation steps in the skill.

3. Include Helper Scripts

Put complex parsing logic in the scripts/ directory — don't make the LLM rewrite it every time:

scripts/
└── parse_api_response.py   # Helper script for parsing API responses

4. Include Verification Steps

Let the Agent know how to confirm success:

markdown

## Verification

Run the following command to confirm the configuration is active:
\`\`\`bash
hermes doctor
\`\`\`
If the output contains "✅ my-service: connected", the configuration was successful.

Hands-On: Creating a Custom Skill

Scenario

Create a git-workflow skill that helps the Agent manage Git branches and PRs.

Step 1: Create the Directory

bash

mkdir -p ~/.hermes/skills/git-workflow

Step 2: Write SKILL.md

markdown

---
name: git-workflow
description: Git branch management and PR workflow
metadata:
  hermes:
    tags: [git, workflow, github]
    related_skills: [github-pr-workflow]
---

# Git Workflow

A workflow skill for managing Git branches, commits, and PRs.

## When to Use

Load when the user mentions:
- Create branch / new feature branch
- Commit code / commit
- Create PR / initiate merge

## Branch Naming Convention

- Feature branches: feature/xxx
- Fix branches: fix/xxx
- Release branches: release/vX.Y.Z

## Workflow

### Creating a Feature Branch

1. Pull latest code from main
2. Create feature/xxx branch
3. Commit when development is done
4. Push and create PR

### Commit Message Convention

Format: type(scope): description

Types include: feat, fix, docs, refactor, test, chore

## Caveats

- Never push directly to main
- PR description should include change summary and test steps
- Ensure CI passes before merging

Step 3: Test

You: Help me create a new feature branch
Hermes: [Auto-loads git-workflow skill]
        Sure, what's the name of the new feature?

Step 4: Iterate and Improve

Refine the wording and steps in SKILL.md based on actual usage until the Agent's performance is satisfactory.

Publishing Skills

Publish to Skills Hub

bash

hermes skills publish my-skill

All Hub-installed skills go through a security scan that checks for:

Malicious command injection
Sensitive information leakage
Unsafe file operations

Publish to a Custom Repository

Create a GitHub repository for your skills
Users add it as a tap:

bash

hermes skills tap add your-username/your-skills-repo
hermes skills install my-skill

Contribute to Official

If your skill is general-purpose enough, you can submit a PR to the Hermes Agent main repository:

General skills → skills/ directory
Skills with specific dependencies → optional-skills/ directory

Skill Location Comparison

Location	Best For	Installation Method
`~/.hermes/skills/`	Personal/custom skills	Manual creation
Skills Hub	Community-shared skills	`hermes skills install`
GitHub tap	Team/organization skills	`hermes skills tap add`
Source `skills/`	Official built-in skills	Installed with Hermes
Source `optional-skills/`	Official optional skills	`hermes skills browse`

Chapter 2 Skills Development ​

Skill vs Tool: Which to Choose? ​

Directory Structure ​

SKILL.md Complete Format ​

Frontmatter Field Reference ​

Basic Fields ​

Platform Restrictions ​

Conditional Activation ​

Environment Variables (Secrets) ​

Configuration Items (Non-Secret) ​

Writing Best Practices ​

1. Progressive Disclosure ​

2. No External Dependencies ​

3. Include Helper Scripts ​

4. Include Verification Steps ​

Hands-On: Creating a Custom Skill ​

Scenario ​

Step 1: Create the Directory ​

Step 2: Write SKILL.md ​

Step 3: Test ​

Step 4: Iterate and Improve ​

Publishing Skills ​

Publish to Skills Hub ​

Publish to a Custom Repository ​

Contribute to Official ​

Skill Location Comparison ​

Further Reading ​

Chapter 2 Skills Development

Skill vs Tool: Which to Choose?

Directory Structure

SKILL.md Complete Format

Frontmatter Field Reference

Basic Fields

Platform Restrictions

Conditional Activation

Environment Variables (Secrets)

Configuration Items (Non-Secret)

Writing Best Practices

1. Progressive Disclosure

2. No External Dependencies

3. Include Helper Scripts

4. Include Verification Steps

Hands-On: Creating a Custom Skill

Scenario

Step 1: Create the Directory

Step 2: Write SKILL.md

Step 3: Test

Step 4: Iterate and Improve

Publishing Skills

Publish to Skills Hub

Publish to a Custom Repository

Contribute to Official

Skill Location Comparison

Further Reading