Plain-English Guide
Hermes Agent Skills: What They Are and How to Write Your First One
A skill is a small folder of instructions, and the person who wrote it is the person you are trusting.
Hermes Agent, from Nous Research, lets you teach it repeatable jobs through skills. This guide explains what a skill is, where it lives on your machine, how to treat a stranger's skill safely, and how to write a first one by hand. It is an independent guide, not affiliated with Nous Research, and it is separate from Claude's own skills system.
In Hermes Agent, the coding agent from Nous Research, a skill is a folder containing a SKILL.md file of instructions, following the open agentskills.io standard. Installed skills live in ~/.hermes/skills/ and each one becomes a slash command. Skills use progressive disclosure, so the agent loads a skill's full text only when it is relevant. You can write one by hand, and because a third-party skill is another person's instructions, read its SKILL.md before enabling it.
Published
Free lesson · no account neededMeet ClaudeWhy Claude?6 minStart the free lessonKey Takeaways
- A Hermes Agent skill is a folder with a SKILL.md file inside it, written to the agentskills.io open standard, so the format is plain text you can read and edit.
- Installed skills sit in ~/.hermes/skills/ on disk, and every installed skill automatically becomes a slash command you can call inside Hermes Agent.
- Progressive disclosure keeps token use down: the agent loads the fuller instructions in a skill only when the current task actually calls for them.
- You can write a skill by hand as a plain SKILL.md in the skills directory, or ask the /learn command to draft one from docs, notes, or a past conversation.
- A skill from the Skills Hub or anywhere else is a stranger's prompts and sometimes executable instructions, so read the SKILL.md before you install or enable it.
Four ways a skill ends up in Hermes Agent
| Route | Best for | Effort | Main thing to watch |
|---|---|---|---|
| Write it by hand | A task you do the same way every time and know well | You write a plain SKILL.md in the skills directory | The wording: vague instructions produce vague behavior |
| Draft it with /learn | Turning docs, a local SDK, a past conversation, or pasted notes into a first draft | Low to start, then you review and edit the draft | The draft reflects the source material, including its gaps and mistakes |
| Install from the community Skills Hub | Reusing something others already solved | Lowest, but reading the skill first is still your job | You are running a stranger's instructions inside your agent |
| Use the bundled hermes-agent skill | Questions about Hermes Agent's own CLI usage, setup, configuration, and troubleshooting | None, it ships with the agent | It describes the product, so check it against the live docs if something looks off |
Copy and Paste
Prompts You Can Use Today
Turn a repeated task into a first SKILL.md draft
I want to write an agent skill in the agentskills.io format, as a folder containing one SKILL.md file. The job: every Friday I turn my rough bullet notes into a status update for my manager. The update has three parts: what shipped, what is blocked, and what is next. It should be under 150 words, plain and factual, with no hype. Draft the SKILL.md with a short metadata block at the top (a name and a one-sentence description of when to use it), then clear numbered steps, then a short example of good output.
Swap the Friday status update for any task you repeat at least weekly. The more precisely you describe the output, the better the first draft.
Review a third-party skill before you install it
I am about to install an agent skill written by someone I do not know. Below is the full text of its SKILL.md. Act as a careful reviewer. List every instruction that runs a shell command, reads or writes files outside the project, makes a network request, or asks for credentials or API keys. Then flag anything that tells the agent to hide its actions from me or ignore my other instructions. End with a plain verdict: install, install with changes, or do not install, and say why. Here is the file: [paste SKILL.md]
Paste the whole file plus any scripts in the folder. A model review is a second pair of eyes, not a replacement for reading the file yourself.
Sharpen the description so the skill triggers at the right time
Here is the metadata and first paragraph of my agent skill. The agent keeps loading it for unrelated tasks and sometimes misses it when I need it. Rewrite the description in one or two sentences so it says exactly when the skill applies and when it does not. Give me three example requests that should trigger it and three that should not, so I can test the wording. Skill text: [paste the top of your SKILL.md]
Because skills load progressively, the short description is what the agent sees first. It is the most important sentence in the file.
Convert a messy runbook into skill steps
Below is an internal runbook I use to onboard a new client into our project tracker. It is long and mixes background with actual steps. Rewrite it as agent skill instructions: keep only the actions the agent must take, put them in numbered order, mark any step that needs my confirmation before the agent proceeds, and move reference material into a clearly labeled section at the bottom. Do not invent steps that are not in the runbook. Runbook: [paste text]
Asking for confirmation points is a good habit for anything that changes data or sends messages.
Stress-test a skill with awkward inputs
I wrote an agent skill that summarizes meeting transcripts into action items. Here is its SKILL.md. Act as a tester. Invent six realistic but awkward inputs, such as a transcript with no decisions, one with two people disagreeing about an owner, and one in mixed languages. For each, predict where my instructions are ambiguous and suggest one sentence I could add to the skill to fix it. SKILL.md: [paste file]
Run the real skill on the inputs it produces, then compare the actual result with the prediction.
Write a plain-language README for a skill you want to share
I have an agent skill folder I want to share with colleagues. Write a short README in Markdown for it covering what the skill does, what it needs installed, every file in the folder and what each one does, whether it runs any commands or touches the network, and how to remove it. Keep it honest and under 300 words, written for someone who has never seen the skill before. Folder contents: [paste file list and SKILL.md]
A reader who can see exactly what the skill touches is far more likely to trust it, and you are far less likely to be surprised later.
The basics
What a Hermes Agent skill is made of
Nothing about a skill is exotic. It is a folder, a text file, and a convention for how the agent finds and uses it.
A folder with a SKILL.md
The skill is a directory. Inside it is a file named SKILL.md holding instructions for the agent, written in plain text you can open in any editor.
An open standard
Hermes Agent follows the agentskills.io open standard. That means the format is shared with other agent tools rather than invented just for Hermes.
A slash command
Every installed skill automatically becomes a slash command inside Hermes Agent, so you can call a skill by name instead of re-explaining the job.
Loaded on demand
Skills use progressive disclosure. The agent reads the full instructions only when a skill is relevant to the task at hand.
A fixed home on disk
Installed skills live in the ~/.hermes/skills/ directory. If you want to know what your agent can do, you can list that folder.
A community hub
Nous Research hosts a Skills Hub where people share and discover skills other Hermes Agent users have built.
Why skills exist
The problem a skill solves
Anyone who works with an AI agent repeatedly runs into the same friction. You explain how you like your weekly report formatted, the agent does it well, and next week you explain it all again. A skill is the fix: you write the explanation down once, in a file, and the agent can pick it up whenever the job comes around.
This is different from a one-off prompt in a specific way. A prompt lives in a single conversation. A skill lives on disk, has a name, can be edited like any document, can be copied to a colleague, and can be improved over months. It is closer to a recipe card than to a sentence you said once.
Think of it as the difference between telling a new hire how to file expenses on their first morning and handing them a one-page procedure. The procedure can be read by anyone, corrected when the finance system changes, and reused by the next new hire. Skills give an agent that same kind of durable, shareable instruction.
How it works
Progressive disclosure, explained without jargon
An agent has a limited amount of text it can hold in mind at once, usually called its context window, and every token spent on instructions is a token not available for your actual task. If you installed fifty skills and the agent loaded all fifty in full at the start of every session, most of that space would be wasted on instructions for jobs you are not doing.
Progressive disclosure is the answer. Per the official docs as reported, the agent only loads the fuller instructions inside a skill when that skill is actually relevant to the current task. Before that point, the agent works from the lightweight identifying information about each skill, enough to know the skill exists and roughly what it is for.
This has a practical consequence for you as an author. The short description at the top of a skill does the work of a table of contents entry: it is how the agent decides whether to open the rest. A skill with a vague description may be opened for the wrong jobs or ignored for the right ones. Spend more time on that first sentence than on any other line in the file.
It also means you can afford to be thorough inside a skill. Detailed steps, edge cases, and examples cost nothing when the skill is not in use. They only cost tokens on the occasions when you need them.
Finding and installing
Where skills live and how to get one
Installed skills sit in ~/.hermes/skills/ on your machine, one folder per skill. Once a skill is installed, it appears as a slash command inside Hermes Agent without extra wiring. The folder is the source of truth, so deleting a skill's folder is how you remove it, and opening its SKILL.md is how you see exactly what it tells the agent to do.
To discover skills other people have built, the community Skills Hub from Nous Research is the place to start. Browse it the way you would browse any package index: look at what a skill claims to do, who published it, and then open the actual file. For the exact installation steps and current command names, follow the Hermes Agent documentation at hermes-agent.nousresearch.com/docs/, which is the authority here. Docs change, so check the live pages for anything this guide describes, especially commands and menu names.
The docs site also publishes llms.txt and llms-full.txt versions of its content, which are plain-text files meant to be fed to another model. That is a handy trick: paste the contents of llms-full.txt into any capable assistant and ask it questions about Hermes Agent, such as how a particular skill setting works. You get an answer grounded in the project's own words rather than a guess. Hermes Agent also ships with at least one bundled skill, documented as hermes-agent. It covers the agent's own CLI usage, setup, configuration, and troubleshooting. Opening it is a good first exercise, because it is a real, working example of the format written by the people who built the tool. Reading a few good skills before writing your own is the fastest way to develop a feel for tone and structure.
If you are brand new, read the bundled hermes-agent skill first. It costs nothing, shows you a working example of the format, and answers questions about the tool itself. Then write one small skill by hand for a job you know well. That order teaches you the most per hour spent. If you already have good source material, such as a clean documentation page or a conversation where the agent got a hard task right, try /learn to get a draft quickly, then edit it hard. You will learn what the agent extracts well and what it misses. If you want to borrow rather than build, browse the Skills Hub, pick a skill with a narrow and clearly stated purpose, and read every file before installing. Prefer skills whose instructions are short enough for you to read fully in a few minutes. A skill you cannot finish reading is a skill you cannot vouch for.
Safety
A third-party skill is a stranger's instructions
This is the part to take seriously. A skill is prompts, and sometimes executable instructions, written by whoever published it. When you install a third-party skill, you are running what amounts to another person's code and instructions inside your agent. The agent will follow them with whatever access you have given it: your files, your terminal, your accounts.
This is general guidance that applies across agent-skill ecosystems, not a quotation from Nous Research. The sensible habit is the same one you would use for a browser extension or a package from an unfamiliar author: read it before you enable it. A SKILL.md is just text, so reading it costs a few minutes and requires no special skill beyond patience.
Most skills will be harmless and useful. The point of reading is not to assume the worst about people. It is that the cost of checking is small and the cost of an unchecked mistake, such as an instruction that quietly sends your files somewhere, is large and hard to undo. A capable reader is calm about this and simply does the check every time.
A reading checklist
What to look for before you enable a skill
Open the folder, not just the Hub listing. Check every file, not only SKILL.md.
Read the whole SKILL.md
Does the text match the description? A skill that claims to format reports but contains instructions about unrelated systems deserves a second look.
Find every command
Look for any step that runs a shell command, installs software, or executes a script in the folder. Read those scripts too, since they are code.
Spot network activity
Note any instruction that fetches from or sends data to a URL. Ask whether the skill needs the network to do its stated job.
Watch for secrets
A skill has no business asking for API keys, tokens, or passwords unless its purpose clearly requires them. Be wary of instructions to read credential files.
Check the scope
Does it touch only the project you are working in, or does it reach into your home directory and other folders? Narrower is safer.
Distrust secrecy
Any line telling the agent to hide what it is doing, skip confirmation, or override your own instructions is a reason to stop and not install.
Hands-on
Write your first skill by hand
Writing by hand is the best way to learn, because it forces you to say exactly what you want. Pick a job you do at least weekly and that has a clear good result. A status update, a meeting summary, a commit message in your team's style, or a standard reply to a common customer question all work. Avoid anything that changes important data in your first attempt.
Create a new folder inside ~/.hermes/skills/ and name it after the job, in lowercase words joined by hyphens, such as weekly-status-update. Inside, create a file named SKILL.md. Per the official docs as reported, a hand-written skill is just a plain SKILL.md in the skills directory, following the same agentskills.io format the bundled skills use. The standard calls for a short metadata block at the top that names the skill and describes when to use it, so check the agentskills.io specification for the exact required fields rather than relying on memory.
Below that metadata, write the body as if briefing a capable colleague who has never seen your work. State the goal in one sentence. List the steps in order. Say what the output should look like, including length and format. Add one short example of a good result, because examples communicate tone faster than rules do. If a step needs your approval before the agent acts, say so explicitly.
Then use it. Open Hermes Agent, call the skill by its slash command, and give it real input. Read the result critically. Where the output surprised you, the instructions were probably ambiguous. Edit the SKILL.md, run it again, and repeat. Three or four rounds of this usually turn a mediocre skill into a dependable one, and each round teaches you something about how the agent reads instructions.
A faster start
Drafting with /learn, and why you still edit
Hermes Agent includes a /learn command that has the agent draft a SKILL.md from source material you point it at. Reported examples of sources include a documentation page, a local SDK, a past conversation, or pasted notes. This is useful when the knowledge already exists somewhere and you do not want to retype it. If you have just spent an hour getting the agent to handle a tricky task correctly, turning that conversation into a skill captures the working method.
Treat the output as a first draft, never a finished product. A generated skill reflects its source, including that source's gaps, outdated advice, and stray assumptions. If you point it at a documentation page for an old version of a library, you will get a skill that confidently teaches the old way. Read the draft the way you would read a colleague's first pass: check the steps are right, cut what is unnecessary, and tighten the opening description.
Because this command is described by a smaller number of sources than the other features here, try it first on a throwaway skill so you can see how it behaves in your version before relying on it for something important.
Even when the draft is good, run the same test loop as for a hand-written skill. Call it on real input, notice where it stumbles, and revise. The agent can write the first version, but you are the one who knows what good looks like for your work.
Craft
What separates a good skill from a forgettable one
Good skills are narrow. A skill called handle-all-my-email will be vague and unreliable. A skill called triage-support-inbox, with specific categories and a defined output, will be consistent. If a skill grows long and starts covering several unrelated jobs, split it. Small, named skills are easier to test, easier to share, and easier for the agent to choose correctly.
Good skills show rather than only tell. A single worked example of the output you want does more than a paragraph of adjectives. Include a short example of the input too, so the agent sees the transformation you expect. Keep examples realistic and free of anything confidential, since the file may be shared later.
Good skills state their limits. If the skill should never send anything without approval, say so. If it should stop and ask when the input is missing a key detail instead of guessing, say that too. Instructions about when not to act are among the most valuable lines you can write, and they are the ones most people forget.
Good skills stay current. A skill that encodes a process, a style guide, or a tool's behavior goes stale when those change. Put a note in the file about what version or date it was written against, and revisit it when the underlying thing changes. Keeping the folder under version control with Git makes this easy, because you can see exactly what changed and roll it back.
Honest limits
What skills do not do, and how this relates to Claude
A skill is guidance, not a guarantee. The agent reads your instructions and usually follows them, but it can misread, skip a step, or apply a skill where it does not fit. Anything with real consequences, such as sending messages, deleting files, or spending money, should keep a human confirmation step, and you should review what the agent did, not just trust that the skill worked.
A skill also does not make the underlying model smarter. It supplies your context and your preferred method. If the model cannot do a task reliably without the skill, a skill will help it do the task in your style, but it will not remove the limit. Test on realistic cases before you depend on it.
Finally, a note on scope. This page is about the skills system in Hermes Agent from Nous Research. Claude, from Anthropic, has its own agent-skills system, and the two are separate products with their own documentation, so do not assume a setting, folder, or command from one exists in the other. Nightschool AI is an independent learning site, and mentioning Hermes Agent here describes a tool you may be curious about, not an endorsement of it or any relationship with its makers. The transferable lesson is the craft: writing clear, narrow, testable instructions is the skill that matters in any agent.
Get better at instructing any AI agent
Reading about skills and writing skills that work are different things. The free Nightschool AI curriculum is hands-on from the first lesson, and the instruction-writing habits you build there carry over to any agent you use.
Frequently Asked Questions
What is a skill in Hermes Agent?
A skill in Hermes Agent is a folder containing a SKILL.md file of instructions for the agent, following the open agentskills.io standard. It packages a repeatable job, such as writing a status update or following a team's commit style, so you do not re-explain it each time. Installed skills live in ~/.hermes/skills/ and each one becomes a slash command inside the agent.
Where are Hermes Agent skills stored?
Installed skills are stored in the ~/.hermes/skills/ directory on your machine, with one folder per skill. Each folder holds a SKILL.md file. Because it is an ordinary directory, you can list it to see what your agent can do, open any SKILL.md to read exactly what it instructs, and delete a skill's folder to remove it.
How do I use a Hermes Agent skill once it is installed?
Every installed skill automatically becomes a slash command inside Hermes Agent, so you call it by name in the same way you would any other slash command. The agent then follows the skill's instructions for your request. Because of progressive disclosure, the agent also loads a skill's fuller instructions when it is relevant to your task.
What does progressive disclosure mean for skills?
Progressive disclosure means the agent loads the fuller instructions inside a skill only when that skill is relevant to the current task, instead of loading every skill's full text up front. That keeps token usage down. For you as an author, it means the short description at the top of a skill matters most, since it helps the agent decide whether to open the rest.
How do I write my first Hermes Agent skill?
Pick a job you repeat weekly. Create a folder in ~/.hermes/skills/, add a SKILL.md with a short metadata block naming the skill and saying when to use it, then write the goal, ordered steps, the expected output format, and one good example. Run it through its slash command on real input, read the result critically, and edit the file until it behaves.
What does the /learn command do?
As reported in coverage of the docs, /learn has the agent draft a SKILL.md from source material you point it at, such as a documentation page, a local SDK, a past conversation, or pasted notes. Treat the result as a first draft: it reflects its source, including gaps and outdated advice, so read it, edit it, and test it before relying on it.
Are skills from the Skills Hub safe to install?
There is no blanket answer, and that is why reading matters. A skill is prompts and sometimes executable instructions from whoever published it, so installing one means running another person's instructions inside your agent. As general agent-skills practice, read the SKILL.md and any scripts in the folder before enabling it, and look for commands, network requests, and requests for credentials.
What should I look for when reviewing a skill someone else wrote?
Check that the instructions match the stated purpose. Look for shell commands, scripts in the folder, network requests, and any request for API keys or credential files. Check whether it reaches outside your project folder, and treat any instruction to hide actions, skip confirmation, or override your own instructions as a reason not to install it.
Is the agentskills.io format the same as Claude's skills?
Hermes Agent follows the agentskills.io open standard, but its skills system is a separate product from Claude's skills, with its own documentation, folders, and commands. Do not assume a path or setting from one exists in the other. Check each tool's own documentation, and treat the shared idea of clear, narrow, testable instructions as the part that transfers.
Can I give the Hermes Agent docs to another AI model?
Yes. The Hermes Agent documentation site publishes llms.txt and llms-full.txt versions of the docs, which are plain-text files intended to be fed to a model. You can paste the contents into an assistant and ask questions about Hermes Agent, getting answers grounded in the project's own documentation rather than in guesses.
Write instructions that work
The best agent skill is just a clear paragraph you were willing to write down.