Hermes Agent Skill Authoring: In-Repo SKILL.md Guide

This guide covers how to write and maintain SKILL.md files that ship with Hermes Agent itself, stored in the repository tree rather than in a user's local skills directory. You would reach for this when you need to create a reusable, version-controlled skill that becomes part of the Hermes Agent package and is available to every user who installs it.

What it does

Hermes Agent loads skills from two locations: user-local skills under ~/.hermes/skills/ and in-repo skills under /home/bb/hermes-agent/skills/. This guide focuses on the in-repo path. An in-repo SKILL.md is a Markdown file with YAML frontmatter that tells the agent what the skill does, when to activate it, and how to execute its steps. The skill manager tool validates the frontmatter and enforces size limits, but the real value comes from the structure and writing discipline that make the agent's behavior predictable.

Before you start

You need write access to the Hermes Agent repository, typically at /home/bb/hermes-agent/.
You must be comfortable with write_file and git add commands. The skill_manage(action='create') tool writes to the user-local tree, not the repo tree, so it will not work for in-repo creation.
The skill loader is initialized at session start. A new skill will not appear in skill_view or skills_list until you start a new session. This is expected behavior, not a bug.
The source of truth for frontmatter validation is tools/skill_manager_tool.py::_validate_frontmatter. If you are unsure about a constraint, check that file.

Required frontmatter

The frontmatter must start with --- as the first bytes of the file, with no leading blank line or BOM. It closes with \n---\n before the body. The content between the delimiters must parse as a YAML mapping. Two fields are hard-required by the validator: name and description. The body after the closing --- must be non-empty.

Every skill under skills/software-development/ follows this peer-matched shape:

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

The fields version, author, license, and metadata are not enforced by the validator, but every peer skill has them. Omitting them makes your skill look half-finished.

Size limits

