Skill authoring template

What a skill is

A skill is a Markdown how-to that the agent loads on demand — a procedure it reads when a task matches, then follows. It's not code you compile; it's instructions you write in plain English (plus a little YAML at the top). Each skill lives in its own folder at ~/.hermes/skills/[category/]<name>/SKILL.md, and the file is named SKILL.md exactly. For the full mental model of how skills get discovered, loaded, and improved over time, see Module 4 — Skills: the learning loop.

The directory layout

A skill is a folder. SKILL.md is the only required file; the four optional subfolders hold supporting material the body can point to.

~/.hermes/skills/
  my-category/
    my-skill/
      SKILL.md            # required
      references/         # optional supporting docs
      templates/          # optional
      scripts/            # optional helper scripts
      assets/             # optional files

The category folder (my-category/) is optional too — a skill can sit directly under ~/.hermes/skills/<name>/. Categories just keep large collections tidy.

The annotated template

Copy this whole block into a new SKILL.md and fill in the blanks. The frontmatter (between the --- fences) is structured metadata; everything below it is the free-form body the agent reads.

---
name: my-skill                      # required · lowercase, matches [a-z0-9][a-z0-9._-]*
description: One clear sentence on what this does and when to use it.   # required
version: 1.0.0                       # optional
author: Your Name                   # optional
license: MIT                         # optional
platforms: [linux, macos, windows]  # optional
metadata:
  hermes:
    tags: [Category, Keyword, Keyword]   # optional · helps discovery
    related_skills: [some-other-skill]   # optional
---

# My Skill Title

Short intro: what this skill helps the agent do, and when to reach for it.

## When to use this
- Bullet the trigger situations.

## Steps
1. First do this.
2. Then this. Be concrete and command-level where you can.

## Examples
Show a real example (commands, expected output).

## Gotchas
- Note pitfalls so the agent avoids them.

Frontmatter fields

Only two fields are required. Everything else is optional but improves discovery and provenance.

The rules

Validation rules — keep these or the loader rejects the skill

• name must be lowercase and match [a-z0-9][a-z0-9._-]*.
• SKILL.md can be up to ~100,000 characters (about 36k tokens). If it grows past that, split the long parts into references/ or templates/.
• Supporting files must live in one of four subfolders only: references/, templates/, scripts/, assets/.
• You can reference the skill's own folder from inside the body with ${HERMES_SKILL_DIR} — Hermes expands it to the absolute path at load time, so a helper script becomes ${HERMES_SKILL_DIR}/scripts/run.sh.

These constraints are enforced in tools/skill_manager_tool.py (name pattern, the 100,000-char ceiling, and the allowed-subdirs allowlist) and the ${HERMES_SKILL_DIR} substitution happens in agent/skill_preprocessing.py.

A finished mini-example

Here's a complete, working skill — small but real. Save it as ~/.hermes/skills/git/git-clean-branches/SKILL.md and the agent can run it the moment you ask it to tidy up your branches.

---
name: git-clean-branches
description: Delete local Git branches that have already been merged into the main branch. Use to tidy up a repo after merging PRs.
version: 1.0.0
author: Your Name
license: MIT
platforms: [linux, macos, windows]
metadata:
  hermes:
    tags: [Git, Cleanup, Branches]
---

# Clean up merged Git branches

Removes local branches that are fully merged into the default branch, so the
branch list stays readable after a round of PRs.

## When to use this
- The user says "clean up my branches" or "delete merged branches".
- After merging one or more pull requests.

## Steps
1. Confirm you're in a Git repo: `git rev-parse --is-inside-work-tree`.
2. Find the default branch: `git symbolic-ref --short refs/remotes/origin/HEAD`
   (usually `origin/main`). Switch to it: `git checkout main`.
3. Update it: `git pull --ff-only`.
4. List merged branches, excluding the current one and main:
   `git branch --merged | grep -vE '^\*|main|master'`.
5. Show that list to the user and confirm before deleting.
6. Delete each: `git branch -d <branch>`.

## Examples
```
$ git branch --merged | grep -vE '^\*|main|master'
  feature/login-form
  fix/typo
$ git branch -d feature/login-form fix/typo
Deleted branch feature/login-form (was a1b2c3d).
Deleted branch fix/typo (was e4f5g6h).
```

## Gotchas
- Use `-d` (safe), never `-D`, so Git refuses to drop unmerged work.
- Never delete the branch you're standing on — checkout main first.
- `--merged` is relative to the *current* branch; that's why step 2 matters.

How to use it once written

1. Save the file at ~/.hermes/skills/[category/]<name>/SKILL.md.
2. Start the agent: run hermes.
3. Load it explicitly by typing /my-skill — or just describe a task that matches its description and let the agent find and load it on its own.

When you're happy with it, share it: hermes skills publish pushes the skill out for others to install. Hermes skills follow the open agentskills.io standard, so the same SKILL.md format works across compatible agents.

Pair with your AI — don't start from a blank file; hand the workflow to your agent and edit what it returns. Try: "Draft a complete SKILL.md for <my workflow>, following the Hermes frontmatter format."