Skills — the self-improvement loop

The pitch: skills are field manuals, not new gadgets

In Module 3 we met tools — actual code that gives the loop a new ability (read a file, search the web, run a command). A skill is different in kind. A skill doesn't add an ability; it adds better instructions for using abilities the agent already has. It's the difference between handing someone a power drill and handing them the step-by-step guide for hanging a cabinet straight.

The toolbox vs. the field manual — Tools are what's in the toolbox — the drill, the saw, the level. Skills are the field manuals and recipes that sit next to the toolbox: "here's how we change brake pads," "here's our house style for a research brief," "here's the exact arXiv query syntax." The drill never changes. What makes someone a pro is knowing which tool to reach for, in what order, with what gotchas. Skills are how you teach Hermes that — in plain English.

Because a skill is pure Markdown, this is your highest-leverage on-ramp into the whole codebase. You don't have to understand the agent loop to make Hermes dramatically better at your domain. You just have to write down how the job is done.

What a skill physically is

A skill is a directory living under your data folder (remember ~/.hermes/ from Module 1), optionally nested in a category:

~/.hermes/skills/                  # your skills live here
└── research/                      # optional category folder
    └── arxiv/                     # the skill name
        ├── SKILL.md               # REQUIRED — the only mandatory file
        ├── references/            # optional: extra docs to load on demand
        ├── templates/             # optional: starter files / boilerplate
        ├── scripts/               # optional: helper scripts the skill calls
        └── assets/                # optional: images, data, fixtures

Only SKILL.md is required. The bundled skills that ship with Hermes live in the repo's skills/ folder (you saw the category list — research, github, devops, and more); your hand-authored ones go in ~/.hermes/skills/. Same format, two homes — exactly the program-vs-data split from Module 1.

The SKILL.md format: frontmatter + a body

A SKILL.md has two parts: a block of YAML frontmatter between two --- lines, and then a normal Markdown body. The frontmatter is metadata about the skill; the body is the skill. Here's the real frontmatter from the bundled arXiv skill (skills/research/arxiv/SKILL.md):

---
name: arxiv
description: "Search arXiv papers by keyword, author, category, or ID."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [Research, Arxiv, Papers, Academic, Science, API]
    related_skills: [ocr-and-documents]
---

# arXiv Research

Search and retrieve academic papers from arXiv via their free REST API…

Don't let the field count scare you. Only two fields are required: name and description. Everything else — version, author, license, platforms, and the metadata.hermes block with tags and related_skills — is optional polish that helps with discovery and sharing. The description is the single most important line you'll write, and the next section explains exactly why.

The body below the frontmatter is where the value lives: in the arXiv skill it's quick-reference tables, copy-paste curl commands, query syntax, and a full research workflow. That's the procedural knowledge the agent reads when it needs to actually do the thing.

Progressive disclosure — why hundreds of skills stay cheap

Here is the idea that makes the whole system work. The agent does not stuff every skill's full text into its context window. That would be enormous and expensive. Instead, the system prompt carries only a compact index — each skill's name plus its one-line description — assembled by agent/prompt_builder.py. The full SKILL.md is loaded only when that skill is actually needed.

Glossary: progressive disclosure — Progressive disclosure = showing the model a tiny summary of everything up front, then loading the full detail of one thing only at the moment it's required. The agent always knows a skill exists (it sees the name + description), but it only pays the token cost of the full how-to when it decides to open it. This is the trick that lets Hermes ship with hundreds of skills without bloating every single prompt.

This is also why your description matters so much. It's the only thing the model sees by default, so it's what the model uses to decide "is this the skill I need right now?" A vague description means a great skill never gets opened. Write the description like a search result for your future agent.

Using a skill

There are two ways a skill gets pulled into a conversation:

• You invoke it explicitly. Type /<skill-name> (e.g. /arxiv) and the skill's content is injected into the conversation. This is handled by agent/skill_commands.py. It's the same family of slash commands as /skills (list them) from Module 1.
• The model decides on its own. Seeing the index, the model can choose to load a skill via a skill tool when a task calls for it — no slash command from you required. Progressive disclosure in action: it reads the one-liner, decides it's relevant, then opens the full file.

When a skill is loaded, Hermes runs a quick preprocessing pass first: template tokens like ${HERMES_SKILL_DIR} (and ${HERMES_SESSION_ID}) get swapped for real paths, so a skill can reliably point at its own scripts/ or assets/ no matter where it's installed. You'll see this referenced in agent/skill_preprocessing.py.

The self-improvement loop (the headline)

Now the part that makes Hermes genuinely unusual. The agent can create and edit its own skills. There's a skill-management tool — tools/skill_manager_tool.py — that exposes actions like create, edit, and patch. So after the agent grinds through a hard, multi-step task, it can capture the procedure it just figured out as a brand-new skill. Next time, it doesn't re-derive — it reads its own notes.

Left alone, self-written skills would pile up and rot. So a background curator (agent/curator.py) periodically tends the garden. Crucially, it tracks provenance — it knows which skills the agent made versus which you hand-wrote — so by default it only touches the agent's own. It:

• marks unused skills stale after ~30 days (DEFAULT_STALE_AFTER_DAYS = 30),
• archives very stale ones after ~90 days (DEFAULT_ARCHIVE_AFTER_DAYS = 90) — reversibly; it never deletes, and the archive is recoverable,
• and can patch or merge overlapping skills so the library stays tidy.

