The Skills System: An Agent That Learns

The Skills System: An Agent That Learns

An AI agent that executes tasks is good. An agent that learns from its experiences and improves over time is revolutionary. That's exactly what the Skills system in Hermes Agent offers: a procedural memory that transforms every interaction into a reusable capability.

In this article, we explore the skills system in depth — from the SKILL.md file format to the Skills Hub, including automatic skill creation by the agent.

What is a Skill?

A skill in Hermes Agent is an on-demand knowledge document. Unlike a static system prompt that clutters the context in every conversation, a skill is only loaded when the agent actually needs it.

Skills follow the open agentskills.io standard, making them interoperable with other AI agents and skill ecosystems.

💡 Analogy: think of skills as browser extensions. They aren't all active at once, but each adds a specific capability when you need it.

The SKILL.md Format

Each skill is defined by a SKILL.md file composed of two parts: a YAML frontmatter (metadata) and a Markdown body (instructions).

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]
    requires_toolsets: [terminal]
    config:
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Setup prompt"
---
# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

Key frontmatter fields:

• name: unique skill identifier (kebab-case)
• description: summary for discovery and indexing
• version: update tracking
• platforms: OS filter (macos, linux, windows)
• metadata.hermes.tags: labels for search
• metadata.hermes.category: categorization (devops, mlops, productivity…)
• metadata.hermes.config: configurable settings stored in config.yaml

Progressive Disclosure

One of the most intelligent aspects of the system is its three-level loading approach, designed to minimize token consumption:

Level 0 — skills_list(): the agent gets a lightweight list of all available skills (~3,000 tokens). Each entry contains only the name, description, and category. Sufficient to decide if a skill is relevant.

Level 1 — skill_view(name): the agent loads the full skill content (frontmatter + body). Used when the agent has identified a relevant skill and wants to follow its instructions.

Level 2 — skill_view(name, path): the agent loads a specific file from the skill (a template, a reference script, an asset). Useful for multimodal skills with complementary files.

The agent only loads full content when it actually needs it. This token economy is significant over long sessions.

The ~/.hermes/skills/ Directory

All skills reside in ~/.hermes/skills/ — the primary directory and source of truth. Here is its typical structure:

~/.hermes/skills/
├── mlops/
│   ├── axolotl/
│   │   ├── SKILL.md
│   │   ├── references/
│   │   ├── templates/
│   │   ├── scripts/
│   │   └── assets/
│   └── vllm/
│       └── SKILL.md
├── devops/
│   └── deploy-k8s/
│       ├── SKILL.md
│       └── references/
├── productivity/
│   └── plan/
│       └── SKILL.md
├── .hub/
│   ├── lock.json
│   ├── quarantine/
│   └── audit.log
└── .bundled_manifest

Each skill lives in its own subdirectory, organized by category. The SKILL.md file is mandatory; other directories (references, templates, scripts, assets) are optional.

The Three Types of Skills

1. Bundled Skills

These are skills shipped with Hermes Agent. They are copied from the repo on install and synced on every hermes update. Hermes maintains a manifest (.bundled_manifest) tracking each skill's hash:

• Unmodified → automatically updated with the new version
• User-modified → never overwritten, your edits are protected

The hermes skills reset <name> command resets a modified skill, with --restore to revert to the pristine bundled version.

2. Agent-Managed Skills

This is where the magic happens. Hermes can create its own skills via the skill_manage tool — its procedural memory.

When does the agent create skills automatically?

• After completing a complex task (5+ tool calls) successfully
• When it encountered errors or dead ends and found the working path
• When the user corrected its approach
• When it discovered a non-trivial workflow worth saving

3. Hub Skills

Skills available through the Skills Hub — online registries, GitHub repos, and other community sources. Detailed in the dedicated Hub section.

The skill_manage Tool: The Agent's Procedural Memory

The skill_manage tool gives the agent the ability to manage its own skills with six actions:

