hermes-agent-skill-authoring

Authoring Hermes-Agent Skills (in-repo)

Overview

There are two places a SKILL.md can live:

1. User-local: ~/.hermes/skills/<maybe-category>/<name>/SKILL.md — personal, not shared. Created via skill_manage(action='create').
2. In-repo (this skill is about this case): /home/bb/hermes-agent/skills/<category>/<name>/SKILL.md — committed, shipped with the package. Use write_file + git add. skill_manage(action='create') does NOT target this tree.

When to Use

• User asks you to add a skill "in this branch / repo / commit"
• You're committing a reusable workflow that should ship with hermes-agent
• You're editing an existing skill under /home/bb/hermes-agent/skills/ (use patch for small edits, write_file for rewrites; skill_manage still works for patch on in-repo skills, but not for create)

Required Frontmatter

Source of truth: tools/skill_manager_tool.py::_validate_frontmatter. Hard requirements:

• Starts with --- as the first bytes (no leading blank line).
• Closes with \n---\n before the body.
• Parses as a YAML mapping.
• name field present.
• description field present, ≤ 1024 chars (MAX_DESCRIPTION_LENGTH).
• Non-empty body after the closing ---.

Peer-matched shape used by every skill under skills/software-development/:

---
name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
description: Use when <trigger>. <one-line behavior>.
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [short, descriptive, tags]
    related_skills: [other-skill, another-skill]
---

version / author / license / metadata are NOT enforced by the validator, but every peer has them — omit and your skill sticks out.

Size Limits

• Description: ≤ 1024 chars (enforced).
• Full SKILL.md: ≤ 100,000 chars (enforced as MAX_SKILL_CONTENT_CHARS, ~36k tokens).
• Peer skills in software-development/ sit at 8-14k chars. Aim for that range. If you're pushing past 20k, split into references/*.md and reference them from SKILL.md.