Introducing a new way to review your PRs.

Read the announcement

nousresearch / hermes-agent

The agent that grows with you

View on GitHub

38 documents · Updated Nov 20, 2026

docs / skills-system

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:

SourcePurposeAvailability model
BundledCore workflows that ship with HermesSeeded into a profile and maintained across updates
Official optionalLarger or specialized workflows shipped with HermesInstalled when the user chooses them
Skills HubSkills from official catalogs, registries, GitHub, and URLsDiscovered, checked, scanned, and installed by the user
External and project-localShared or repository-specific workflowsScanned when configured; project skills require trust
Plugin-providedSkills owned by an enabled pluginExposed 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

TriggerConsequenceGuard
A community skill has a dangerous scan resultThe skill is not installedThe install policy blocks dangerous community content, including with --force
Two different same-tier skills share a nameThe name is ambiguous and is not auto-loadedThe resolver requires an exact relative path or a rename
A user edits a bundled skillA product update keeps the edited copy and skips the updateThe bundled manifest compares the copy with its recorded origin hash
A project skill changes after trust is grantedA dangerous skill stays out of the catalog and refuses to loadProject content is scanned by hash and quarantined on a dangerous verdict
A loaded skill lacks required setupThe skill loads with reduced readiness and reports what is missingLoad-time readiness checks report missing environment values or credential files

Key files

FileWhy to read it
agent/skill_utils.pyDefines skill roots, precedence, platform and project trust rules, and catalog resolution.
agent/prompt_builder.pyShows how the runtime creates the compact skill index for the agent.
tools/skills_tool.pyDefines the progressive-disclosure interface for listing and viewing skills.
agent/skill_commands.pyConnects resolved skills to slash commands, stacked invocations, and session preload.
tools/skills_sync.pyDefines how bundled content reaches profiles and how user ownership survives updates.
hermes_cli/skills_hub.pyDefines the user-facing browse, inspect, install, and update workflow for Hub content.
tools/skills_hub_install.pyDefines the staged install boundary and ownership record for Hub-installed packages.
tools/skills_guard.pyDefines 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.