Why is an installed Hermes skill missing from the list?
In Hermes v0.23.1, a skill whose files are on disk stays out of the list for one of six reasons:
- it is in a folder or profile Hermes doesn’t scan;
- its own frontmatter limits it to another operating system, environment or app;
- it is disabled, for everyone or for one chat platform;
- the curator has archived it;
- another skill with the same name hides it;
- it is listed but has no slash command.
Missing API keys don’t hide a skill. To find out which reason applies, ask Hermes to load the skill by its exact name. The reply usually names the cause.
This guide follows Hermes v0.23.1, commit 3b42157, checked on 14 November 2026 against the official source and documentation. We did not reproduce each case on a running Hermes.
Which list is missing it?
Hermes has several lists, and they don’t all apply the same filters. Note where you looked before changing anything.
| Where you looked | What it leaves out |
|---|---|
hermes skills list in a terminal |
Skills for another OS, environment or missing app, and shadowed copies. Disabled skills still appear, marked disabled. |
| The skills the agent offers in chat (its skill index) | Everything above, plus disabled skills, plus skills whose tool conditions aren’t met in this session. |
/skill-name slash commands |
Hidden and disabled skills, plus skills whose command name is already taken by a built-in or by another skill (git_helper and git-helper become the same command). The map rescans when the skill folders change; /reload-skills forces it. |
Telegram’s / menu |
Anything beyond the menu cap, which is 60 commands by default, plus skills disabled for Telegram and skills in skills.create_dir. Typed commands still work, using Telegram-safe names: hyphens become underscores, at most 32 characters. |
So a skill can be in hermes skills list while the agent never offers it. When the terminal list shows it as enabled, look at tool conditions, the platform you’re chatting on, and whether the conversation started before you added it.
Ask for it by name
Asking Hermes to load a skill by name bypasses most offer-time filters, so the result is a useful test. The v0.23.1 loader returns these messages:
| Reply | Meaning | Next check |
|---|---|---|
Skill 'NAME' not found. |
No scanned folder holds a SKILL.md with that name. |
Folder, profile, archive and declared name, below. |
Skill 'NAME' is not supported on this platform. |
Its platforms: list excludes this operating system. |
Platform limits, below. |
Skill 'NAME' is disabled. |
It is on a disabled list. | Disabled skills, below. |
Ambiguous skill name ... use one of ... |
Two different skills in one folder tier share the name. | Load one by the path shown, or rename one. |
Project skill 'NAME' is quarantined |
A repository skill failed the security scan. | Read the skill in the repo before trusting it. |
If the skill loads normally but the agent never offered it, the cause is an offer-time filter: environment, required app, tool conditions or chat platform.
It’s in a folder or profile Hermes doesn’t scan
Hermes scans these places, in this order of precedence:
- the project’s
.hermes/skills/or.agents/skills/, only in a repository you trusted; - the profile’s
~/.hermes/skills/; skills.create_dir, if you set it;- each folder in
skills.external_dirs.
Every profile is a separate Hermes home with its own skills. A skill installed in one profile is absent from another. Check the active profile, or run hermes -p NAME skills list for a named one.
Things that commonly put a skill out of reach:
- A missing external directory is skipped silently. A typo in
external_dirsproduces no error. Check the path exists on the computer where Hermes runs. - Untrusted project skills don’t load. The first run in such a repository prints a notice. Run
hermes skills trustinside the repo if you have read its skills. Settingskills.project_discovery: falseturns project skills off entirely. - Nested in another skill’s support folder. A
SKILL.mdinside another skill’sreferences/,templates/,assets/orscripts/folder is treated as a support file, not a skill. - Inside an excluded folder. Hermes skips
.git,.github,.hub,.archive,node_modules,venv,.venv,site-packages,__pycache__and similar folders. - The file can’t be read. A permission error or an undecodable file is skipped without a visible message.
The skill’s name comes from its name: field, not its folder. A folder called deploy-k8s whose frontmatter says name: kube-deploy appears as kube-deploy. Without a name: field, Hermes uses the folder name.
Its frontmatter limits where it appears
A skill can declare where it belongs. Three of these settings are about the host:
| Field | Effect in v0.23.1 |
|---|---|
platforms: [macos] |
Hidden on Linux and Windows, and it refuses to load there. A hosted Hermes normally runs on Linux. |
environments: (such as docker, kanban, s6) |
Hidden from the index, lists and slash commands when the environment isn’t detected. An explicit load still works. Unknown tags count as a match. |
requires_apps: |
Hidden unless every named app is registered and available on this host. An unknown app name hides the skill. |
Two more groups, under metadata.hermes, depend on the session:
- Tool conditions.
requires_toolsandrequires_toolsetshide the skill when those tools are off.fallback_for_toolsandfallback_for_toolsetshide it when those tools are on. A fallback search skill is meant to disappear while the web toolset works. session_platforms. This limits the skill to particular chat platforms, such as Telegram.
These tool and session checks apply to the agent’s skill index, not to hermes skills list.
If you wrote the skill, read its frontmatter before anything else. A copied platforms: [macos] line is enough to hide it on a Linux server.
It’s disabled, everywhere or on one platform
skills.disabled in config.yaml turns a skill off everywhere. skills.platform_disabled turns it off for one platform, such as Telegram, and leaves it on elsewhere. Use hermes skills config to change either list for the active profile.
Two details matter:
- A skill can be enabled in the terminal and disabled on Telegram. The terminal list then says
enabled, while the Telegram chat can’t load it. - A single name works as well as a list: v0.23.1 reads
skills.disabled: deployas a one-item list, including when it was written withhermes config set.
The essential hermes-agent skill can’t be disabled.
The curator archived it
The curator moves long-unused skills out of the active tree. By default it runs when at least 7 days have passed since its last run and Hermes has been idle for 2 hours. An eligible skill unused for 30 days moves to ~/.hermes/skills/.archive/. Hermes doesn’t scan that folder, so the skill reports not found.
The curator manages fewer skills than people expect:
- Included: skills created by Hermes’s background self-improvement review.
- Opt-in only: unused bundled built-ins, when
curator.prune_builtins: trueis set. - Not touched unless you hand them over with
hermes curator adopt: skills you wrote by hand, skills the agent created at your request (including/learn) and skills from external directories. Hub-installed skills are never touched.
A skill listed in any cron job’s skills: is also protected while that reference remains, even if the job is paused.
To check and recover:
hermes curator status
hermes curator list-archived
hermes curator restore SKILL_NAME
hermes curator pin SKILL_NAME
Replace SKILL_NAME with the skill’s name. A restore refuses if a skill with the same name now occupies the active folder, or a hub skill (or, unless built-in pruning is on, a bundled skill) with that name was installed in the meantime. The curator never deletes skills by itself; archiving is its strongest action.
Another skill with the same name wins
When two skills in different tiers share a name, the higher tier wins on every surface: project, then local, then create_dir, then external. The hidden copy is logged as shadowed. If you edit an external skill and see no change, check for a local skill with the same name.
Inside a single tier, Hermes won’t guess between two different skills with the same name. Both are listed under their relative paths, and loading the bare name fails with the ambiguity message above. Rename one skill, or load it by its path.
It’s listed but has no slash command
- A built-in already owns the name. A skill called
modelorstatusloads normally but gets no/modelor/statusshortcut.hermes skills listnotes this beside it. - Telegram’s menu is full. The menu shows 60 commands by default (up to 100 if configured). A skill missing from the menu still works when you type its command. To give it a slot, add it to
platforms.telegram.extra.command_menu.priority. - You added it during a conversation. Your next message tells the agent about the new skill. The full skill index refreshes at the next compaction. Slash commands rescan when the skill folders change, and
/reload-skillsforces that immediately.
Missing credentials don’t hide it
A skill can declare required_environment_variables. Hermes still lists and loads it. In the local CLI it asks for a missing value when the skill loads. On messaging platforms it tells you to use hermes setup or ~/.hermes/.env instead of asking in chat.
A skill that appears but fails partway is a different problem from a missing skill. Where to put a secret your Hermes needs covers storing the value. Skill, tool or plugin helps when what’s missing is really a tool or plugin.
Finding it on a hosted Hermes
The checks are the same wherever Hermes runs. What changes is how you reach it. On Vavio, open Hermes and ask it to load the skill by name. The reply carries the same messages as the loader table above. If you used a terminal to install the skill, confirm you used the profile your hosted Hermes runs.
Vavio supplies a managed Hermes computer for $14.99 per month, with model usage billed separately. Its MCP server and CLI handle the computer, the model choice, checks and gateway restarts. They don’t install, enable or restore skills today; those remain Hermes’s own settings. See the current hosting offer, or check whether your hosted Hermes is working if the problem is bigger than one skill.
Sources
- Skills guide, platform limits, conditional activation and secure setup, checked 14 November 2026
- External directories, project skills, precedence and duplicate names, checked 14 November 2026
- Skill catalog scan and its visibility filters, checked 14 November 2026
- Messages returned when a skill is loaded by name, checked 14 November 2026
- Excluded folders, OS, environment, app and disabled-list checks, checked 14 November 2026
- What `hermes skills list` shows, checked 14 November 2026
- Tool-based conditions applied to the agent's skill index, checked 14 November 2026
- Curator archival, which skills it manages, and restore, checked 14 November 2026
- Telegram command menu cap, checked 14 November 2026
- Profiles keep separate skills, checked 14 November 2026
Written by Vavio with AI assistance and checked against pinned official Hermes v0.23.1 source and documentation. No skill was installed, hidden or restored on a running Hermes for this article.