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 / skill-discovery-and-lifecycle

Skill discovery and lifecycle

Skills move through a controlled lifecycle from source discovery to agent use and later maintenance. Hermes combines bundled skills, official optional skills, project and external collections, plugin skills, and registry content while keeping source identity, user changes, and safety decisions separate. See the Skills system page for the wider product model.

Skill source catalog

The skill catalog turns many skill collections into one searchable view. It keeps metadata such as the skill name, description, source identity, trust level, and source-specific identifier so selection can prefer a known source without treating names as globally unique.

Source indexing and selection

The Skills Hub queries the central Hermes index first when it is available, then uses source adapters for official optional skills, GitHub, skills.sh, well-known endpoints, direct URLs, ClawHub, LobeHub, and browse.sh. Cached index data supports offline or failed-network use, while a bounded fallback search can find new registry entries that the central index has not yet recorded. Results are merged by identifier and ordered by trust before the user selects a skill.

Source groupRole in the lifecycle
Bundled skillsShipped with Hermes and seeded into a profile for immediate use.
Official optional skillsMaintained with Hermes but not active by default. They become active after installation or repair.
Project and external collectionsLocal collections that can supplement or override profile skills under configured trust and precedence rules.
Plugin skillsRead-only skills supplied by an enabled plugin and addressed through its namespace.
Registry skillsSkills fetched from the Skills Hub sources and treated according to their source trust.

References: tools/skills_hub_search.py• L27-113 tools/skills_hub_search.py• L132-173 tools/skills_hub_models.py• L26-48 tools/skills_hub_official.py• L34-42

Source identity and trust

A source-specific identifier remains attached to a skill from search through update. This prevents an update or reinstall from silently replacing one registry’s skill with a same-named skill from another registry. Trust labels guide the validation policy: bundled content is builtin, selected maintained repositories are trusted, and general registry content is community content.

References: tools/skills_hub_install.py• L305-365 tools/skills_guard.py• L26-44 tools/skills_hub_models.py• L113-124

Skill intake and installation

Installation converts a selected source record into an active skill package. Hermes fetches the package, stages it outside the active collection, validates it, and only then places it in the profile’s skill tree with provenance records.

Bundle staging and validation

Hermes treats downloaded content as untrusted until it passes the intake boundary. Path checks keep package files and install targets inside the skill collection, while the scanner checks structure, scripts, text, and other files for high-risk behavior. The result combines the scan verdict with source trust. Dangerous findings in trusted or community content block installation even when the user asks to force the operation.

The package must contain a usable SKILL.md. Linked support files can travel with it, but unsafe paths, escaping links, invalid names, and unsafe package members stop the install. A confirmation step remains for normal interactive installs so the user can review source and scan information before activation.

References: tools/skills_hub_install.py• L63-99 tools/skills_hub_install.py• L181-243 tools/skills_guard.py• L910-1001 tools/skills_hub_models.py• L208-250

Installation ownership and provenance

After validation, Hermes moves the staged package into its chosen category or flat profile path. A hub lock records the source, identifier, trust, scan verdict, content hash, install path, and file list. An audit record captures install and removal actions. This ownership record lets Hermes distinguish a hub-managed skill from a bundled skill or a user-created skill during later operations.

References: tools/skills_hub_install.py• L181-243 tools/skills_hub.py• L374-450 tools/skills_hub.py• L503-515

Agent skill availability

The runtime presents skills through a shared catalog and loads full content only when the agent requests it. This separates routing information from long instructions and lets the agent inspect a skill without placing every skill body into the conversation context.

Search roots and precedence

The runtime searches trusted project collections first, then the active profile, an optional creation directory, and configured external directories. A higher-priority copy can shadow a lower-priority copy. Different skills with the same name at the same priority remain ambiguous instead of being chosen by accident; identical copies can resolve to one winner.

Project collections need explicit trust. A trusted project skill still passes a scan gate, and a dangerous result is quarantined from the index, list, view, and slash-command paths. This protects an already trusted project after its source changes.

References: agent/skill_utils.py• L402-424 agent/skill_utils.py• L452-508 agent/skill_utils.py• L511-665

Catalog filtering and loading

The catalog reads the skill name and short description first. Platform, runtime environment, required application, and disabled-skill rules control whether a skill is offered. An explicit load still checks hard platform support and safety gates. The essential hermes-agent skill cannot be disabled because the agent depends on it.

When the agent loads a skill, Hermes returns its instructions and identifies linked references, templates, assets, or scripts for later requests. Required environment values and credential files produce a readiness state rather than silently claiming that the skill is ready. Declared tool dependencies are also checked at load time; a failed dependency leaves the skill content available with a setup note.

References: tools/skills_tool.py• L229-282 tools/skills_tool.py• L485-544 tools/skills_tool.py• L633-734 agent/skill_utils.py• L167-196 agent/skill_utils.py• L276-293

Plugin skill availability

Plugins provide skills through a separate namespaced path. These skills are listed with the active catalog but are not copied into the profile’s local skill directory. The namespace prevents one plugin from replacing another plugin’s instructions and lets disabling the plugin remove its skills from the agent’s available set.

