Author Hermes Agent skills that load when intended

A skill is a compact routing record plus an on-demand procedure. Its directory and description decide whether Hermes can discover it and has enough signal to load it.

Validation, discovery, activation, and task success are separate checks. Passing one does not establish the next. Source reviewed on 2026-07-28. Runtime implementation claims below are pinned to Hermes commit a9c9467dd8f0757cd3c04d3138992fbf3727b32b. Any successful local run needs a record of the Hermes version or commit, model, active toolsets, skill path, prompt, and observed load behavior. The commands in this article are verification procedures, not reported pass results.

Choose a skill only when the agent should interpret a procedure

Use a skill when the useful part of the capability is a documented procedure that the model can adapt to the task. Use a tool when the useful part is an execution contract the model must not reconstruct. Hermes makes the same distinction in its skill versus tool guidance.

A skill may call a small, checked-in helper script. That does not turn every deterministic integration into a good skill. Do not encode unavailable commands, invented APIs, hidden credentials, or a human-only UI ritual as if Hermes can verify them.

Put the source and the installed skill in the right place

These paths answer different questions:

• <active-hermes-home>/skills/<skill-name>/SKILL.md is the local installed skill location and the right place for a personal runtime test. ~/.hermes is the default POSIX Hermes home, so ~/.hermes/skills/<skill-name>/SKILL.md is only the default POSIX profile path. A named profile, a custom HERMES_HOME, or Windows resolves the active Hermes home elsewhere. Hermes documents the skills directory and its relationship to other discovered locations in the Skills System guide, the profiles guide, and the environment-variable reference. The pinned manager also resolves its local directory from the active Hermes profile in its source.
• skills/<category>/<skill-name>/SKILL.md is the in-repository source location for a broadly useful bundled Hermes skill.
• optional-skills/<category>/<skill-name>/SKILL.md is the in-repository source location for an official skill that should not ship to every user.

Hermes describes the repository directory shape in its skill directory guidance and distinguishes bundled from optional source content in where a skill should live. The source versus installation boundary matters: bundled repository content is seeded or copied into the active Hermes profile. Contributors edit repository source; a user testing a private skill installs it under the active profile's <active-hermes-home>/skills.

Repository skills/ and optional-skills/ are not additional live per-user roots. In particular, do not put optional skills under <active-hermes-home>/optional-skills.

Treat the description as a routing test, not a summary

The Agent Skills specification allows a description up to 1024 characters and asks it to say both what the skill does and when to use it. Hermes has a tighter implementation constraint at the pinned commit: the create path requires a description within a 60-character system-prompt budget. Existing longer descriptions remain editable, but the prompt index truncates them to 57 characters plus ..., as shown by the manager validation, prompt preview code, and boundary tests.

For Hermes, author to the tighter budget. Put the trigger first, make it self-contained, and move qualifications into the body.

# Weak
description: Helps with documentation.
 
# Better for the pinned Hermes routing budget
description: Use when a local Markdown link fails. Verify its target.

The weak description names a broad domain but no activation condition. The better description starts with an observed trigger and ends with a bounded action.

Use a portable name: lowercase letters, digits, and single hyphens; match the frontmatter name to the parent directory; stay within 64 characters. Avoid dots and underscores. The pinned Hermes implementation accepts them, but the Agent Skills name rules do not. This is a compatibility choice, not a claim that Hermes rejects those characters.

Keep the common path in SKILL.md and disclose the rest on demand

Skills work best when they use progressive disclosure. name and description are cheap routing metadata, the full SKILL.md body loads after activation, and supporting files load only when the task needs them. Hermes explains this model in its Skills System documentation and authoring guide; the Agent Skills specification defines the portable version.

Keep the body focused on trigger boundaries, the common procedure, failure handling, and verification. Move long API references and edge-case catalogs into references/. Put reusable deterministic logic in scripts/. Put output material in assets/ or templates/ only when the procedure uses it.

