Why Isn't My Hermes Agent Picking Up New Skills?

If your Hermes Agent is not picking up new skills, the most common cause is that skills are discovered at startup — so a skill added mid-session will not appear until you restart the agent. The next most common causes are a malformed SKILL.md, a description too weak for the agent to match, a disabled skill, or a body that exceeds the ~5,000-token guidance. This guide walks through each fix in order.

Fix 1: Restart So Skills Are Discovered

Hermes Agent discovers skills at startup, so a skill installed during a running session usually will not be picked up until the agent restarts. This is the single most common reason a "missing" skill is actually fine — it is on disk, correctly formatted, and simply has not been loaded yet.

After running an install (for example hermes skills install), restart the agent and start a fresh session, then confirm the skill appears in the skill list. The Hermes CLI reference lists the commands for installing and listing skills. If it shows up after a restart, nothing was ever broken. If it does not, move to the format check below.

Fix 2: Check the SKILL.md Format

A skill that fails to register almost always has a formatting problem in its SKILL.md. Hermes skills are markdown files with YAML frontmatter and structured sections, and a broken frontmatter block or a missing required field stops the file from being parsed.

Confirm the frontmatter is valid YAML, opens and closes with ---, and includes a name and a description. Per the official Hermes documentation, skills carry a name, a description, and a procedure — the agent reads the short description cheaply and loads the full body only when a task needs it. Hermes skills are also compatible with the agentskills.io format. If the YAML is malformed, none of that happens. Our Hermes Agent skills guide covers the full SKILL.md structure, and you can validate a file against the format with our free SKILL.md scorer.

Fix 3: Fix a Weak Description

Hermes decides whether to use a skill by matching your task against the skill's description, so a vague or generic description is a silent failure: the skill is loaded, but the agent never activates it. This is different from the skill "not being picked up" at all — the file registered, it just never fires.

Write the description as a clear trigger: state exactly when the skill should be used and with which inputs. "Use when the user asks to reconcile a Stripe payout against invoices" will match; "helps with finance" will not. If a skill exists but the agent keeps solving the task manually, tighten the description before touching anything else.

Fix 4: Confirm It's Installed and Enabled

A skill has to be both installed in the location Hermes reads from and enabled, not merely present on disk. If you copied a folder into the wrong directory, or the skill was installed but toggled off, the agent will not see it as active.

Re-run the install through the proper command rather than hand-placing files, then check the skill list to confirm it is enabled. If you manage many skills, disabling the ones you are not using keeps the active set focused — but make sure the one you actually want is on. For where to source clean, installable skills, see the best places to find Hermes Agent skills.

Fix 5: Watch the Token Limit

Hermes guidance is to keep a skill body under roughly 5,000 tokens, because the full body loads into context when the skill activates. An oversized skill can be skipped, truncated, or degrade the agent's performance when it does load.

If a large skill is not behaving, split it into two focused skills rather than one sprawling file — smaller, single-purpose skills both stay under the limit and match tasks more reliably. This also makes each skill easier for the agent to select, since its description maps to one clear job instead of many.

Limitations and When to Rebuild the Skill

Not every "not picking up" problem is a bug to fix in place. If a skill was auto-generated after a messy task, its procedure may encode the wrong steps, and no amount of restarting will make it useful — it is better to delete it and let the agent regenerate a cleaner version, or write a fresh SKILL.md by hand. Likewise, if two skills have overlapping descriptions, the agent may pick the wrong one; consolidate them. Restarting, fixing YAML, and tightening descriptions solve the mechanical cases, but a skill built from a bad run is worth rebuilding rather than debugging. When in doubt, start from a known-good skill from a trusted source — such as the community-maintained awesome-hermes-agent list — and adapt it.

Related Guides

• Hermes Agent Skills: The Complete Guide
• Best Places to Find Hermes Agent Skills
• How to Integrate Third-Party Plugins with Hermes
• How to Set Up Hermes Agent from Scratch