Skip to content
vavio

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:

  1. the project’s .hermes/skills/ or .agents/skills/, only in a repository you trusted;
  2. the profile’s ~/.hermes/skills/;
  3. skills.create_dir, if you set it;
  4. 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_dirs produces 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 trust inside the repo if you have read its skills. Setting skills.project_discovery: false turns project skills off entirely.
  • Nested in another skill’s support folder. A SKILL.md inside another skill’s references/, templates/, assets/ or scripts/ 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_tools and requires_toolsets hide the skill when those tools are off. fallback_for_tools and fallback_for_toolsets hide 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: deploy as a one-item list, including when it was written with hermes 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: true is 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 model or status loads normally but gets no /model or /status shortcut. hermes skills list notes 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-skills forces 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

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.

More from the Vavio blog: Hermes Agent guides