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): skills/<category>/<name>/SKILL.md or optional-skills/<category>/<name>/SKILL.md inside the hermes-agent repo — committed, shipped with the package. Use write_file + git add. skill_manage(action='create') does NOT target this tree.

In-repo skills must meet the repo's hardline authoring standards (see AGENTS.md, "Skill authoring standards (HARDLINE)" — that section is the source of truth; this skill is the operational walkthrough). Reviewers reject PRs that violate them, so meeting them up front is cheaper than a salvage pass later.

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 skills/ or optional-skills/ (use patch for small edits, write_file for rewrites; skill_manage still works for patch on in-repo skills, but not for create)
• Don't use for: personal skills in ~/.hermes/skills/ (just use skill_manage)

Decide the Tier First: Bundled vs Optional

• Bundled (skills/<category>/) — daily-driver behavior, broadly useful across many user types, low footprint. Hard bar: you can say "a user will load this in 5+ sessions per month" with a straight face.
• Optional (optional-skills/<category>/) — niche, vertical-specific (blockchain, gaming, finance, one app), recurring-job/task skills, or anything heavy. Installed via hermes skills install official/<category>/<skill>.

When in doubt, optional. Promoting later is easy; demoting is churn. "Would be useful to anyone who ever needs this" is an optional-tier argument, not a bundled one.

Pick the category by what the tool IS, not what it feels like (an AI-agent CLI goes in autonomous-ai-agents/ even if it "feels productivity"). Confirm existing categories with search_files(pattern='*', target='files', path='skills') and don't invent new top-level categories casually.

No router / index / hub skills. A skill whose core content is a routing table pointing at sibling skills adds an indirection hop and duplicates the siblings' own When to Use triggers. If the skill would be empty without "load skill X instead" pointers, don't write it — the catalog and each sibling's triggers already do that job.

Required Frontmatter

Validator source of truth: tools/skill_manager_tool.py::_validate_frontmatter. Validator 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 (validator ceiling 1024 chars — but see the repo hardline below, which is much stricter).
• Non-empty body after the closing ---.

Repo-standard shape (all fields expected, even where the validator doesn't enforce them):

---
name: my-skill-name               # lowercase, hyphens, ≤64 chars (MAX_NAME_LENGTH)
description: Concise capability statement, under sixty chars.
version: 0.1.0                    # semver; new skills start at 0.1.0
author: Real Name (github-handle), Hermes Agent
license: MIT
platforms: [linux, macos, windows]   # audit, don't guess — see Platform Gating
metadata:
  hermes:
    tags: [Short, Descriptive, Tags]
    related_skills: [other-in-repo-skill]
---

description rules (HARDLINE — the validator's 1024 is NOT the standard)

• ≤ 60 characters. One sentence. Ends with a period.
• State the capability, not the implementation, and don't repeat the skill name.
• No marketing words ("powerful", "comprehensive", "seamless", "advanced").
• The system prompt skill index truncates at 57 chars + "..." — the trigger/capability must be self-contained in that window.
• If the description contains a :, wrap it in double quotes or YAML parses it as a mapping and the docs generator crashes. Quotes don't count toward the 60.

Good: Track named companies for material news with cited digests. Bad: Use when a user asks to monitor named competitors or companies for product launches, pricing changes, funding, ... (240 chars — rejected in review)

author rules

• Credit the human first, then "Hermes Agent" as secondary collaborator: Ben Barclay (benbarclay), Hermes Agent.
• Never author: Hermes Agent alone for contributed skills — credit the human, not the tool, even (especially) when an agent drafted the text.
• Maintainer-authored skills: Teknium (teknium1), Hermes Agent.

related_skills rules

• Every entry must resolve to an existing in-repo skill in the same tree state as your PR. Do not reference skills that were only planned, live in another PR, or exist only in ~/.hermes/skills/.
• Verify each entry: search_files(pattern='<name>', target='files', path='skills') (and optional-skills/).

Platform Gating: audit, don't trust

platforms: gates loading by host OS. Set it from what the skill's prose and scripts actually invoke:

<!-- no-tmp: ok — names the anti-pattern skill authors must avoid -->

POSIX-only signals to search for in scripts/: fcntl, termios, pty, os.fork, os.killpg, signal.SIGKILL, os.kill(pid, 0) liveness checks, hardcoded /tmp /proc /etc. Default posture: fix cross-platform first (tempfile.gettempdir(), pathlib.Path, psutil.pid_exists); gate narrower only when the dependency is genuinely platform-bound, and say why in ## Pitfalls.

Size Limits

• Full SKILL.md: ≤ 100,000 chars enforced (MAX_SKILL_CONTENT_CHARS), but target ~100 lines for a simple skill, ~200 for a complex one. Peer skills sit at 8-14k chars.
• Bulky or branch-specific material goes in references/*.md, templates/, or scripts/ — pointed to from SKILL.md, not inlined.
• Don't expect the model to inline-write parsers or non-trivial logic every call — ship a helper script in scripts/ and reference it by path.

Body Structure (modern section order)

# <Skill> Skill
2-3 sentence intro: what it does, what it doesn't do, dependency stance.

## When to Use          — bulleted triggers (+ "Don't use for:" counter-triggers)
## Prerequisites        — exact env vars, installs, API key sourcing
## How to Run           — canonical invocation through the `terminal` tool
## Quick Reference      — flat command list, no narration
## Procedure            — numbered steps, each with a checkable completion criterion
## Pitfalls             — known limits, things that look broken but aren't
## Verification         — how to prove the skill worked

Not every section applies to every skill (a pure-procedure task skill may have no Quick Reference), but When to Use + actionable body + Pitfalls + Verification are the minimum. Cut marketing intros, "Setup Check" no-ops, and re-explanations of env vars already in Prerequisites.

Reference Hermes tools, not raw shell

When the skill needs a capability, name the proper Hermes tool in backticks: terminal, read_file, write_file, patch, search_files, web_search, web_extract, browser_navigate, vision_analyze, delegate_task, cronjob. Do NOT name shell utilities the agent already has wrapped (grep → search_files, cat → read_file, sed/awk → patch, find/ls → search_files target='files'). A CLI-wrapper skill should frame invocations as terminal(command="{tool} ...", timeout=...) — bare shell prose ("run foo --version") is a review-blocking non-conformance. If the skill depends on an MCP server, name it and document setup in Prerequisites.

Never use machine-local paths

Write repo-relative paths (skills/..., tools/skill_manager_tool.py). A /home/<you>/... path baked into a committed skill breaks for every other user and is an instant review flag.

Writing Quality Principles

A skill exists to make the agent's process more predictable — the agent reliably follows the same useful discipline.

1. Optimize for process predictability. If a line does not change behavior, cut it.
2. Choose the right context load. The description is paid for every turn; details go in the body or linked references.
3. End steps with completion criteria. Checkable and, when it matters, exhaustive: "every modified file accounted for" beats "summarize changes."
4. Co-locate rules with the concept they govern.
5. Use strong leading words ("tight loop," "root cause," "regression test") over long repeated explanations.
6. Prune duplication and no-ops. "Be careful" and "use best practices" don't change model behavior — replace with a checkable criterion or delete.