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 group | Role in the lifecycle |
|---|---|
| Bundled skills | Shipped with Hermes and seeded into a profile for immediate use. |
| Official optional skills | Maintained with Hermes but not active by default. They become active after installation or repair. |
| Project and external collections | Local collections that can supplement or override profile skills under configured trust and precedence rules. |
| Plugin skills | Read-only skills supplied by an enabled plugin and addressed through its namespace. |
| Registry skills | Skills 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
| Trigger | Consequence | Guard |
|---|---|---|
| Two different skills share a name at the same precedence tier | Hermes refuses to guess and the skill is not loadable by that name | Same-tier ambiguity detection and exact relative-path names |
| A trusted project skill changes to dangerous content | The skill disappears from the catalog and cannot load | Content-hash scan cache and project quarantine gate |
| A community or trusted bundle has a dangerous scan verdict | Installation stops and the staged files are discarded | Trust-aware scan policy; force does not override the hard block |
| A bundled skill is edited locally before an upstream update | The local copy stays unchanged and the update is reported as skipped | Manifest origin hash comparison |
| A hub lock points outside the active skills directory | Uninstall or update could remove unrelated data | Install-path validation and component-by-component containment checks |
| The central index is stale or unavailable | Search can miss a newly published skill or use older metadata | Stale-cache fallback and bounded registry fallback search |
Key files
| File | Why to read it |
|---|---|
| tools/skills_hub_search.py | Central index loading, source routing, parallel search, fallback, and trust-ranked merge. |
| tools/skills_hub_official.py | Bundled optional-skill discovery, live-repository fallback, and official provenance meaning. |
| tools/skills_hub_install.py | Staging, installation ownership, uninstall boundaries, and upstream update checks. |
| tools/skills_guard.py | Content scan results and the trust-aware install decision. |
| agent/skill_utils.py | Search-root precedence, project trust, quarantine, filtering, and skill-name resolution. |
| tools/skills_tool.py | The agent-facing catalog and progressive skill loading behavior. |
| tools/skills_sync.py | Manifest-based synchronization of bundled skills and profile opt-out behavior. |
| tools/skills_sync_optional.py | Official optional-skill provenance backfill and repair. |