hermes

Compatibility: Hermes Agent (SKILL.md)

Claim (Tier B, narrow). An MDA-compiled SKILL.md whose frontmatter stays inside the agentskills.io v1 envelope subset is discovered and parsed by Hermes Agent when installed under its category-organized layout at ~/.hermes/skills/<category>/<name>/SKILL.md. name, description, body, and the reserved metadata.hermes.* vendor namespace survive the round-trip from .mda source to runtime ingest, and the skill enumerates in hermes skills list --source local.

Claim (negative). Some shipped Hermes skills carry version and author as top-level fields rather than under metadata.mda.*. MDA v1.0's SKILL.md schema rejects those at the top level (per §06-3.3 forbidden list). The same v1.1 schema-expansion gap that applies to Claude Code applies here.

Last verified: 2026-05-26 against @markdown-ai/cli@1.1.7, Hermes Agent v0.9.0 (2026.4.13) on hermes-vm.

Directory contents

• source.mda — dedicated MDA source for this kit (do not reuse for unrelated examples)
• build/SKILL.md — reproducible compile output
• verify.sh — structural verification, no live install needed
• install.sh — optional live install via SSH to hermes-vm:~/.hermes/skills/compat/mda-compat-hermes/SKILL.md (override host with HERMES_HOST=...)
• uninstall.sh — removes the live install from the VM
• notes.md — scope, gaps, caveats, graduation criteria

Quick verify (offline, modifies nothing on any system)

./compat/hermes/verify.sh

Re-compiles source.mda, validates the output against the SKILL.md JSON Schema, and confirms the envelope subset plus metadata.hermes.* passthrough are intact.

Live verify (writes one file under hermes-vm:~/.hermes/skills/compat/)

./compat/hermes/install.sh
ssh hermes-vm 'hermes skills list --source local'

Copies build/SKILL.md over SSH to hermes-vm. hermes skills list --source local enumerates locally-installed skills — the source code path for this list invokes Hermes' parse_frontmatter() (~/.hermes/hermes-agent/agent/skill_commands.py:102, :226), so an entry in the list implies the frontmatter parsed.

To remove:

./compat/hermes/uninstall.sh

How Hermes' loader actually behaves

From the Hermes Agent source on the verification VM (~/.hermes/hermes-agent/agent/skill_utils.py:52):

• Hermes parses frontmatter with PyYAML's CSafeLoader, supporting nested objects and lists.
• The list/scan code paths (skill_commands.py:102, :226) invoke parse_frontmatter() before filtering by platforms/disabled-list.
• Discovery is rooted at ~/.hermes/skills/<category>/<name>/SKILL.md (category-organized) plus external_dirs configured in ~/.hermes/config.yaml.
• hermes skills install <identifier> fetches from registries (skills.sh, ClawHub, GitHub taps, builtin); local files dropped into the discovery layout are picked up at scan time.
• Existing Hermes skills routinely add metadata.hermes.{tags, related_skills} for Hermes-specific filtering and graph references.

What MDA emits today (v1.0)

The SKILL.md schema (schemas/frontmatter-skill-md.schema.json) permits these top-level fields, exactly:

Field	Source	Hermes status
name	author	Required; must match dir name (spec §06-2.1).
description	author	Required by MDA; consumed by Hermes for skill descriptions.
license	author	Optional. Hermes accepts at top level.
compatibility	author	Optional. Hermes accepts at top level.
allowed-tools	author	agentskills.io v1; Hermes loader behavior on this field is not documented.
metadata	author	Optional. metadata.mda.* MDA-extended, metadata.hermes.* reserved for Hermes and read by Hermes for tags/related-skills/etc.
integrity	compiler	Not consumed by Hermes today.
signatures	compiler/signer	Not consumed by Hermes today.

What MDA does NOT emit today

Some shipped Hermes skills declare version and author (and possibly other Hermes-extended fields) as top-level frontmatter — outside the agentskills.io v1 envelope. MDA v1.0's schema rejects those at the top level. Authors who need them either hand-edit the compiled output (exits MDA validation) or wait for v1.1. Tracked in docs/v1.0/what-v1.0-does-not-ship.md gap #10, same graduation criterion as the Claude Code runtime fields.

What this kit does NOT claim

• That Hermes Agent honors allowed-tools, integrity, or signatures at load.
• That signed MDA artifacts are verified at load time by Hermes.
• That every Hermes-specific top-level field (version, author, …) is authorable from MDA today.
• That hermes skills install <local-path> accepts arbitrary file paths. Local files are picked up by drop-into-discovery-layout, not by the install subcommand.

Anything stronger belongs in a future Tier-C section, behind explicit runtime opt-in to MDA extensions.