The Skills system: the agent that learns

The Skills System: The Agent that Learns

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

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

The Essentials

• A skill is an on-demand loadable knowledge document that only consumes tokens when the agent needs it.
• The system relies on a three-level progressive discovery to minimize token consumption.
• Hermes can create its own skills automatically after a complex task, thus building its procedural memory.
• The Skills Hub allows you to install skills from multiple sources (official, GitHub, direct URL).
• A security scanner protects the user by blocking dangerous skills.

What is a Skill?

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

The skill follows the agentskills.io open standard, which means it is interoperable with other AI agents and skill ecosystems.

💡 Analogy: think of skills like browser extensions. They are not all active at the same time, 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). The frontmatter contains the unique identifier (name), a description for indexing, the version number, the supported platforms, as well as specific Hermes metadata: search tags, category (devops, mlops, productivity…), activation conditions (fallback/requires), and configurable parameters. The Markdown body generally follows the recommended structure: trigger conditions, step-by-step procedure, common pitfalls to avoid, and final verification.

The key frontmatter fields:

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

Progressive Disclosure

One of the smartest 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 content of the skill (frontmatter + body). This is the level 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 that include supplementary files.

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

The ~/.hermes/skills/ directory

All skills reside in ~/.hermes/skills/ — the main directory and source of truth. Each skill lives in its own subdirectory, organized by category (mlops, devops, productivity, etc.). The SKILL.md file is mandatory; other directories (references, templates, scripts, assets) are optional and allow storing supplementary files. A .hub/ subdirectory contains the Hub management files: version locking (lock.json), quarantine of dangerous skills, and the audit log.

The three types of skills

1. Bundled Skills

These are the skills shipped with Hermes Agent. They are copied from the repository during installation and synchronized on every hermes update. Hermes maintains a manifest (.bundled_manifest) that tracks the footprint of each skill:

• Unmodified → automatically updated with the new version
• Modified by the user → never overwritten, your edits are protected

The command hermes skills reset <name> allows you to reset a modified skill, with the --restore option to revert to the clean bundled version.

2. Agent-Managed Skills

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

When does the agent create a skill automatically?

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

3. Hub Skills

Skills available via the Skills Hub — online registries, GitHub repositories, and other community sources. We cover the Hub in a dedicated 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: create a 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 complete SKILL.md (params: name, content)
• delete: delete a skill entirely (param: name)
• write_file: add or modify a support file (params: name, file_path, file_content)
• remove_file: delete a support file (params: name, file_path)

💡 The patch action is preferred for updates — it saves tokens because only the modified text appears in the tool call.

