Authoring Hermes-Agent Skills (in-repo)

Overview

There are two places a SKILL.md can live:

User-local: ~/.hermes/skills/<maybe-category>/<name>/SKILL.md — personal, not shared. Created via skill_manage(action='create').
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):

yaml

---
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:

Skill uses only…	`platforms:`
Hermes tools + stdlib Python + cross-platform CLIs	`[linux, macos, windows]`
bash pipelines, `grep`/`awk`/`sed` chains, heredocs	`[linux, macos]`
`osascript`, `defaults`, `pmset`	`[macos]`
`apt`/`systemctl`/`/proc`	`[linux]`

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.

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

Tests and Docs (required for repo skills)

Tests live at tests/skills/test_<skill>_skill.py — stdlib + pytest + unittest.mock only, no live network. Run via scripts/run_tests.sh tests/skills/test_<skill>_skill.py -q. (The generic tests/tools/test_skill_manager_tool.py passing proves nothing about YOUR skill.)
Docs regen: run python website/scripts/generate-skill-docs.py, then apply scope discipline — the generator rewrites EVERY auto-gen page. git checkout -- everything that isn't yours; the final diff must show only your SKILL.md, your one per-skill docs page, a one-line catalog row, and a one-line website/sidebars.ts insertion (verify with search_files(pattern='<your-slug>', path='website/sidebars.ts') — exactly one hit, or the page is an orphan).
.env.example (only if the skill needs new env vars): one clearly delimited commented block; touch nothing else in the file.

Workflow

Survey peers in the target category with search_files(target='files') and read 2-3 peer SKILL.md files to match tone and structure. Prefer extending an existing skill over creating a narrow sibling.
Decide tier and category (see above). When in doubt, optional — and ask before pushing rather than defaulting.
Draft with write_file to skills/<category>/<name>/SKILL.md (or optional-skills/...).

Validate locally:

python

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"]) <= 60, f"description {len(fm['description'])} chars — hardline is 60"
assert fm["description"].endswith(".")
assert "platforms" in fm
assert len(content) <= 100_000

Also verify every related_skills entry exists in-repo.

Add tests + regen docs (previous section).
Git add + commit on the active branch; open a PR.
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.

Editing Existing In-Repo Skills

Small fix: skill_manage(action='patch', ...) works on in-repo skills, as does patch.
Major rewrite: write_file the whole SKILL.md.
Supporting files: write_file to references/, templates/, or scripts/ under the skill dir.
Always commit — in-repo skills are source, not runtime state. Re-run the docs generator when frontmatter changed.

Common Pitfalls

Using skill_manage(action='create') for an in-repo skill. It writes to ~/.hermes/skills/, not the repo tree. Use write_file.
Trusting the validator's limits as the standard. The validator allows 1024-char descriptions; review rejects anything over 60. The validator doesn't check platforms:, author format, tests, or docs — review does.
author: Hermes Agent on a contributed skill. Credit the human first.
Leading whitespace before ---. Validation fails on any leading blank line or BOM.
Description too generic or trigger buried past char 57.
related_skills pointing at skills that don't exist in-repo (user-local, planned, or in a sibling PR).
Duplicating a peer. Survey the category first; extend rather than sibling.
Skipping the docs generator or pushing its unrelated drift. Both directions are wrong: no regen = orphan skill with no docs page; blind regen = a ballooned diff full of other skills' drift.
Expecting the current session to see the new skill. The loader is initialized at session start.
Letting skills accumulate sediment. When adding a rule, remove the old wording it replaces.

Authoring Hermes-Agent Skills (in-repo)

Authoring Hermes-Agent Skills (in-repo)

Overview

When to Use

Decide the Tier First: Bundled vs Optional

Required Frontmatter

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

author rules

related_skills rules

Platform Gating: audit, don't trust

Size Limits

Body Structure (modern section order)

Reference Hermes tools, not raw shell

Never use machine-local paths

Writing Quality Principles

Tests and Docs (required for repo skills)

Workflow

Editing Existing In-Repo Skills

Common Pitfalls

Verification Checklist

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

`author` rules

`related_skills` rules