Do not create support files just to make a directory look complete. Do not make the agent chase a reference chain to understand the common path. At the pinned Hermes commit, managed writes accept references/, templates/, scripts/, and assets/, according to the allowlist and path validation. That is Hermes implementation behavior, not a universal specification extension.

Build one small skill with a falsifiable procedure

This complete example has a narrow scope:

---
name: verify-local-markdown-link
description: Use when a local Markdown link fails. Verify its target.
---
 
# Verify a local Markdown link
 
## Procedure
 
1. Read the named Markdown file and copy the exact relative target.
2. Resolve the target from the Markdown file's directory.
3. Check whether the resolved path exists without modifying it.
4. Report the source file, original target, resolved path, and result.
 
If the target is an HTTP URL or an in-page anchor, stop and say that this skill does not cover it.
 
## Verification
 
A result is complete only when it shows the resolved path and the existence check.

The trigger is narrow and fits the pinned Hermes prompt budget. The procedure uses ordinary file inspection and a read-only path check, has an explicit out-of-scope branch, and defines observable completion evidence. It does not invent a helper command or claim to validate all Markdown semantics. It needs no supporting files yet; empty references/ or scripts/ directories would not improve progressive disclosure.

Verify six layers in order

Use this matrix as the acceptance procedure. It expresses an inference from the sources: structural validity and runtime routing are independent acceptance layers.

The following are command templates to execute during verification. They have not been run for this article.

skills-ref validate "<active-hermes-home>/skills/verify-local-markdown-link"
 
# Run this only against a disposable Hermes home, then record the successful create result.
HERMES_HOME="<disposable-hermes-home>" hermes chat --toolsets "skills,file,terminal" -q "Use the managed skill tool to create the verify-local-markdown-link skill with the documented frontmatter and procedure."
 
# Inspect only after managed creation, using the same disposable Hermes home.
HERMES_HOME="<disposable-hermes-home>" hermes chat --toolsets "skills,file,terminal" -q "Show me the verify-local-markdown-link skill."
HERMES_HOME="<disposable-hermes-home>" hermes chat --toolsets "skills,file,terminal" -q "Use the verify-local-markdown-link skill to check the disposable, read-only Markdown fixture with a broken relative link."

skills-ref validate checks Agent Skills structure, but at agentskills/agentskills commit 38a2ff82958afee88dadf4831509e6f7e9d8ef4e it validates the directory, SKILL.md, frontmatter, name, and directory match without checking that the procedure body is nonempty. That is why the separate body inspection is required. Record the exact skills-ref version or source commit with the result; this article does not assume a version-reporting command. The documented Hermes chat command exercises the live agent. The Toolsets Reference documents that skills provides skill browsing and management, file provides file reading, and terminal provides shell execution, so the runtime commands use all three toolsets. Keep the Markdown fixture disposable and read-only. The pinned create path, recursive discovery and collision lookup, frontmatter and creation tests, and placement and collision tests establish implementation constraints, not a live routing result.

For natural routing, do not mention the skill name in the prompt. Use a fresh session for each case and hold the Hermes commit or version, model, toolsets, working directory, and fixture constant. Test a local Markdown file with a missing relative target, then the same fixture with an existing target. Also test an HTTP-link request as the near miss and a request for a short summary of the Markdown file as the negative case. Record actual loading from a tool trace or skill-view event, not from a plausible final answer. Repeat each routing case at least three times before claiming reliability, and report observations as results for the pinned setup rather than a universal selection rate.

Apply a compact acceptance rule

A predictable Hermes skill has one portable name, one trigger-first description, one correct installed location, a short common procedure, and observable verification. It loads for the positive case and stays unloaded for nearby negative cases.

If the behavior requires exact custom execution, a first-class authentication flow, streaming, or binary handling, stop stretching SKILL.md and build a tool. If a procedure cannot be verified, it is a note, not a reusable skill.