Description: ≤ 1024 characters, enforced by the validator. Long descriptions are truncated to 57 characters plus "..." in the system prompt skill index. The full text is still visible via skills_list() and skill_view(). Front-load the trigger phrase so the agent sees it within the first 57 characters.
Full SKILL.md: ≤ 100,000 characters, enforced as MAX_SKILL_CONTENT_CHARS (roughly 36,000 tokens).
Peer skills in software-development/ typically run 8,000 to 14,000 characters. Aim for that range. If you exceed 20,000 characters, split bulky reference material into references/*.md files and reference them from SKILL.md.

Writing quality principles

A skill exists to make the agent's process more predictable. Predictability does not mean identical output every run; it means the agent reliably follows the same useful discipline. Use these quality checks when writing or editing any skill:

Optimize for process predictability. Ask: what behavior should change when this skill loads? If a line does not change behavior, cut it.
Choose the right context load. A model-invoked Hermes skill pays for its description every turn. Keep descriptions focused on trigger classes and the skill's distinctive behavior. Put details in the body or linked references.
Use an information hierarchy. Put always-needed steps in SKILL.md; put branch-specific or bulky reference material in references/, templates/, or scripts/ and point to it only when needed.
End steps with completion criteria. Each ordered step should say how the agent knows it is done. Good criteria are checkable and, when it matters, exhaustive: "every modified file accounted for" beats "summarize changes."
Co-locate rules with the concept they govern. Avoid scattering one idea across the file. Keep definition, caveats, examples, and verification near each other.
Use strong leading words. Prefer compact concepts the model already knows, such as "tight loop," "tracer bullet," "root cause," or "regression test," over long repeated explanations. A good leading word saves tokens and anchors behavior.
Prune duplication and no-ops. Keep each meaning in one source of truth. Sentence by sentence, ask whether the sentence changes agent behavior versus the default. If not, delete it rather than polishing it.
Watch for premature completion. If agents tend to rush a step, first sharpen that step's completion criterion. Split the sequence only when later steps distract from doing the current step well.

Common quality failures:

Premature completion, the skill lets the agent move on before the work is genuinely done.
Duplication, the same rule appears in multiple places and drifts.
Sediment, stale lines remain because adding felt safer than deleting.
Sprawl, too much always-visible material; push branch-specific reference behind pointers.
No-op prose, generic advice the agent would already follow without the skill.

Peer-matched structure

Every in-repo skill follows roughly this structure:

# <Title>

## Overview
One or two paragraphs: what and why.

## When to Use
- Bulleted triggers
- "Don't use for:" counter-triggers

## <Topic sections specific to the skill>
- Quick-reference tables are common
- Code blocks with exact commands
- Hermes-specific recipes (tests via scripts/run_tests.sh, ui-tui paths, etc.)

## Common Pitfalls
Numbered list of mistakes and their fixes.

## Verification Checklist
- [ ] Checkbox list of post-action verifications

## One-Shot Recipes (optional)
Named scenarios → concrete command sequences.

Not every section is mandatory, but Overview + When to Use + actionable body + pitfalls are the minimum for the skill to feel like a peer.

Directory placement

Place the skill at:

skills/<category>/<skill-name>/SKILL.md

Categories currently in the repo (confirm with ls skills/): autonomous-ai-agents, creative, data-science, devops, email, gaming, github, leisure, mcp, media, mlops/*, note-taking, productivity, red-teaming, research, smart-home, social-media, software-development.

Pick the closest existing category. Do not invent new top-level categories casually.

Workflow

Survey peers in the target category:

ls skills/<category>/

Read 2-3 peer SKILL.md files to match tone and structure. 2. Check validator constraints in tools/skill_manager_tool.py if unsure. 3. Draft with write_file to skills/<category>/<name>/SKILL.md. 4. Validate locally:

import yaml, re, pathlib
content = pathlib.Path("skills/<category>/<name>/SKILL.md").read_text()
assert content.startswith("---")
m = re.search(r'\n---\s*\n', content[3:])
fm = yaml.safe_load(content[3:m.start()+3])
assert "name" in fm and "description" in fm
assert len(fm["description"]) <= 1024
assert len(content) <= 100_000

Git add + commit on the active branch.
Note: the CURRENT session's skill loader is cached, skill_view / skills_list will not see the new skill until a new session. This is expected, not a bug.

Cross-referencing other skills

metadata.hermes.related_skills unions both trees (skills/ in-repo and ~/.hermes/skills/) at load time. You CAN reference a user-local skill from an in-repo skill, but it will not resolve for other users who clone the repo fresh. Prefer referencing only in-repo skills from in-repo skills. If a frequently-referenced skill lives only in ~/.hermes/skills/, consider promoting it to the repo.

Editing existing in-repo skills

Small fix (typo, added pitfall, tightened trigger): skill_manage(action='patch', name=..., old_string=..., new_string=...) works fine on in-repo skills.
Major rewrite: write_file the whole SKILL.md. skill_manage(action='edit') also works but requires supplying the full new content.
Adding supporting files: write_file to skills/<category>/<name>/references/<file>.md, templates/, or scripts/. skill_manage(action='write_file') also works and enforces the references/templates/scripts/assets subdir allowlist.
Always commit the edit, in-repo skills are source, not runtime state.

Common pitfalls

Using skill_manage(action='create') for an in-repo skill. It writes to ~/.hermes/skills/, not the repo tree. Use write_file for in-repo creation.
Leading whitespace before ---. The validator checks content.startswith("---"); any leading blank line or BOM fails validation.
Description too generic or trigger buried past char 57. The system prompt skill index truncates long descriptions at 57 chars. Peer descriptions start with "Use when ..." and complete the trigger class within that window.
- Good: Use when debugging Hermes skill discovery failures.
- Bad: This skill contains detailed guidance for agents working on Hermes skill discovery failures.
Forgetting the author/license/metadata block. Not validator-enforced, but every peer has it; omitting makes the skill look half-finished.
Writing a skill that duplicates a peer. Before creating, ls skills/<category>/ and open 2-3 peers. Prefer extending an existing skill to creating a narrow sibling.
Expecting the current session to see the new skill. It won't. The skill loader is initialized at session start. Verify in a fresh session or via skill_view using the exact path.
Letting skills accumulate sediment. A skill should get shorter or sharper over time. When adding a rule, remove the old wording it replaces; don't layer advice forever.
Writing no-op prose. "Be careful," "be thorough," and "use best practices" rarely change model behavior. Replace with a checkable completion criterion or a stronger leading word.
Linking to skills that don't exist in-repo. related_skills: [some-user-local-skill] works for you but breaks for other clones. Prefer only in-repo links.

Verification checklist

File is at skills/<category>/<name>/SKILL.md (not in ~/.hermes/skills/)
Frontmatter starts at byte 0 with ---, closes with \n---\n
name, description, version, author, license, metadata.hermes.{tags, related_skills} all present
Name ≤ 64 chars, lowercase + hyphens
Description ≤ 1024 chars, trigger phrase self-contained within first 57 chars, and starts with "Use when ..."
Total file ≤ 100,000 chars (aim for 8-15k)
Structure: # Title → ## Overview → ## When to Use → body → ## Common Pitfalls → ## Verification Checklist
Each ordered step has a checkable completion criterion
Description is trigger-focused and avoids duplicated body content
Bulky or branch-specific reference is progressively disclosed in linked files
No-op prose and duplicated rules removed
related_skills references resolve in-repo (or are explicitly OK to be user-local)
git add skills/<category>/<name>/ && git commit completed on the intended branch

When not to use it

Do not use this workflow if you are creating a personal, non-shared skill. Use skill_manage(action='create') instead, which writes to ~/.hermes/skills/. Also avoid this if you are making a trivial one-off edit that does not need version control; a user-local skill is simpler for experiments.

Limits and gotchas

The skill loader is cached per session. New or edited in-repo skills will not be visible until the next session. This is by design.
The description truncation at 57 characters in the system prompt skill index is a hard limit. If your trigger phrase does not fit in that window, the agent may not activate the skill when it should.
Cross-referencing user-local skills from in-repo skills will break for other users who clone the repository fresh. Only do this if you are certain the user-local skill is present on every target machine.
The validator enforces only name and description. The other frontmatter fields are convention, but omitting them makes the skill inconsistent with its peers.

Related skills

This skill pairs naturally with the plan skill for structuring multi-step workflows and the requesting-code-review skill for getting feedback on skill changes before committing.

Hermes Agent Skill Authoring: Writing In-Repo SKILL.md Files