How to Write a Hermes Skill File

What a Skill File Is

A Hermes skill is a markdown file that teaches your agent how to handle a specific task. When the agent encounters a matching task, it loads the skill and follows its instructions. Skills live in `~/.hermes/profiles/<profile>/skills/`.

The Four Parts

1. Frontmatter

---
name: my-skill
description: Use when doing X. Does Y.
trigger: "keyword that activates this skill"
---

The `description` field is indexed in your session — keep the first 57 characters self-contained because that is all that shows in the skill index.

2. Trigger

Write the trigger as a plain-language condition: `Use when the user asks to deploy to production.`

The agent reads this and loads the skill if the current task matches. Be specific to avoid false positives.

3. Steps

Number every step. Include exact commands, not descriptions of commands.

## Steps

1. Check current branch: `git branch --show-current`
2. Run tests: `npm test`
3. If tests pass, tag and push: `git tag v$VERSION && git push origin v$VERSION`

Steps are instructions for the agent, not documentation for humans. Write them as if you are telling someone exactly what to do.

4. Pitfalls

## Pitfalls

- Never push to main directly. Always use a PR.
- If tests fail, stop and report to the user before continuing.
- The deploy script requires `DEPLOY_TOKEN` in the environment.

Pitfalls are where real knowledge lives. Every time you hit a problem, add it here.

Loading and Verifying

Create a skill:

hermes skill create my-skill

View it:

hermes skill view my-skill

The agent loads matching skills automatically. You can also reference one explicitly in a prompt: `Load the deploy skill and follow it.`