Skills as Reusable Workflow Packages

+15 Mana ✨
Hermes Skills User Guide(DOCUMENTATION)Agent Skills Open Standard(DOCUMENTATION)

Introduction

A Hermes Skill is the smallest unit of procedural knowledge you can ship to an agent. It is a folder with a SKILL.md file inside. When the agent decides the skill is relevant, it loads that file into its prompt and follows the instructions. That is the entire mental model.

What makes skills powerful is not what they are, but what they are not. They are not code patches to Hermes. They are not server processes. They are not slash command extensions hard-wired into the CLI. They are plain Markdown plus optional supporting files, loaded into the prompt only when needed.

Key Concepts

  • Skill: A directory containing a SKILL.md file. The directory name is the skill's identifier.
  • SKILL.md: A Markdown file with YAML frontmatter (name, description, optional metadata) and a body of instructions for the agent.
  • Progressive disclosure: The pattern Hermes uses to load skills in three stages (discovery, activation, execution) so dozens of skills can coexist without burning context.
  • Open standard: The Skills format is published at agentskills.io and supported by many AI clients beyond Hermes (Claude Code, Cursor, OpenAI Codex, Goose, and more).

Real World Context

A team has an internal deployment runbook that lives in a Notion page. Every new engineer has to read it before pushing to production. They keep forgetting steps. They turn the runbook into a skill: a folder called deploy-runbook/ with a SKILL.md listing services, rollback procedures, Slack channels. They drop it in ~/.hermes/skills/ and push the repo. Now any team member can type /deploy-runbook prepare release v2.4 and the agent walks them through it the same way every time. The Notion page becomes the canonical source, the skill is generated from it, and the runbook lives where the work happens.

Deep Dive

A minimal skill is just two things:

text
my-skill/
└── SKILL.md

SKILL.md itself is plain Markdown with a YAML frontmatter block on top:

markdown
---
name: my-skill
description: One sentence telling the agent when to use this skill
---
# My Skill

## When to Use
Trigger conditions go here.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and how to recover.

The frontmatter is the contract. The name and description fields are mandatory because they drive discovery: at startup, Hermes shows the agent a list of every installed skill with just those two fields. That short list is what the model scans when it sees your request. If the description is sharp, the agent picks the right skill. If it is vague, the skill stays cold.

The body is the payload. When the agent decides a skill is relevant, it expands the body into context and treats it as additional instructions. There is no parsing, no schema, no DSL. Whatever you write in Markdown, the model reads.

Skills can grow beyond a single file. Common subdirectories include scripts/ for executable helpers, references/ for longer documentation the agent can pull on demand, templates/ for output formats, and assets/ for supplementary files. But the entry point is always SKILL.md.

Common Pitfalls

  1. Treating a skill like a script: Skills are instructions the agent reads. They are not auto-executed code. The agent decides what to do based on the body, including whether to run any bundled scripts.
  2. Vague descriptions: A description like helper for git stuff will rarely match user intent. A description like Create a conventional-commits-style git commit message from staged changes will. The description is your selector.

Best Practices

  1. Start small: A 30-line SKILL.md with one clear procedure is more useful than a 300-line essay covering edge cases the agent will never hit.
  2. Write the description for selection, the body for execution: Two different audiences. The description is read by the agent when picking a skill. The body is read once the skill is already active.

Summary

  • A Hermes Skill is a folder with a SKILL.md file: YAML frontmatter plus a Markdown body.
  • The format is an open standard published at agentskills.io and supported by many AI tools.
  • Skills load progressively: only the name and description appear at startup; the full body loads when needed.
  • Optional subdirectories (scripts/, references/, templates/, assets/) extend a skill beyond a single file.

Code Examples

markdown
---
name: deploy-runbook
description: Our deployment runbook. Walks the user through service deploys, health checks, and rollback for production.
version: 1.0.0
author: Platform Team
---
# Deploy Runbook

## When to Use
User asks about deploying to production, rolling back, or checking a deploy.

## Procedure
1. Confirm the current production version with `kubectl get deployments -n prod`.
2. Bump the image tag in `infra/prod/values.yaml`.
3. Open a PR, wait for CI green, merge.
4. Argo CD picks up within 2 minutes. Watch the sync in #deploys.
5. Run smoke tests at https://status.internal/smoke.

## Pitfalls
- Never edit the prod chart directly. Always PR.
- If CI is red, do NOT bypass. Investigate.

## Verification
New pods report ready and /health returns 200 with the new version string.
✓ Completed