• create: new skill from scratch (params: name, content, optional category)
• patch: targeted fixes, the preferred method (params: name, old_string, new_string)
• edit: major rewrites of the full SKILL.md (params: name, content)
• delete: remove a skill entirely (param: name)
• write_file: add or update a supporting file (params: name, file_path, file_content)
• remove_file: remove a supporting file (params: name, file_path)

💡 The patch action is preferred for updates — it's more token-efficient since only the changed text appears in the tool call.

Concrete example: imagine asking Hermes to deploy an app on Kubernetes. After several attempts, it finds the right command sequence. It can then create a deploy-k8s skill in the devops category. Next time you request a deployment, it loads this skill and executes the proven procedure directly.

The Skills Hub: An Ecosystem of Capabilities

The Skills Hub is Hermes' built-in marketplace. It lets you browse, search, install, and manage skills from multiple online sources.

Supported Sources

Official — optional skills maintained in the Hermes repo. Built-in trust.

hermes skills browse --source official
hermes skills install official/security/1password

skills.sh — Vercel's public skills directory. Searchable directly from Hermes.

hermes skills search react --source skills-sh
hermes skills install skills-sh/vercel-labs/json-render/json-render-react --force

Well-known — URL-based discovery via /.well-known/skills/index.json. Open web convention.

hermes skills search https://mintlify.com/docs --source well-known
hermes skills install well-known:https://mintlify.com/docs/.well-known/skills/mintlify

GitHub — direct installation from GitHub repos, with default taps (openai/skills, anthropics/skills, VoltAgent/awesome-agent-skills).

hermes skills install openai/skills/k8s
hermes skills tap add myorg/skills-repo

Direct URL — install a single SKILL.md file from any HTTPS URL.

hermes skills install https://sharethis.chat/SKILL.md
hermes skills install https://example.com/SKILL.md --name my-skill

Hermes also integrates other sources like ClawHub, LobeHub, and Claude marketplace-style repos.

Essential Hub Commands

hermes skills browse                    # Browse all Hub skills
hermes skills search kubernetes         # Search all sources
hermes skills inspect openai/skills/k8s # Preview before installing
hermes skills install openai/skills/k8s # Install with security scan
hermes skills list --source hub         # List installed Hub skills
hermes skills check                     # Check for available updates
hermes skills update                    # Update changed skills
hermes skills audit                     # Re-scan security
hermes skills uninstall k8s             # Remove a Hub skill

Trust Levels

• builtin: ships with Hermes → always trusted
• official: optional-skills from repo → built-in trust, no third-party warning
• trusted: trusted registries (openai/skills, anthropics/skills) → more permissive policy
• community: everything else (skills.sh, well-known, custom GitHub) → --force for non-critical warnings; dangerous verdicts always blocked

External Skill Directories

If you maintain skills outside Hermes — for example, a shared ~/.agents/skills/ directory used by multiple AI tools — you can tell Hermes to scan those directories too:

# ~/.hermes/config.yaml
skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

How it works:

• Read-only: external dirs are only scanned for discovery. The agent always writes to ~/.hermes/skills/
• Local precedence: if the same skill exists locally and externally, the local version wins
• Full integration: external skills appear in the index, skills_list, skill_view, and as slash commands
• Non-existent paths are silently skipped: no errors if a configured directory doesn't exist

Conditional Skill Activation

Skills can automatically show or hide based on which tools are available in the current session. Most useful for fallback skills.

metadata:
  hermes:
    fallback_for_toolsets: [web]       # Show ONLY when web is unavailable
    requires_toolsets: [terminal]      # Show ONLY when terminal is available
    fallback_for_tools: [web_search]   # Same logic for specific tools
    requires_tools: [terminal]         # Requires a specific tool

Concrete example: the built-in duckduckgo-search skill uses fallback_for_toolsets: [web]. When FIRECRAWL_API_KEY is set, the web toolset is available and the agent uses web_search — the DuckDuckGo skill stays hidden. If the API key is missing, the DuckDuckGo skill automatically appears as a fallback.

Concrete Skill Examples

The plan Skill

A bundled skill that transforms a request into a structured implementation plan instead of executing the task directly. It inspects context if needed, writes a Markdown plan, and saves it under .hermes/plans/.

/plan design a rollout for migrating our auth provider

The axolotl Skill

An MLOps category skill that guides the agent in fine-tuning LLM models with the Axolotl library. It includes configuration templates, verification scripts, and reference documentation.

/axolotl help me fine-tune Llama 3 on my dataset

An Automatically Created Skill

Imagine a workflow where Hermes deployed a React app to Vercel, encountered build errors, adjusted the configuration, and finally succeeded. It could create a deploy-vercel-react skill:

---
name: deploy-vercel-react
description: Deploy a React application to Vercel with optimized configuration
version: 1.0.0
metadata:
  hermes:
    tags: [react, vercel, deployment]
    category: devops
---
# Deploy React to Vercel

## Procedure
1. Verify that vercel.json has correct rewrites configured
2. Run npm run build locally to validate the build
3. Deploy with vercel --prod
4. Check serverless functions in the Vercel dashboard

## Common Pitfalls
- Absolute imports require baseUrl in tsconfig.json
- Environment variables must be declared in the Vercel dashboard

Skill Writing Best Practices

To make your skills effective and maintainable:

1. Clear and concise description — the description appears in skills_list(). It should help the agent quickly decide if the skill is relevant.

2. Consistent structure — follow the pattern: When to Use → Procedure → Pitfalls → Verification. This helps the agent follow instructions predictably.

3. Actionable instructions — each step should be a concrete action the agent can execute. Avoid vague formulations.

4. Document failures — the "Common Pitfalls" section may be the most valuable. It prevents the agent from reproducing past errors.

5. Version properly — update the version field with each significant change. This allows the Hub to detect updates.

6. Use complementary files — for complex workflows, place templates in templates/, scripts in scripts/, and extended documentation in references/.

7. Configure parameters — use metadata.hermes.config for values users can customize without modifying the skill itself.

Security: Scanning Third-Party Skills

Security is a cornerstone of the Skills Hub. All Hub-installed skills go through a security scanner that checks for:

• Data exfiltration
• Prompt injection
• Destructive commands
• Supply chain compromise signals
• Other potential threats

The scanner produces a verdict:

• No issues → direct installation
• Warning/Caution → user is informed, --force allows override
• Dangerous → always blocked, even with --force

hermes skills audit  # Re-scan all installed Hub skills
hermes skills inspect openai/skills/k8s  # View security metadata

The .hub/audit.log file maintains audit history, and .hub/quarantine/ isolates skills deemed dangerous.

⚠️ official skills are treated with built-in trust and don't trigger the third-party warning panel. For everything else, vigilance is warranted.

Daily Usage

Skills are used in two ways:

Via slash commands (in the CLI or any messaging platform):

/plan design a rollout for migrating our auth provider
/axolotl help me fine-tune Llama 3
/github-pr-workflow create a PR for the auth refactor

Via natural conversation:

hermes chat --toolsets skills -q "What skills do you have?"
hermes chat --toolsets skills -q "Show me the axolotl skill"

Every installed skill is automatically available as a slash command, no additional configuration needed.

Conclusion

The Hermes Agent skills system represents a paradigm shift in how AI agents interact with knowledge. Far from a simple prompt system, it's a living procedural memory that:

• Saves tokens through three-level progressive disclosure
• Enriches itself automatically when the agent learns new procedures
• Opens to the world via the Skills Hub and its multiple sources
• Protects itself through the security scanner and trust levels

Combined with persistent memory and context files, the skills system makes Hermes an agent that doesn't just execute tasks — it learns, adapts, and improves with every interaction.

To discover Hermes basics, check out our complete introduction, or explore the 68 available tools that bring these skills to life.