What a skill is for
A skill is a markdown document that teaches Hermes how to do a particular job: your release checklist, the way you like research briefs formatted, the steps for triaging a support inbox. The docs sum up the split neatly: memory stores facts, skills store procedures. If you notice yourself explaining the same multi-step process for the third time, that is a skill waiting to be written.
Skills follow the open agentskills.io format and use progressive disclosure, which keeps them cheap. At session start Hermes only sees a compact index of skill names and descriptions (around 3k tokens for the whole list). It loads a skill's full text only when it decides the skill is relevant, and loads supporting files only if the skill points to them.
Step 1: create the folder and file
Personal skills live in ~/.hermes/skills/, one folder per skill, optionally grouped by category. The official guide's example path is ~/.hermes/skills/my-category/my-skill/SKILL.md. The only required file is SKILL.md; you can add references/, templates/, scripts/, examples/ or assets/ folders next to it for supporting material.
The file starts with YAML frontmatter. The documented example looks like this: name: my-skill, description: Brief description of what this skill does, version: 1.0.0, and a metadata.hermes block with tags and a category. Optional fields include platforms (limit the skill to macos, linux or windows) and required_environment_variables for secrets the skill needs.
Step 2: write a description that earns the load
The description is the most important line you will write, because it is nearly all the agent sees before deciding whether to open the skill. Say plainly what the skill does and when it applies, using the words you would naturally use when asking for that task. "Formats weekly research briefs with sources, confidence notes and a three-bullet summary" will be picked up far more reliably than "Brief helper".
For the body, the official template suggests four sections: When to Use, Procedure, Pitfalls and Verification. This is a recommendation, not a required schema, but it is a good shape. Keep the main file focused and move long reference material into references/, then point to it from the procedure so Hermes fetches it only when needed.
Step 3: use it
Every installed skill automatically becomes a slash command. Typing /my-skill followed by a task runs it with that skill loaded; typing the name alone loads the skill without a task. You can also just ask in plain language ("use my release-checklist skill"), which makes the agent call skill_view. You can chain up to five skill commands at the start of one message.
One timing detail: skills added during a session are announced on your next message, but the system prompt itself stays fixed to protect prompt caching. Hub-installed skills take effect in new sessions; /reset, or --now on install, applies them immediately at the cost of more tokens on the next turn.
Letting Hermes write skills for you
Hermes can create and update skills itself through the skill_manage tool, which supports create, patch, delete, write_file and remove_file. After a complex task it may offer to save the approach as a skill, and there is also a /learn command that drafts a skill from a directory, URL, workflow or document. An advisory linter warns about oversized bodies or too many reference files but never blocks a write.
If you would rather approve those changes, set skills.write_approval: true. Writes are then staged under ~/.hermes/pending/skills/ and you review them with /skills pending, /skills diff <id>, /skills approve and /skills reject.
Sharing and installing
The Skills Hub lets you browse and install community skills with hermes skills browse, search, inspect and install (for example hermes skills install official/security/1password), or install straight from a URL. Every hub install passes a built-in security scanner, and a skill rated dangerous cannot be forced through. Project-local skills in a repo's .hermes/skills/ or .agents/skills/ folders load only after you run hermes skills trust for that repo.
Related guides
- Hermes Agent skills vs plugins vs MCP: which to use
- Hermes Agent not using your skill
- How Hermes Agent memory works (and where it stops)
Primary sources
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