Tutorial 19: Skills System — Making AI Smarter

This is part of the Hermes Agent official tutorial series. View all tutorials

Imagine your AI assistant is like a new employee. They’re smart, but they don’t know everything about your company yet. Skills are like instruction manuals you hand them only when they need to do a specific task — instead of making them memorize every manual upfront, they pull one off the shelf when the job calls for it. That’s exactly what the Skills System does for Hermes Agent.

What Are Skills?

Skills are simple knowledge documents that your agent loads on demand. Think of them as cheat sheets. They follow a “progressive disclosure” pattern — the agent only reads the details when it actually needs them, which saves memory and keeps things fast. All skills live in a special folder on your computer: ~/.hermes/skills/.

Step 1: Starting Fresh (Optional)

By default, Hermes comes with a set of pre-installed skills. But maybe you want a clean slate — no bundled skills at all. Here’s how:

During installation: the installer has no --no-skills flag. Its setup stage asks whether to seed the bundled catalog when you pick the Blank Slate setup; answering no writes the opt-out marker described below. Non-interactive installs seed the catalog, so run hermes skills opt-out afterwards if you want the profile empty.

When creating a new profile:

hermes profile create research --no-skills

On an already-installed profile:

hermes skills opt-out            # stop future skills from being added
hermes skills opt-out --remove   # also delete unmodified bundled skills
hermes skills opt-in --sync      # undo and re-add skills

Safe by default: opt-out only stops future additions — it never deletes anything. The --remove flag only deletes skills you haven’t edited. Your custom skills are always safe.

All of these paths write a .no-bundled-skills marker into the profile directory. While the marker is present, the installer, hermes update, and any skill sync all skip bundled-skill seeding for that profile. Delete the marker (or run hermes skills opt-in) to re-enable.

Step 2: Using Skills — Slash Commands

Here’s the magic: every installed skill automatically becomes a slash command. Just type /skill-name followed by your request:

/gif-search funny cats
/plan design a rollout for migrating our auth provider
/excalidraw

The last one loads the skill and lets the agent ask what you need. Simple as that!

Step 3: Stacking Multiple Skills

Need more than one skill at once? Chain them together at the start of your message (up to 5):

/github-pr-workflow /test-driven-development fix issue #123 and open a PR

The agent loads both skills, then uses the rest of your message as instructions. Clever, right?

A helpful tip: The parser stops at the first word that isn’t a skill. So if you have a file path like ~/.hermes/cache/scratch/scan.pdf, it won’t get confused:

/ocr-and-documents ~/.hermes/cache/scratch/scan.pdf extract the tables   # loads one skill, the path is the argument

Step 4: Skill Bundles (For Repeated Combinations)

If you find yourself using the same skill combo over and over, create a skill bundle — one short command that loads multiple skills at once. It’s like making a playlist instead of picking songs one by one. The bundled plan skill is a great example of this.

Step 5: Browsing and Installing in Desktop

Open Capabilities → Skills and switch between Installed and Browse. Search stays at the top, and the tab switch and actions share one row. Installed reads the selected profile’s actual skills and enabled state — it isn’t inferred from the public catalog. Browse is a native catalog UI, not an embedded website or a second, smaller catalog.

Desktop and the public Skills Hub read the same published CDN snapshot: /docs/api/skills.json. Browsing doesn’t crawl GitHub or query upstream marketplaces live; installation still retrieves the selected skill through its source’s installer.

The Skills Hub has an Install in Hermes button on each installable card. It opens the installed Hermes Desktop app with a URL-encoded, source-qualified target — for example, official/... for optional skills or clawhub/... for ClawHub. Bundled skills use an explicit repository path rather than an ambiguous bare name. The same target powers native Browse and the card’s CLI fallback:

hermes://skill/install?identifier=official%2Fsecurity%2F1password

Hermes shows Install “skill-name”? with separate Source and Install to rows. Cancel makes no changes. After you confirm, the dialog shows Installing…, then Installed and a completion notification. Errors stay in the dialog so you can read them and retry, and installation still runs through the usual Skills Hub pipeline — security scan, action log, and installed-list refresh. If you switch profile or connection while the confirmation is open, reopen the link for the new destination; a link can’t bypass scanning or pick a different profile. Open conversations are told about the new skill on their next message.

The skill/install route needs an updated Desktop build. If the app is missing or the link isn’t recognized, update Desktop or expand the card to copy its CLI install command instead.

A note on rate limits: Skills Hub operations use the GitHub API, which allows 60 requests/hour for unauthenticated users. An install costs about two API calls (the repo and its file tree); the skill’s files themselves download from raw.githubusercontent.com, which the limit does not count. If you see rate-limit errors during install or search, set GITHUB_TOKEN in your .env file to raise the limit to 5,000 requests/hour. The error message includes an actionable hint when this happens.

Step 6: Where Skills Live and Which One Wins

Skills can come from more than one directory, so Hermes uses a fixed precedence order to decide which copy wins:

project → local (~/.hermes/skills/) → skills.create_dir → external_dirs

If the same skill name exists in more than one directory, the higher-precedence directory wins everywhere — the skill index, skills_list, hermes skills list, skill_view, slash commands, -s preload, and cron. The hidden copy is logged as shadowed.

Project skills are the highest-precedence tier. A project skill named deploy overrides a same-named profile or bundled skill for sessions inside that repo — that’s the point: vendored repo skills win on their home turf, without touching your global profile. Project skills are tagged [project] in the agent’s skill index so provenance stays visible.

Duplicate skill names

Every surface resolves a skill name the same way:

• Across directories, the higher-precedence directory wins (project → local → skills.create_dir → external_dirs), including for the same relative path (productivity/xdup local and external loads the local copy). The shadowed copy is hidden and a warning is logged.
• Inside one directory, two different skills that share a name are never guessed between. Both are listed under their exact relative path (for example a/one and b/two), and loading the bare name fails with Ambiguous skill name dup-demo: use one of a/one, b/two. That message is also what hermes -s dup-demo and cron jobs report. Identical copies of one skill (a symlink view or byte-identical copy) resolve to the shallowest path.

Plugin skills use their own plugin:skill names and never collide with these.

Skills added during a conversation

The list of skills the agent picks from is part of the conversation’s system prompt, which stays fixed so the provider’s prompt cache keeps working. When a skill is installed, created or removed while a conversation is open (from the Skills Hub, hermes skills install in another terminal, a plugin, the curator, or the agent itself), your next message to the agent carries a short note naming the new skills with their descriptions and the removed ones. The note is sent once per change; the system prompt itself picks up the change at the next compaction. /reload-skills is not needed for this — it still refreshes the /skill-name slash commands.

Key Takeaways

• Skills = on-demand knowledge — loaded only when needed, saving tokens and time
• All skills live in ~/.hermes/skills/ — easy to find, add, or remove
• Slash commands make skills instant — just type /skill-name and go
• Stack up to 5 skills in one command for complex tasks
• Opt-out for a clean profile — perfect for specialized use cases
• Precedence matters — project → local → skills.create_dir → external_dirs; project skills win inside their repo
• Ambiguous names fail loudly — two different skills with the same name inside one directory require the full relative path
• Open conversations stay in sync — new or removed skills are announced on your next message, no reload needed

Summary

The Skills System is like giving your AI a well-organized toolbox. Instead of carrying every tool at once, it picks exactly what it needs for the job. Whether you’re generating GIFs, planning migrations, or creating pull requests, skills make Hermes Agent smarter, faster, and more efficient — without wasting resources.

Next up: Tutorial 20 — Persistent Memory: giving Hermes a long-term memory that survives across sessions.