AI AGENTS

How To Write Hermes Agent Skills That Actually Compound

The SKILL.md format, the self-improvement loop, the Curator, and the delegation patterns that make a skill get sharper every time it runs.

You wrote your first batch of Hermes Agent skills the way the tutorials told you to… decent frontmatter, a clean procedure, a couple you actually tuned by hand.

A week later you open one of them and your edits are gone.

The agent rewrote it, not maliciously. It just hit a checkpoint, decided it knew better, and regenerated the file over your work.

So now you’re stuck in this loop: the self-improvement is real, but it overwrites the parts you cared about, and you can’t tell which skills are getting sharper and which are quietly rotting.

The skills that survive are the ones written so the loop extends them instead of flattening them, and getting that one property right is the gap between a skill library that compounds and one that just runs.

Here’s exactly how to write for it.

A Skill Is A SKILL.md Folder, Not Code

First thing that trips people up: a skill isn’t a script. It’s a folder with a markdown file in it.

It lives at ~/.hermes/skills/<category>/<skill-name>/SKILL.md, following the open agentskills.io spec.

That's the same format other agents read, which matters more than it sounds, and I'll come back to why at the end.

The frontmatter is short. Only two fields are actually required:

• name (lowercase-with-hyphens, because it becomes the slash route you call the skill with)
• description (one line, this is what the agent reads to decide whether to fire the skill at all)

Everything else is optional: version, platforms, metadata.hermes.tags, and any toolset or credential gates you want to declare.

No code required to write a good one, the whole thing reads like a runbook you'd hand a competent coworker.

Skill Or Memory?

People dump things into skills that should be memories, and vice versa. Quick test that’s never failed me:

If it’s a reference document the agent should consult to do a repeatable job, it’s a skill. “How I format a weekly client report.” “The steps to pull and clean Shopify order data.”

If it’s a sticky note, a fact about you or your setup that the agent should just know, it’s a memory. “I prefer metric units.” “My main project is called Northwind.”

Two more rules that keep skills usable… scope each one to a single job, not a sprawling domain. And keep the body under roughly 5,000 tokens, because the entire file loads into context the moment the skill fires.

A fat skill taxes every single run, whether it earns that cost or not.

The Twist That Should Shape How You Write Them

Hermes writes skills itself. Roughly every 15 tool calls, the agent pauses, reflects on what just worked and what just failed, and either generates a new SKILL.md or rewrites an existing one in that same folder.

It's the documented learning loop, the thing Nous Research built the agent around.

The detail that changes how you should write: hand-written and machine-written skills share one format and one path.

There’s no separate “user skills” folder the agent leaves alone.

When you author a skill well, you’re not just writing instructions for today’s task, you’re handing the loop a clean template it can extend.

Write a vague one and the loop has garbage to build on.

Write a sharp one and it gets sharper on top of your structure.

The Curator Is The Discipline Layer

There’s a second process running underneath. The Hermes Curator runs periodically (think weekly housekeeping) and prunes the library.

It archives skills that have gone stale and merges narrow ones into broader skills.

So your skill isn’t just competing to be useful, it is competing for shelf space against a process that’s actively trying to consolidate the library.

A skill that’s too narrow and rarely fires is archive bait, a skill that overlaps three others is merge bait.

You’re writing for two readers now: the task in front of you, and a librarian that’s quietly reorganizing everything you’ve made.

[embed]Hermes Agent: The Complete Setup Guide (Telegram, Discord, VPS — No Mac Mini Required) Set up Hermes Agent on a cheap VPS in under an hour. Install, model selection, Telegram setup, Skill Documents, and…medium.com

Anatomy Of A Skill That Compounds (Versus One That Just Works)

A skill that “works” runs once and produces output. A skill that compounds gives the loop something to measure, credit, and refine. Five things separate them.

A sharp activation contract

The description field plus the When to Use section are the attribution layer. The loop can only credit or blame a skill if it knows when that skill was supposed to fire.

Vague trigger language ("helps with research") means the agent fires it at the wrong times, the results are mixed, and the loop can't tell whether the skill is good or the targeting is bad.

Tight trigger language ("use when the user asks for a competitor scan across more than three sources") gives the loop clean signal.

A Verification block, the load-bearing piece

If you carefully write one section of any skill, write this one.

