# AI Agent Skills in Hermes: Install a Skill and Create Your Own > Directories and GitHub, the SKILL.md format, /learn, checking, updating, and removing Hermes Agent skills with complete command examples. Source: https://ailoot.ai/blog/en/hermes-agent-skills/ Canonical: https://ailoot.ai/blog/en/hermes-agent-skills/ Language: en Publisher: Ailoot (https://ailoot.ai/) Translation: guide-117 Revision: sha256-6520b645790b606c86de67be8ec68c0e12e62cd4e4ad6e8d60202f3019da344e A skill is a saved instruction for an agent: you describe how to perform a task once, and from then on Hermes applies it when you call `/skill-name`, without needing repeated explanations. A ready-made skill can be installed with one command, and you can create your own in two ways: write SKILL.md manually or use `/learn`. If you haven't installed Hermes yet, start with the guide [what this agent is and how to install it](https://ailoot.ai/blog/en/hermes-agent-install-setup/), then move on to skills.
Practical instructions for using Ailoot are in the [documentation](https://ailoot.ai/docs/).
## What is a skill in Hermes Agent?
Takeaway A skill is a file containing instructions for an agent: what to do, which commands to use, what to pay attention to, and where mistakes commonly happen. It is stored in the `~/.hermes/skills/` folder as a SKILL.md file, along with any accompanying materials. After installation, the skill automatically becomes a `/name` command in any chat with the agent.
You write a prompt in a message to the agent. A skill is stored in a separate file, and Hermes can use that instruction in future tasks. The agent has access to a list of names and descriptions, and loads the full skill text when it is relevant to the task. This saves space in the context: not all instructions are loaded at once. A skill by itself does not give the agent new tools or access; it describes how to use the tools it already has. A new integration with an external service is handled by MCP, which is a separate topic. If a task requires precise program logic, special authorization, or event-stream processing, it needs agent tools; a skill alone is not enough. Choose a ready-made skill for a standard task if its instructions fit and its source has been checked. Write your own when you need to preserve your particular sequence of actions, constraints, and output format. Use `/learn` when you already have materials or have completed a process and don't want to write the file manually.

Skills are documents containing information an agent needs, which it loads only when needed.

— Hermes Agent documentation (translated from English), https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
The format is open and compatible with the [Agent Skills specification](https://agentskills.io/specification), so skills from other catalogs usually work in Hermes without any format changes, although a particular skill may require its own tools or keys. You can also share your own skill if you like. ## Which skills are already installed, and where are they stored?
Takeaway By default, skills are stored in the `~/.hermes/skills/` folder, organized into category subfolders (if you use a nonstandard profile or the HERMES_HOME variable, the path will be different; `hermes config path` will show it). After installation, Hermes already includes dozens of built-in skills, from searching arXiv to working with GitHub and documents. The `hermes skills list` command shows the list, and you can ask the agent in chat which skills it has.
The folder is organized like this: ``` ~/.hermes/skills/ ├── research/ │ └── arxiv/ │ ├── SKILL.md │ └── scripts/ ├── productivity/ │ └── pdf/ │ ├── SKILL.md │ └── references/ └── .hub/ ``` SKILL.md is the only required file. Everything else is added as needed: `references/` for longer materials, `scripts/` for helper programs, and `templates/` and `assets/` for templates and files. The built-in catalog includes skills for everyday tasks: finding GIFs, working with PDFs, spreadsheets, YouTube, GitHub, and notes. The complete list with descriptions is on the [built-in skills catalog](https://hermes-agent.nousresearch.com/docs/reference/skills-catalog) page. With every `hermes update`, Hermes also updates built-in skills while preserving your changes to them. ## How do you install a ready-made skill from the catalog?
Takeaway Open the catalog with `hermes skills browse`, find what you need with `hermes skills search`, view a skill's card with `hermes skills inspect`, and install it with `hermes skills install`. Every skill undergoes a security check before installation, and official skills do not trigger a third-party source warning.
1. ### Search the catalog ```bash hermes skills search pdf ``` The search runs across all connected sources. To see the full catalog without a filter, run `hermes skills browse`. 2. ### View the skill card ```bash hermes skills inspect anthropics/skills/skills/pdf ``` The card shows the description, source, and trust level. Don't install someone else's skill without reading its card. 3. ### Install it ```bash hermes skills install anthropics/skills/skills/pdf ``` Hermes downloads SKILL.md and its accompanying files, runs a security check, and puts everything in `~/.hermes/skills/`. The skill is immediately available as the `/pdf` command. If the skill needs additional tools or keys, they are listed in its SKILL.md, and Hermes will tell you during installation. The security check looks for attempts to send data outside, instructions injected for the agent, and commands that could delete or damage files. Sources have different trust levels: | Level | Skill source | What happens during installation | |----|----|----| | Built-in | Included with Hermes | Already in place; no installation needed | | Official | The optional-skills folder in the Hermes repository | Installed without a third-party source warning: `hermes skills install official/security/1password` | | Trusted | The openai/skills, anthropics/skills, huggingface/skills, and NVIDIA/skills repositories | Less strict check | | Other | Catalogs, other people's GitHub repositories, direct links | Warning and full check | If the check issues a warning, you can continue the installation with the `--force` flag, but first read what risk it found. A “dangerous” verdict cannot be bypassed. The check itself does not guarantee safety: before first running someone else's skill, read its instructions and accompanying commands. ## How do you install a skill from GitHub or a link?
Takeaway Install a skill from GitHub with `hermes skills install owner/repository/path`, or use a direct link to a SKILL.md file; Hermes will download the files that accompany it. You can connect your own skill source with `hermes skills tap add`, after which it works like any other catalog.
Three ways to install: ```bash # 1. A specific skill from a GitHub repository (the path inside the repository comes after its name) hermes skills install anthropics/skills/skills/pdf # 2. A direct link to a SKILL.md on any site hermes skills install https://example.com/SKILL.md # 3. Connect an entire repository as a source (replace with your owner and repository) hermes skills tap add myorg/skills-repo hermes skills install myorg/skills-repo/deploy-runbook ``` For a direct link, Hermes downloads SKILL.md and only the files mentioned in it from service subfolders; it does not download unrelated files from the site. The link is remembered as a source, and `hermes skills update` will later update the skill from the same address. In addition to GitHub, external skill catalogs can be connected. You can find skills from them with the same `hermes skills search` command, specifying the source.
Attention GitHub limits unauthenticated requests to 60 per hour. If you get rate-limit errors while installing or searching, add `GITHUB_TOKEN` to the `~/.hermes/.env` file; the limit will increase to 5000 requests per hour.
## How do you use a skill after installation?
Takeaway An installed skill automatically becomes a command: type `/skill-name` and the task on the same line. No separate activation is needed. It works in the terminal, web interface, and messengers through the gateway. You can invoke up to five skills in a single message, or turn a recurring combination into one command.
Enter `hermes ...` commands in the terminal, and `/skill-name` invocations in a chat with the agent (in the same terminal, the web interface, or a messenger): ``` /gif-search funny cats /github-pr-workflow create a PR for the authorization rewrite ``` If you enter `/skill-name` without a task, Hermes will load the instructions and ask what you want it to do. You can invoke several skills on one line, up to five; the remaining text becomes the task: ``` /github-pr-workflow /test-driven-development close issue 123 and open a PR ``` For combinations you use regularly, there are skill bundles, called bundles in Hermes terminology: `hermes bundles create backend-dev --skill github-pr-workflow --skill test-driven-development` groups several skills under one short `/backend-dev` command. Such a bundle acts as an alias; the skills in it must be installed beforehand. Slash commands also work in Telegram if the gateway is connected; setup is covered in the guide [how to connect Hermes Agent to Telegram](https://ailoot.ai/blog/en/hermes-agent-telegram-setup/). This is also a convenient way to run skills from your phone. ## How do you create your own skill: what goes in SKILL.md?
Takeaway Your own skill is a folder in `~/.hermes/skills/` with one required file, SKILL.md: a short header with a name and description, followed by instructions organized into sections—when to use it, the sequence of actions, common mistakes, and verification. It is written in plain text; no programming is needed. For a simple version, one folder and one file are enough.

Skills are the main way to add new capabilities to Hermes Agent: they are easier to create than tools, don't require changes to the agent's code, and can be shared with the community.

— Hermes Agent documentation (translated from English), https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills
You can copy this skill and adapt it for yourself: ```markdown --- name: weekly-review description: Weekly review: what got done, what stalled, plan for next week version: 1.0.0 metadata: hermes: tags: [planning, review] --- # Weekly review ## When to Use When the user asks to review the week or put together a plan for the next one. ## Procedure 1. Get the week's task list from the file the user provided, or ask them for it. 2. Sort the tasks into three groups: done, stalled, and new. 3. Name three priorities for the coming week. ## Pitfalls - Don't invent tasks that aren't in the original list. ## Verification Ask the user to confirm that the tasks are correctly sorted into “done,” “stalled,” and “new.” ``` The header between the triple dashes is metadata. The main fields are `name` (in Latin letters, hyphen-separated, and used to invoke the skill as a command) and `description`. The agent uses the description field to decide whether the skill fits the current task and should be loaded. If the description is vague, the skill may not load when needed. The header is followed by instruction sections. `When to Use` says when to load the skill. `Procedure` gives the steps to follow. `Pitfalls` covers where the agent commonly makes mistakes and how to avoid them. `Verification` explains how to check the result. If the instructions are long, move the main content to files in `references/`; they will be loaded only when needed, and put helper programs in `scripts/`.
Tip Put the most common scenario first and rare cases at the end of the file. Hermes reads a skill from top to bottom, and this order saves context.
If a skill needs an API key, declare it in the header using `required_environment_variables`; do not put the key itself in the file, only declare the variable name. Hermes will ask for the value once, on the first invocation in a local terminal, and then supply it automatically (in messengers, it will prompt you to configure the key locally). The `platforms`, `config`, `blueprint`, and other fields are described on the official documentation page [Creating Skills](https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills). With the file ready, follow these steps: 1. ### Create the skill folder ```bash mkdir -p ~/.hermes/skills/weekly-review ``` The folder name matches the `name` field in the header. 2. ### Save SKILL.md Put a file called `SKILL.md` with your instructions inside the folder; you can use the example above and rewrite it for your task. 3. ### Call the skill and check it Enter `/weekly-review` and ask the agent to review your week. If it follows the steps in your instructions, the skill works. ## How do you build a skill from existing materials with /learn?
Takeaway The `/learn` command builds a skill from existing materials: give it a folder of documentation, a page link, your notes, or a verbal description of a process, and Hermes writes SKILL.md according to accepted conventions for you to review. A book or large archive will produce a skill with separate files by topic.
``` /learn documentation for the demo API in ~/projects/example-docs, especially the section on authentication /learn https://hermes-agent.nousresearch.com/docs/user-guide/features/skills /learn how I just published a site to hosting ``` If you've just completed a complicated process with the agent, ask `/learn` to save it as a skill while all the steps are still in the conversation. Next time, Hermes will repeat the procedure using the ready-made instructions. A large source, such as a book, specification, or document archive, won't fit into a single file. Hermes will create a compact SKILL.md with a topic map and move the details into `references/`. These files do not take up context space until the agent loads them to answer a question. Calling `/learn` again on the same topic appends to the existing skill instead of creating a duplicate. ## How do you check that a skill works?
Takeaway To check it, run `hermes chat --toolsets skills -q` and give it a request related to the skill, such as asking it to review a week using a task list. If the agent sorts the tasks into the groups in your instructions, the skill works. If it responds as usual, check the filename, the description in the header, and where you put the folder.
```bash hermes chat --toolsets skills -q "review my week using the weekly-review skill: done - report and calls, stalled - hosting payment" ``` This is the test the documentation recommends: run the skill and check that the agent follows your instructions. If it doesn't, check three possible causes. First, the folder name or the `name` in the header may not match the name you invoke. Second, the description may be written in a way that doesn't make clear when the skill should be used; rewrite the description using the words of the task itself. Third, the folder may not be in `~/.hermes/skills/`, so Hermes cannot see it. Note that the `--toolsets skills` flag limits the test's toolset: it shows how the agent works with the instruction, but does not check the skill's dependencies, such as external programs. `hermes skills list` in the terminal shows exactly what is installed. ## How do you update and remove skills?
Takeaway `hermes skills check` shows which installed skills have been updated at their source, `hermes skills update` downloads the new versions, and `hermes skills uninstall name` removes a skill. Your edits to someone else's skill are preserved during updates: Hermes skips changed files. You can restore the original: for a skill from the hub, use `hermes skills update name --force`; for a built-in skill, use `hermes skills reset name --restore`.
```bash hermes skills check # what changed at the sources hermes skills update # download new versions hermes skills uninstall pdf # remove a skill from the hub ``` To remove a skill you created manually, delete its folder from `~/.hermes/skills/`. If you customized someone else's skill, `update` will leave it alone: Hermes compares hashes and skips changed files to avoid overwriting your work. To restore the original for a skill from the hub, use `hermes skills update name --force`; for a built-in skill, use `hermes skills reset name --restore`. Both commands overwrite your changes, so save your version first. If you don't need the built-in skills and they clutter the list, `hermes skills opt-out` will disable their addition during updates. The `opt-out --remove` command will also remove those you haven't changed. ## What should you do if a skill won't install or work?
Takeaway Three things most often get in the way: GitHub's limit of 60 requests per hour, installation blocked by the security check, and the file being in the wrong folder. If you hit the rate limit, add `GITHUB_TOKEN`. If the check blocked installation, read its verdict. If Hermes can't see the skill, check whether it is in `~/.hermes/skills/`.
| Symptom | Cause | What to do | |----|----|----| | Rate-limit errors while searching or installing | Without a token, GitHub allows up to 60 requests per hour | Add `GITHUB_TOKEN` to `~/.hermes/.env` | | Installation blocked | The check found a risk in the skill's code | Read the check output during installation; to recheck an installed skill, run `hermes skills audit`. If it is a warning, you can continue with `--force`; if the verdict is “dangerous,” you cannot | | Skill installed, but `/name` does not work | The name does not match or the folder is misplaced | Run `hermes skills list` and check the `~/.hermes/skills/` folder | | Skill is not even in the list | Its SKILL.md has a platform or required-tools restriction | Open its SKILL.md and check the `platforms` and `requires_*` fields | | New skill version was not fetched after update | You changed the file locally, and Hermes preserves your edits | If you need the original, use `update name --force` for a skill from the hub or `reset --restore` for a built-in one; if your version matters more, do nothing | | Skills from another repository won't load | The repository must be marked as trusted | Run `hermes skills trust` inside the repository | Hermes finds skills in `.hermes/skills/` and `.agents/skills/` folders inside a git repository. Before loading them, you must mark the repository as trusted: these files contain instructions the agent will follow. After that, skills from the repository work only within it and undergo the same security check. You only need to mark the repository as trusted once. ## What should you do first?
Takeaway Install one ready-made skill from the catalog; installation takes only one command. Then take an instruction you repeat, pass it to `/learn`, and check the result on a real task from your work.
Next on this topic: [how to connect Hermes Agent to Telegram](https://ailoot.ai/blog/en/hermes-agent-telegram-setup/), so you can invoke skills from your phone, and [how to keep an agent running on a server around the clock](https://ailoot.ai/blog/en/hermes-agent-vps-24-7/), if you want scheduled skills. If you are choosing an agent, see the comparison [OpenClaw or Hermes Agent](https://ailoot.ai/blog/en/openclaw-vs-hermes-agent/).
### Sources - [Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs/) - [Skills System - how skills work](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) - [Creating Skills - how to write your own skill](https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills) - [Built-in skills catalog](https://hermes-agent.nousresearch.com/docs/reference/skills-catalog) - [Official optional skills](https://hermes-agent.nousresearch.com/docs/reference/optional-skills-catalog) - [Hermes Agent repository on GitHub](https://github.com/NousResearch/hermes-agent) - [Open Agent Skills standard](https://agentskills.io/specification)
You can continue exploring Ailoot at [ailoot.ai](https://ailoot.ai/).
## Questions about Hermes Agent Skills: Installing and Creating Your Own Skill ### Why does an installed skill not appear as a slash command? Check the installed-skills list, the SKILL.md filename and name field, and the active profile’s skills folder. Platform, required-tool, or repository-trust restrictions can also prevent it from loading. ### Does the limited skills smoke-test verify every dependency? No. A skills-only test checks whether the agent loads and follows the instruction. Check required tools, programs, and keys separately, then verify one bounded real result before using the full workflow. ## Ailoot · The company and its project portfolio Ailoot combines established operating experience, a large client base, stable service and ongoing KPI control. The company and its project portfolio: millions of customers; monthly sales in the billions. Ailoot brings that operating experience to API access for AI features in customer products, agents, applications and automations.