Hermes Agent not using your skill

What you see

You created or installed a skill, but Hermes does the task its own way, says it has no such skill, or the /skill-name command doesn't autocomplete. Or the skill works in the terminal but not on Telegram.

Likely causes

Hermes doesn't read every skill in full at the start of a session. It sees a compact index of names and descriptions and decides from that whether to open a skill. So a skill can be ignored either because Hermes can't see it at all, or because it can see it but the description doesn't match how you phrased the request. The checks below cover both, starting with the quick ones.

• The file is in the wrong place or isn't named SKILL.md, or its YAML frontmatter is malformed.
• The skill was added mid-session and the current session hasn't picked it up, or a hub install hasn't taken effect yet.
• The description is vague, so the agent doesn't connect it to your request. The agent decides from the index of names and descriptions.
• The skill is filtered out: a platforms field excludes your OS, it is hidden on that messaging platform, or requires_toolsets / requires_tools names a toolset that isn't enabled.
• A same-named skill elsewhere shadows it (project skills beat local, local beats external_dirs).
• It is a project-local skill in a repo you haven't trusted, or it was quarantined by the security scanner.
• You're on a different profile; each profile has its own skills folder.

Check this first

• Confirm the path: ~/.hermes/skills/<;category>/<skill-name>/SKILL.md (or the profile's own skills folder).
• Type / in the CLI and see if the skill appears in autocomplete.
• Run hermes skills to check per-platform visibility.
• Read the frontmatter: is name set, is description specific, are platforms, requires_toolsets or requires_tools excluding you?
• For a repo's .hermes/skills/ or .agents/skills/, have you run hermes skills trust?
• hermes -p <profile> if you use more than one profile.

Fix

• Start a new session (/new or /reset) after adding a skill; hub installs can use --now to apply immediately.
• Invoke it explicitly with /skill-name <task> to confirm the skill itself works.
• Rewrite the description to say what the skill does and when to use it, in the words you'd use when asking.
• Remove or adjust restrictive platforms or requires_* fields, or enable the toolset it depends on with hermes tools.
• Rename one of two clashing skills so a higher-precedence copy doesn't hide yours.
• Trust the repo with hermes skills trust for project-local skills.
• For a hub skill, hermes skills check and hermes skills update; hermes skills reset --restore reinstates a bundled skill you broke.

If it still fails

Ask Hermes directly to call skill_view on your skill and summarise it. If it can load it but still skips it, the instructions may be too long or ambiguous; move detail into references/ and keep the procedure short. If skills.write_approval is on, an agent-made edit may be sitting in /skills pending. Finally, remember a skill is guidance, not enforcement: for steps that must happen every time, a scheduled job or explicit slash command is more reliable than hoping the agent recalls it.

Related guides

• How to write your first Hermes Agent skill
• Hermes Agent skills vs plugins vs MCP: which to use
• Hermes Agent ignoring your project instructions

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher