Skills system
The Skills system packages reusable procedures and reference material as on-demand guidance for Hermes agents. It brings built-in, optional, user, project, plugin, and external skills into the same agent workflow while keeping large content out of the model context until it is useful.
Skill packages
A skill is a named package centered on SKILL.md. It gives the agent task guidance and can point to supporting references, templates, assets, or scripts that the agent reads only when needed. This package model lets Hermes share a repeatable method without turning every conversation into a large fixed prompt.
The system treats a skill as procedural knowledge. It is different from memory, which holds small facts that are useful in many sessions. Skills instead preserve a way to complete a class of task and can be changed as the workflow improves.
References: tools/skills_tool.py• L1-5 website/…/skills.md• L173-193 website/…/skills.md• L607-645
Skill sources
Hermes combines several skill sources into one catalog. The profile-local skills directory is the main working copy. Bundled skills seed that directory from the product package, while optional skills remain shipped with Hermes but require an explicit install before they become active.
Other sources extend the same catalog for different ownership needs:
| Source | Purpose | Availability model |
|---|---|---|
| Bundled | Core workflows that ship with Hermes | Seeded into a profile and maintained across updates |
| Official optional | Larger or specialized workflows shipped with Hermes | Installed when the user chooses them |
| Skills Hub | Skills from official catalogs, registries, GitHub, and URLs | Discovered, checked, scanned, and installed by the user |
| External and project-local | Shared or repository-specific workflows | Scanned when configured; project skills require trust |
| Plugin-provided | Skills owned by an enabled plugin | Exposed with a plugin-qualified name |
The source does not change how the agent uses the skill. It changes who owns the content and which trust, update, and precedence rules apply. See Skill discovery and lifecycle for the source index, install path, validation, and maintenance flow.
References: tools/skills_sync.py• L398-459 tools/skills_sync_optional.py• L91-113 website/…/skills.md• L714-755 agent/skill_utils.py• L402-424
Skill availability
Hermes resolves skills through one ordered view so the system prompt, tool calls, slash commands, preload options, and scheduled work agree on what a name means. Trusted project skills have the highest precedence, followed by the profile-local tree, the configured creation directory, and external directories.
When two different skills at the same precedence level use the same name, Hermes does not guess. It requires the exact relative path or a rename. A higher-precedence copy can shadow a lower-precedence copy, which lets a repository provide its own workflow without changing the global profile.
Platform, environment, application, tool, and session conditions can hide a skill from the offer list. An explicit load still follows the skill's platform and safety rules. Project skills add a separate trust decision and a scan gate because repository content can change after a repository is trusted.
References: agent/skill_utils.py• L402-424 agent/skill_utils.py• L473-508 agent/skill_utils.py• L511-665 agent/prompt_builder.py• L1408-1442
Runtime connection
The runtime uses progressive disclosure to connect skill content to the agent. It places a compact name and description index in the system prompt, then loads the full SKILL.md only when the agent selects a relevant skill. Supporting files are loaded as separate references rather than being added to every turn.
The main runtime path is:
flowchart LR
S[Skill sources] --> I[Resolved skill index]
I --> P[Compact system-prompt index]
P --> V[skill_view or slash command]
V --> C[Skill content in the turn]
C --> R[Optional references, templates, assets, or scripts]
R --> O[Agent result]
Slash commands and skill bundles add the selected content as turn input. They do not rebuild the conversation's stable system prompt. This keeps prompt caching useful while still allowing a newly installed, changed, or removed skill to affect later work.
References: agent/prompt_builder.py• L1240-1273 agent/prompt_builder.py• L1340-1367 tools/skills_tool.py• L229-282 tools/skills_tool.py• L633-734 agent/skill_commands.py• L743-801
User workflows
The system supports both direct user selection and agent-led skill use. Users can list or search skills, invoke a skill by slash command, stack several skills for one task, or use a bundle as a named group of related skills. The same central dispatch supports the CLI, TUI, dashboard chat, and gateway platforms.
Users can also grow the skill library. /learn turns a source or a demonstrated workflow into reusable guidance, while skill_manage lets the agent create, revise, or remove a skill. Write approval and skill locks can require review or protect a specific skill before changes reach the active tree.
Skill settings and required environment values connect package guidance to real tools. Hermes reports missing setup when a skill loads and passes declared values to the execution tools when allowed. A skill can therefore describe a workflow without forcing secrets or tool setup into every session.
References: website/…/skills.md• L74-116 website/…/skills.md• L118-171 website/…/skills.md• L522-605 website/…/skills.md• L607-712 tools/skills_tool.py• L485-544
Content safety
Skill content is executable guidance from the agent's point of view, so Hermes separates discovery from trust and installation. Hub content is staged, scanned, and recorded with source and content information before it becomes an installed skill. Official built-in content has a higher trust level than community content.
The safety boundary continues after installation. Project skills are scanned before they enter the catalog, and dangerous content is quarantined. Community findings can block installation or require an explicit override, but a dangerous verdict remains blocked. These rules reduce the chance that a skill can alter agent behavior or expose user data without review.
References: tools/skills_hub.py• L839-885 tools/skills_hub.py• L905-999 tools/skills_guard.py• L1-8 tools/skills_guard.py• L35-42 agent/skill_utils.py• L615-665
Update ownership
Bundled and installed skills have different update owners. Bundled synchronization uses an origin record so Hermes can update an untouched copy while preserving a user-edited copy. A deleted bundled skill is not silently restored, and an upstream move can relocate an unchanged copy without moving user work.
Hub-installed skills use their recorded source and lock data to check for upstream changes. The hub can update or uninstall content it owns, while the bundled updater does not overwrite a hub-owned path. This ownership split keeps product updates, user edits, and third-party installs from silently replacing one another.
References: tools/skills_sync.py• L1-7 tools/skills_sync.py• L358-381 tools/skills_sync.py• L424-459 tools/skills_hub_install.py• L181-243 tools/skills_hub_install.py• L246-260
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the source directory, generated catalog pages, and the install identifiers aligned when adding or renaming a shipped skill.
- Preserve one precedence order across the system-prompt index,
skills_list,skill_view, slash dispatch, preload, and scheduled work. - When changing frontmatter names or conditions, check both discovery visibility and explicit loading behavior.
- When changing bundled or Hub ownership, keep origin hashes, lock entries, update checks, uninstall paths, and shadow handling consistent.
- Keep skill activation in turn content or tool results; do not rebuild a live conversation's stable system prompt.
- If a skill declares setup values, keep readiness reporting and execution-tool environment passing aligned.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A community skill has a dangerous scan result | The skill is not installed | The install policy blocks dangerous community content, including with --force |
| Two different same-tier skills share a name | The name is ambiguous and is not auto-loaded | The resolver requires an exact relative path or a rename |
| A user edits a bundled skill | A product update keeps the edited copy and skips the update | The bundled manifest compares the copy with its recorded origin hash |
| A project skill changes after trust is granted | A dangerous skill stays out of the catalog and refuses to load | Project content is scanned by hash and quarantined on a dangerous verdict |
| A loaded skill lacks required setup | The skill loads with reduced readiness and reports what is missing | Load-time readiness checks report missing environment values or credential files |
Key files
| File | Why to read it |
|---|---|
| agent/skill_utils.py | Defines skill roots, precedence, platform and project trust rules, and catalog resolution. |
| agent/prompt_builder.py | Shows how the runtime creates the compact skill index for the agent. |
| tools/skills_tool.py | Defines the progressive-disclosure interface for listing and viewing skills. |
| agent/skill_commands.py | Connects resolved skills to slash commands, stacked invocations, and session preload. |
| tools/skills_sync.py | Defines how bundled content reaches profiles and how user ownership survives updates. |
| hermes_cli/skills_hub.py | Defines the user-facing browse, inspect, install, and update workflow for Hub content. |
| tools/skills_hub_install.py | Defines the staged install boundary and ownership record for Hub-installed packages. |
| tools/skills_guard.py | Defines trust-aware validation for external skill content. |
skills/ | Product-owned bundled skill packages that provide the default workflow library. |
optional-skills/ | Product-shipped optional packages that users can install when needed. |