References: hermes_cli/plugins_content.py• L31-67 tools/skills_tool.py• L304-397

Bundled skill synchronization

Bundled synchronization keeps the profile’s local copy aligned with the version shipped by Hermes without overwriting user work. The sync process records an origin hash for each seeded skill and uses that record to decide whether a later update is safe.

Seed and update rules

New bundled skills are copied into the profile and added to the manifest. An unchanged skill is skipped. A changed upstream skill replaces the local copy only when the local copy still matches its recorded origin. If the user edited the copy, Hermes keeps it and reports it as user-modified. A user deletion is respected and is not silently re-added.

The sync also handles upstream moves and removals. A pristine skill can move to a new category while a modified copy stays in place. A removed skill leaves the manifest only after no active or archived copy remains, so existing copies retain their built-in provenance.

References: tools/skills_sync.py• L1-7 tools/skills_sync.py• L172-224 tools/skills_sync.py• L310-381 tools/skills_sync.py• L398-459

Profile opt-out and optional provenance

Profiles can opt out of bundled seeding with a marker. An opted-out profile receives only essential skills during sync, and explicit removal deletes only pristine bundled copies. Official optional skills follow a different path: they are discoverable but not seeded by default, and exact byte matches can later receive official hub provenance. Repair can restore missing or changed optional copies while moving existing copies into a restore backup.

References: tools/skills_sync.py• L70-82 tools/skills_sync.py• L398-459 tools/skills_sync_bundled_ops.py• L205-260 tools/skills_sync_optional.py• L128-164 tools/skills_sync_optional.py• L193-235

Skill maintenance

Maintenance keeps installed skills attributable and current after their first activation. Hermes separates upstream update checks, bundled synchronization, user edits, and removal so one lifecycle owner does not destroy another owner’s content.

Upstream update checks

Hub-managed skills are checked through the adapter recorded in their lock entry. If the source exposes a cheap revision, Hermes can avoid downloading an unchanged package. Otherwise it fetches the package and compares its canonical content hash with the installed hash. Missing sources and missing install paths become visible states rather than being treated as successful updates.

User edits are protected during updates by default. An explicit force action is the user’s choice to replace that content; bundled skills use their own reset and restore flow instead of hub update ownership.

References: tools/skills_hub_install.py• L305-365 hermes_cli/skills_hub.py• L1080-1160 tools/skills_sync_bundled_ops.py• L19-60

Removal and repair boundaries

Only skills recorded as hub-installed can be removed by hub uninstall. The recorded install path is checked again before deletion, and bundled or local skills are refused. Official optional repair can replace content because it first backs up the active copy and then re-establishes the official source relationship.

References: tools/skills_hub_install.py• L246-265 tools/skills_hub_models.py• L239-250 tools/skills_sync_optional.py• L116-164

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the source identifier, adapter selection, lock entry, update check, and audit record aligned. A mismatch can make a skill appear installed but prevent a safe update.
  • Keep bundled origin hashes and destination paths aligned when changing category layout or sync rules. Otherwise user edits can be overwritten or moved copies can be treated as deleted.
  • Keep search-root precedence identical for catalog listing, explicit loading, prompt exposure, and slash commands. A different order can show one skill and load another.
  • Keep trust labels aligned with scan policy. A source that becomes trusted must still use the intended dangerous-verdict rule.
  • Keep optional-skill catalog paths, live-repository fallbacks, and provenance backfill rules aligned. A catalog entry can otherwise install content that maintenance cannot identify.

Important failure modes

TriggerConsequenceGuard
Two different skills share a name at the same precedence tierHermes refuses to guess and the skill is not loadable by that nameSame-tier ambiguity detection and exact relative-path names
A trusted project skill changes to dangerous contentThe skill disappears from the catalog and cannot loadContent-hash scan cache and project quarantine gate
A community or trusted bundle has a dangerous scan verdictInstallation stops and the staged files are discardedTrust-aware scan policy; force does not override the hard block
A bundled skill is edited locally before an upstream updateThe local copy stays unchanged and the update is reported as skippedManifest origin hash comparison
A hub lock points outside the active skills directoryUninstall or update could remove unrelated dataInstall-path validation and component-by-component containment checks
The central index is stale or unavailableSearch can miss a newly published skill or use older metadataStale-cache fallback and bounded registry fallback search

Key files

FileWhy to read it
tools/skills_hub_search.pyCentral index loading, source routing, parallel search, fallback, and trust-ranked merge.
tools/skills_hub_official.pyBundled optional-skill discovery, live-repository fallback, and official provenance meaning.
tools/skills_hub_install.pyStaging, installation ownership, uninstall boundaries, and upstream update checks.
tools/skills_guard.pyContent scan results and the trust-aware install decision.
agent/skill_utils.pySearch-root precedence, project trust, quarantine, filtering, and skill-name resolution.
tools/skills_tool.pyThe agent-facing catalog and progressive skill loading behavior.
tools/skills_sync.pyManifest-based synchronization of bundled skills and profile opt-out behavior.
tools/skills_sync_optional.pyOfficial optional-skill provenance backfill and repair.