The Verification block defines what “done” and “failed” look like for the task.

Without a done/fail signal, the loop has nothing to optimize against.

It can rewrite the skill all day and never know whether it made it better or worse… a skill with no verification step doesn’t compound, it just drifts.

Make it concrete. “Output contains at least 5 sourced claims, each with a URL and a date.” “The file saved to the target path and is non-empty.”

Something the agent can actually check, not vibes.

A Pitfalls section, where compounding literally lives

This is where the magic is, if there’s any magic here at all.

Every failure you record in Pitfalls is a failure the agent never has to relearn.

Run 1 hits a rate limit because it fired requests too fast, you write that down.

Run 30 already knows to throttle. The compounding isn’t abstract “the agent gets smarter.” It’s a Pitfalls list that grows one hard-won line at a time.

Some ecosystem builds (Super Hermes, for one) formalize this as blind-spot tracking, but you get most of the benefit just by maintaining the section by hand early on and letting the loop add to it.

An ordered Procedure with determinism pushed into scripts/

Number your steps. A numbered Procedure is something the loop can edit surgically, swapping step 4 without touching the other six.

A wall of prose is something it has to rewrite wholesale, which is exactly when your good lines get lost.

Push the mechanical work down into a scripts/ folder beside the SKILL.md. API calls, parsing, anything deterministic.

That way the agent's refinement energy concentrates on the judgment steps, the parts that actually need a model, instead of rewriting boilerplate it could have just called.

Narrow scope, so the Curator keeps it alive

Back to the librarian. One job per skill.

A skill that does “research and write and publish” is three skills wearing a trenchcoat, and the Curator will eventually try to split or merge it, usually at the worst time.

Narrow skills survive housekeeping, sprawling ones get rewritten by a process you didn’t invite.

Here’s the skeleton I start every skill from:

---
name: competitor-scan
description: Use when the user asks for a multi-source competitor
  scan and wants a single brief back, not raw pages.
version: 0.1.0
---

## When to Use
Trigger on requests like "scan what X is doing" across 3+ sources.
Do NOT use for a single-page lookup, that's a one-shot web fetch.

## Quick Reference
Inputs: competitor name(s), focus area.
Output: one brief, max ~400 words, dated, sourced.

## Procedure
1. Confirm the focus area and source count with the user.
2. Delegate the heavy reading (see scripts/ and the delegation note).
3. Collect returned summaries only, never raw pages.
4. Synthesize into the brief format in Quick Reference.
5. Run Verification before returning anything.

## Pitfalls
- Sources without dates sneak in. Reject undated claims.
- (loop appends failures here over time)

## Verification
- Brief contains 5+ claims, each with a URL and a date.
- Word count under 400. If over, compress, do not truncate.

That’s the shape the loop can read, credit, and grow.

The Manual-edit-overwrite Trap (And When To Lock A Skill)

Now the thing that ruins people’s afternoon.

You hand-tune a skill, it’s perfect.

The agent runs, hits its ~15-action checkpoint, decides to “improve” the file, and silently regenerates it.

Your tuning is gone, because authored and machine-written skills share one path and one format and the loop doesn’t know one of them was sacred.

The slower version of the same trap: the Curator merges your skill into a broader one during housekeeping, and your careful edges blur into something generic.

The property that makes skills compound is the exact property that overwrites you.

You can’t have self-improving skills and immutable skills at the same time without deciding, per skill, which one you want.

So the real question was never “how do I stop overwrites.” It’s which skills does the loop own, and which do I own.

How To Avoid It

Decide ownership up front, skill by skill. Then back that decision with mechanics:

1. Run git init inside ~/.hermes/skills/. This is the single highest-value move. An overwrite stops being a loss and becomes a revertable diff.

You can literally see what the loop changed and roll it back.

Commit after every manual edit so there's always a clean point to return to.

2. Bump the version field whenever you hand-edit. It signals intent and gives you a marker to diff against.

3. Keep author-owned skills narrow, so they’re less likely to get pulled into a Curator merge.

4. Freeze by distribution. Once a skill is finished, publish it to a repo and install it back from there.

A skill that arrives as a packaged, installed dependency sits outside the mutable working path, so the loop treats it as a fixed reference instead of a draft to rewrite.