Put it together and you get a flywheel — the agent learns from doing, and the curator keeps the learnings healthy:

+-----------------------------------------------------+
|  THE SELF-IMPROVEMENT LOOP                          |
|                                                     |
|   1. do a hard task   -->   2. capture it as a skill|
|      (the agent loop)         (skill_manager_tool)  |
|          ^                              |           |
|          |                              v           |
|   4. curator keeps it   <--   3. reuse it next time |
|      healthy (curator.py)        (cheap, instant)   |
|      stale->archive, merge,                         |
|      never deletes                                  |
+-----------------------------------------------------+

You stay in control — This is opt-out, not a runaway process. You can pause the curator, or pin a skill so it's never touched, with commands like hermes curator pause / pin (see the curator docs). And remember: it only manages agent-created skills by provenance — your hand-authored skills are left alone unless you say otherwise.

Sharing: the Skills Hub

Skills are portable, so there's an ecosystem around them. The Skills Hub lets you discover and distribute skills from the command line:

hermes skills search "competitor research"   # find skills
hermes skills install <name>                 # add one to ~/.hermes/skills
hermes skills publish <name>                 # share one you wrote

You can also add a GitHub repo as a source — a "tap" — so a team's shared skills flow in. Installed skills are security-scanned before they land, since a skill can contain scripts. And Hermes is built to the open agentskills.io standard, so skills aren't locked to one agent — a well-written SKILL.md is a portable asset. See the work-with-skills guide for the full workflow.

Author one by hand

Let's actually make one. The whole exercise is four steps and a text editor. (Full reference: the skill template, and the official creating skills docs.)

1. Make the directory.

   mkdir -p ~/.hermes/skills/<category>/<name>

   e.g. mkdir -p ~/.hermes/skills/research/competitor-brief.
2. Create SKILL.md. Start with --- frontmatter (just name + description at minimum), then write a Markdown body with clear, ordered steps and concrete examples — exactly like the arXiv skill's quick-reference tables and commands.

   ---
   name: competitor-brief
   description: "Produce a one-page competitor brief in our house format."
   ---
   
   # Competitor Brief
   
   When asked for a competitor brief, follow these steps:
   
   1. Search the web for the company's pricing, positioning, recent news.
   2. Fill the template below — keep each section to 3 bullets.
   3. End with a one-line "so what" for our product.
   
   ## Template
   - **Who they are:** …
   - **Pricing:** …
   - **Strengths / gaps:** …
   - **So what for us:** …

3. (Optional) add supporting files. Drop reusable boilerplate in templates/, deeper docs in references/, helper code in scripts/, fixtures in assets/. Reference them from the body using ${HERMES_SKILL_DIR} so paths resolve anywhere.
4. Use it. Start Hermes and type /<name> — e.g. /competitor-brief. The body is injected and the agent follows your steps. (Or just ask for "a competitor brief" and let progressive disclosure pull it in.)

Two constraints to respect — The skill name must be lowercase and match ^[a-z0-9][a-z0-9._-]*$ (start with a letter or digit; then letters, digits, dots, hyphens, underscores). And a single SKILL.md can be up to ~100,000 characters (MAX_SKILL_CONTENT_CHARS = 100_000 in tools/skill_manager_tool.py) — generous, but if you're brushing it, split detail into references/ and let the body point there.

Why this is your best on-ramp

Start here if you want to extend Hermes — Of every extension point in this series, writing skills is the highest leverage for the least effort. No Python, no rebuild, no understanding of the loop's internals — just a Markdown file describing how a job is done in your domain. And the meta-move: you can literally ask your AI to draft the SKILL.md for you, review it, drop it in ~/.hermes/skills/, and you've taught Hermes a new specialty in five minutes. This is the on-ramp. Take it before anything else.

Key takeaways

• A skill = procedural knowledge in Markdown. Tools add abilities (code); skills add better instructions for using them.
• It's a directory with a required SKILL.md (YAML frontmatter + body) plus optional references/ templates/ scripts/ assets/. Only name + description are required.
• Progressive disclosure: the prompt carries only a name+description index (prompt_builder.py); the full file loads on demand. That's why hundreds of skills stay cheap.
• Invoke with /<name> (skill_commands.py) or let the model load it itself; ${HERMES_SKILL_DIR} resolves paths.
• The agent writes its own skills (skill_manager_tool.py); a curator (curator.py) marks stale (~30d), archives (~90d, reversibly), and merges — never deletes, and you can pause/pin.
• Share via the Skills Hub / open agentskills.io standard. Writing skills is the easiest way to make Hermes better at your domain.

Quick check — You wrote a great skill but the agent never uses it on its own. Nothing's broken. What's the most likely fix?

Answer: Sharpen the description. Because of progressive disclosure, the model only sees each skill's name + one-line description in the prompt index — it never sees the body until it decides to open it. If the description is vague, the model can't tell the skill is relevant, so it never loads it. The description is the skill's "search result"; make it concrete and keyword-rich. (You can always force it with /<name> in the meantime.)

Pair with your AI — let the agent draft your first skill — the meta-move from the on-ramp above: "Draft a SKILL.md for a skill called weekly-standup that turns my git log + open PRs into a 5-bullet standup update in my voice. Use valid YAML frontmatter with just name and description, then a clear step-by-step body with an example. Keep the name matching ^[a-z0-9][a-z0-9._-]*$. Then tell me the exact mkdir + file path to drop it into ~/.hermes/skills/."