Concrete example: imagine you ask Hermes to deploy an application on Kubernetes. After several attempts, it finds the right sequence of commands. It can then create a deploy-k8s`` skill in thedevops` category. The next time you ask it for a deployment, it will load this skill and execute the proven procedure directly.

The Skills Hub: a skills ecosystem

The Skills Hub is Hermes' integrated marketplace. It allows you to browse, search, install, and manage skills from multiple online sources.

Supported sources

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

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

Well-known — URL-based discovery via /.well-known/skills/index.json. Open web convention allowing any site to expose skills.

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

Direct URL — installation of a single SKILL.md file from any working HTTPS URL.

Hermes also integrates other sources such as ClawHub, LobeHub, and Claude marketplace-type repositories.

Essential Hub commands

hermes skills browse                    # Browse all Hub skills
hermes skills search kubernetes         # Search across 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 modified skills
hermes skills audit                     # Re-scan security
hermes skills uninstall k8s             # Remove a Hub skill

Trust levels

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

External skill directories

If you maintain skills outside of Hermes — for example, a shared ~/.agents/skills/ directory used by multiple AI tools — you can tell Hermes to scan these additional directories via the skills.external_dirs key in the ~/.hermes/config.yaml file. Paths support environment variables.

Operating rules:

• Read-only: external directories are only scanned for discovery. The agent always writes to ~/.hermes/skills/
• Local priority: if the same skill exists locally and externally, the local version takes precedence
• Full integration: external skills appear in the index, skills_list, skill_view, and as slash commands
• Non-existent paths ignored: no error if a configured directory does not exist

Conditional skill activation

Skills can automatically show or hide depending on the tools available in the session. This is particularly useful for fallback skills. The fallback_for_toolsets, requires_toolsets, fallback_for_tools, and requires_tools keys in the Hermes metadata allow you to define these conditions.

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

Concrete examples of skills

The plan skill

Built-in skill that transforms a request into a structured implementation plan instead of executing the task directly. It inspects the context if necessary, writes a plan in Markdown, and saves it under .hermes/plans/. Used via the slash command /plan.

The axolotl skill

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 accessible via level 2 of progressive discovery. Used via the slash command /axolotl.

An automatically created skill

Imagine a workflow where Hermes has deployed a React application on Vercel, encountered build errors, adjusted the configuration, and finally succeeded. It can create a deploy-vercel-react skill containing the validated procedure: checking the vercel.json file, local build, production deployment, and verification of serverless functions, as well as the common pitfalls encountered (absolute imports, environment variables).

Best practices for writing skills

To make your skills effective and maintainable:

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

2. Consistent structure — follow the model: When to use it → Procedure → Pitfalls → Verification. This structure helps the agent follow the instructions in a predictable way.

3. Actionable instructions — each step must be a concrete action that the agent can execute. Avoid vague phrasing.

4. Document failures — the "Common pitfalls" section is perhaps the most valuable. It prevents the agent from repeating past mistakes.

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

6. Use supplementary 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 that the user can customize without modifying the skill itself.

Security: scanning third-party skills

Security is a cornerstone of the Skills Hub. All skills installed from the Hub 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 → the user is informed, --force allows bypassing
• Dangerous → always blocked, even with --force

The hermes skills audit and hermes skills inspect commands allow you to re-scan installed skills and view a skill's security metadata, respectively. The .hub/audit.log file keeps the audit history, and .hub/quarantine/ isolates skills deemed dangerous. To delve deeper into this topic, check out our article on Security and permissions in Hermes Agent.

⚠️ official skills are treated with built-in trust and do not trigger the third-party warning panel. For everything else, caution is advised.

Daily use

Skills are used in two ways:

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

/plan design a migration to a new 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"

Each installed skill is automatically available as a slash command, without any additional configuration. To understand how skills interact with the conversation context, see Hermes Agent: sessions and conversation context.

Common errors

• Skill not appearing in the list: check that the SKILL.md file is indeed present at the root of the skill's subdirectory and that the YAML frontmatter is valid. A syntax error in the frontmatter makes the skill invisible.
• Skill hidden when it should be available: check the activation conditions (requires_toolsets, requires_tools). If the required tools are not in the session, the skill remains hidden.
• Modified skill overwritten after hermes update: this should not happen — the manifest protects local modifications. If it does happen, the skill was probably not tracked in the manifest (skill installed manually outside the Hub).
• --force not enough to install a skill: the security scanner's verdict is probably dangerous. This verdict is intentionally non-bypassable to protect the user.
• Conflict between a local skill and an external skill: the local version in ~/.hermes/skills/ always takes precedence. If you want to use the external version, rename or delete the local version.

FAQ

Does a skill consume tokens even when it is not used?
No. The progressive discovery system ensures that only the name and description (~3,000 tokens for all skills) are loaded. The full content is only loaded at level 1, exactly when the agent decides to use the skill.

Can I share a skill automatically created by the agent?
Yes. The skills in ~/.hermes/skills/ are simple files. You can copy them to a GitHub repository and install them on another machine via hermes skills install or publish them on the Skills Hub.

How do I revert to the official version of a modified built-in skill?
Use hermes skills reset <nom> --restore. This command replaces your modified version with the clean bundled version from the Hermes repository.

Can external skills be modified by the agent?
No. External directories are read-only. If the agent wants to improve an external skill, it will create a local copy in ~/.hermes/skills/ via skill_manage.

Is it possible to disable the security scanner?
No. The scanner is a non-disableable security mechanism. Only the "Warning/Caution" verdict can be bypassed with --force. The "Dangerous" verdict always blocks installation.

Recommended tools

• skill_manage : the agent's internal tool to create, modify, and delete its own skills. It is the core of procedural memory.
• skills_list() : lightweight discovery function allowing the agent to browse available skills without loading their full content.
• skill_view() : function for loading a skill's content, with support for loading complementary files (level 2).
• hermes skills : the CLI command to manage the Skills Hub (browse, search, install, audit, update, uninstall).
• Extensions and plugins : to extend Hermes's capabilities beyond skills, check out our article on Hermes Agent Extensions and Plugins.

Conclusion

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

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

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

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