This is the cleanest “lock” I’ve found that I can actually verify works.

Delegation And Subagents For Near Zero-context-cost Pipelines

The other half of writing skills that compound is writing them so they don’t choke the agent on long runs.

The scarce resource here is not compute. It’s the main agent’s context window.

Inline pipelines, where one agent scrapes five pages, reads them all, and reasons over the raw text in a single window, flood that context with intermediate junk.

That’s what degrades a long-running agent, not difficulty… volume.

Use A Shared Evidence Vault

The documented pattern (shipped with the v0.13.0 multi-agent orchestration) isn’t passing giant messages between agents.

It’s a shared evidence vault.

An upstream research agent scrapes and structures findings into the vault.

Downstream agents (a main agent, a coder, a content agent, a QA pass) each query only the slice they need, nobody pipes a wall of raw text into anybody else’s context.

Let The Orchestrator Handle Decomposition

You don’t hand-split the work, an orchestrator does.

The cleanest example is Kanban-style triage: you drop one prompt into a triage column, the orchestrator breaks it into subtasks and routes each one.

The main context holds the plan and the results.

The actual doing happens out in subagents, in their own windows, where the mess stays contained.

Anti-patterns To Avoid

The fast way to learn this is to skip the mistakes I already made:

1. Returning raw subagent output to the main context. The cardinal sin. It just relocates the bloat instead of removing it. The subagent has to return less than it consumed, or the whole pattern is theater.
2. Over-decomposition. An orchestrator plus five subagents for a three-step task. You’ve added routing overhead to save nothing.
3. The vault as a junk drawer. Store structured findings, not whole pages. A vault full of raw HTML is just slow context with extra steps.
4. No QA gate. One silent failure upstream poisons the vault, and every downstream agent confidently builds on a wrong fact. Gate it.
5. The kitchen-sink skill. Curator merge-bait and a fat body that loads into context on every activation. Both costs, no upside.
6. Confusing skill versus memory inside the pipeline, so preferences get baked into procedures where they can’t be reused.
7. Forgetting these skills are still loop-mutable. Even your delegation skills can get rewritten. Same ownership rules apply.

The throughline tying all seven together: delegation only saves context if every boundary returns less than it consumed.

If a step hands back more than it took in, you didn’t delegate, you just added a hop.

Where To Find Templates, And How To Publish

You don’t have to start from a blank file, the official skills double as templates worth reading.

The Shopify skill handles product, order, and inventory work over GraphQL.

HeyGen HyperFrames installs in one line (hermes skills install hyperframes).

xAI's xurl skill wires Hermes to X.

Copy the structure, swap the specifics.

When yours is good enough to share, publishing is one command, and it’s deliberately gated:

hermes skills publish skills/<category>/<name> \
  --to github --repo your-org/repo

Opening the PR triggers an automated security scan (data-exfiltration, prompt-injection, destructive-command, and supply-chain checks) before anyone can install it.

That gate is the reason the skill ecosystem is worth trusting at all, given everything that’s been happening with agent supply chains this year.

For scale: HermesHub aggregates somewhere around 672 skills across roughly 18 categories, spanning built-in (~90), official-optional (~81), and 500-plus community skills.

It’s smaller than OpenClaw’s integration ecosystem, which is the other recurring honest complaint, but it’s growing fast and the published ones are scanned, which OpenClaw’s sprawl can’t fully claim.

Conclusion

You don’t need a perfect skill library… you need four moves, in order:

1. **git init your ~/.hermes/skills/ folder today.** Before anything else. This alone turns every future overwrite from a loss into a diff.
2. Add a real Verification block to your three most-used skills. Concrete done/fail signals. This is what gives the loop something to compound against, and it’s the fastest upgrade you can make.
3. Pick one heavy skill and rewrite its expensive step to delegate to a subagent that returns a summary, not raw pages.
4. Decide ownership on every skill that touches money, credentials, or anything shared, and freeze those by distribution.

One quick caution on the example skill and tool names above.

The SKILL.md format, the vault, and the subagent pattern are documented, but the exact tool identifiers (subagent, vault, web) and the spawn syntax shift between versions.

Run hermes skills inspect against your loaded toolset and reconcile the names before you trust the skeleton verbatim. The structure is right, but the literal identifiers are the thing to check.