Writing Your First Hermes SKILL.md: YAML Frontmatter Spec Reference

A Hermes skill is a markdown file with YAML frontmatter and a handful of optional subfolders. That is the whole format. It is not a DSL, not a plugin archive, not a binary package. You write it in your editor, drop it into ~/.hermes/skills/, and the agent loads it on the next run.

This tutorial walks you through building a real skill from scratch: a weekly review procedure you can trigger by name. We will cover the full frontmatter spec, the body structure, and the conventions that make a skill portable between Hermes and Claude Code.

Key Takeaways

• Hermes skills follow the agentskills.io open standard, the same format used by Claude Code, Cursor, and Codex.
• A skill is one markdown file with required YAML frontmatter plus optional scripts/, templates/, and references/ subfolders.
• The description field uses the "Use when..." pattern borrowed from Claude Code conventions.
• metadata.hermes.tags and related_skills are the Hermes-specific fields most likely to need adjustment when porting from Claude Code.
• Skills live under ~/.hermes/skills/{category}/{skill-name}/SKILL.md by convention.
• Hermes loads skills lazily; putting a skill in the directory is enough, no registration step.
• Format compatibility between Hermes and Claude Code is real, but minor tag tweaks may be needed — plan on a quick pass rather than a straight copy.

The Scenario

We are going to build weekly-review: a skill that guides the agent through a Friday end-of-week retrospective, summarizing what shipped, flagging what is stuck, and drafting Monday priorities. It is a realistic example because the procedure is too repetitive to keep retyping and too situational to hard-code.

Step 1: Create the Directory

Hermes expects skills organized by category under ~/.hermes/skills/. For a productivity skill:

mkdir -p ~/.hermes/skills/productivity/weekly-review
cd ~/.hermes/skills/productivity/weekly-review

Inside a skill directory you will typically have:

• SKILL.md — the main file, required
• templates/ — any markdown templates the skill writes into (optional)
• scripts/ — executable helpers (optional)
• references/ — long reference material the skill loads on demand (optional)

For this tutorial we will stick to SKILL.md and one template.

Step 2: Frontmatter, Line by Line

Here is the complete frontmatter for our weekly-review skill. Copy this and we will walk through every field.

---
name: weekly-review
description: Use when the user asks for a weekly review, Friday retrospective, or end-of-week summary. Pulls commits, open PRs, calendar events, and drafts Monday priorities.
version: 0.1.0
author: Jason at aiskill.market
license: MIT
metadata:
  hermes:
    tags: [productivity, reviews, weekly, retrospective, planning]
    related_skills: [daily-standup, monthly-review, goal-tracking]
---

Required Fields

• name — the skill identifier. Lowercase, hyphens, no spaces. Must match the directory name for clarity.
• description — when Hermes should use this skill. The "Use when X" pattern is the convention because it tells the model how to match user intent. Keep it under 200 characters.
• version — semantic version. Bump on material changes.
• author — your name, handle, or organization. This shows up when the skill is shared.
• license — MIT is the default; pick whatever fits your distribution plans.

Hermes-Specific Metadata

• metadata.hermes.tags — flat list, used for search and filtering inside hermes skills list.
• metadata.hermes.related_skills — a short list of other skills the agent might chain to. Hermes uses these as soft hints, not hard dependencies.

Comparing to Claude Code

Claude Code's skill format uses the same top-level fields. The one material difference is the metadata.hermes block; Claude Code looks for metadata.claude_code if you want runtime-specific hints. Removing or renaming that block is usually the only change needed when moving a skill between the two. See are Claude Code skills portable to Hermes for the full portability story.

Step 3: Write the Body

Below the frontmatter, write the skill as plain markdown. Hermes injects this content into the agent's context when the skill activates, so treat it like a prompt you are handing to a new contractor.

# Weekly Review

## Purpose

Run a Friday retrospective that answers four questions:

1. What shipped this week?
2. What is stuck, and why?
3. What did I learn?
4. What are my top three priorities for Monday?

## Procedure

1. Pull the last 7 days of git commits from every repo in `~/code/`.
2. Fetch open PRs authored by the user from GitHub.
3. Scan the calendar for the past week (if calendar tool is available).
4. Summarize each question with bullet points and specific references.
5. Write the result to `~/notes/weekly-reviews/{YYYY-MM-DD}.md` using `templates/review.md`.
6. Print a condensed version to the chat.

## Constraints

- Do not guess. If a tool returns nothing, say "no data" rather than hallucinate.
- Every claim about what shipped must cite a commit SHA or PR number.
- Keep the Monday priorities list to exactly three items.

## References

- See `references/example-output.md` for a well-formed review.

Notice the structure: purpose, procedure, constraints. This is not mandatory, but it reliably produces good agent behavior. The constraints section is especially important; it is where you encode the lessons you have learned from the agent failing at similar tasks.

Step 4: Add a Template

Create templates/review.md so the skill has a consistent output format:

# Weekly Review: {DATE}

## Shipped
{SHIPPED}

## Stuck
{STUCK}

## Learned
{LEARNED}

## Monday Priorities
1. {P1}
2. {P2}
3. {P3}

Hermes will substitute the placeholders at runtime.

Step 5: Activate and Test

No registration required. Hermes discovers skills on the next session start.

hermes skills list | grep weekly-review
hermes chat --provider anthropic --model claude-sonnet-4-6

In the chat: run my weekly review. Hermes will match that intent to the skill's description, load the body, and walk the procedure.

Step 6: Version and Share

Once the skill behaves the way you want, bump the version and consider publishing. Hermes supports sharing via the Hermes Skills Hub, which follows the same agentskills.io standard so other runtime users can install it too. We cover the publishing workflow in the Hermes Skills Hub article.

Tips From Real Skills

• Write descriptions like dispatch notes. "Use when the user asks for X" wins over "A skill that does X."
• Keep procedures numbered. The agent follows ordered lists more reliably than prose.
• Put constraints in their own section. Hidden inside the procedure they get ignored; as a dedicated block they get honored.
• Version aggressively. Skills evolve. A changelog comment at the top of the body is a nice habit.

What Is Next

You have a working custom skill. The next conceptual layer is memory — how Hermes remembers outcomes from running this skill week after week. That is covered in the Hermes memory deep dive. If you already have Claude Code skills you want to bring over, see migrating a Claude Code skill to Hermes.

Sources

• Hermes Agent GitHub repository
• Hermes Agent documentation
• agentskills.io open standard
• Anthropic Claude Code docs
• What is Hermes Agent?
• Hermes memory deep dive
• Are Claude Code skills portable to Hermes?