Metadata as a Contract: What You Promise - Hermes Skills System

Introduction

Frontmatter is small but load-bearing. The fields you declare in the YAML block at the top of SKILL.md are promises Hermes (and other standards-compliant clients) act on: where to show the skill, when to hide it, what it needs to run, what config it owns. Treat the frontmatter as a contract between the skill and the host.

Key Concepts

Required fields: name and description. Everything else is optional.
Common optional fields: version, author, platforms.
Hermes-specific metadata: lives under metadata.hermes.* and includes tags, category, fallback_for_toolsets, requires_toolsets, fallback_for_tools, requires_tools, and config.
Environment variables: declared as a top-level required_environment_variables list.

Real World Context

A team ships an internal aws-cloudwatch-debug skill. Its frontmatter promises: name aws-cloudwatch-debug, description tuned to user-intent (Investigate a CloudWatch alarm by pulling recent logs and metrics), requires_toolsets: [terminal] (depends on shell access), required_environment_variables: [AWS_REGION, AWS_PROFILE] (depends on aws configuration), and metadata.hermes.config.aws.default_region (so a default can live in config.yaml). When a user lacks AWS env vars, Hermes prompts securely; when the terminal toolset is missing, the skill hides. The frontmatter is enough for Hermes to manage all of that without reading the body.

Deep Dive

A fully-fleshed frontmatter:

yaml
---
name: aws-cloudwatch-debug
description: Investigate a CloudWatch alarm by pulling recent logs and metrics, then summarizing the likely root cause.
version: 1.2.0
author: Platform Team
platforms: [macos, linux]
required_environment_variables:
  - name: AWS_REGION
    prompt: AWS region (e.g. us-east-1)
    required_for: full functionality
  - name: AWS_PROFILE
    prompt: AWS profile to use
    required_for: full functionality
metadata:
  hermes:
    tags: [aws, observability, oncall]
    category: devops
    requires_toolsets: [terminal]
    fallback_for_tools: []
    config:
      - key: aws.default_region
        description: Default AWS region used when no override is given
        default: us-east-1
        prompt: Default AWS region
---

Each field signals something:

name: The slug. Becomes the slash command (/aws-cloudwatch-debug) and the install identifier.
description: One sentence, user-intent shaped. Drives Level 0 discovery.
version: Semver string. Used by hermes skills check to detect upstream changes.
author: Free text. Helps reviewers route questions.
platforms: [macos, linux, windows] in any combination. The skill hides on incompatible OSes.
required_environment_variables: List of env vars with prompts. Hermes asks for them securely when the skill first activates locally.
metadata.hermes.tags: Free-form tags for searching.
metadata.hermes.category: Category override (otherwise the directory name is used).
metadata.hermes.requires_toolsets / requires_tools: The skill hides if these are not available.
metadata.hermes.fallback_for_toolsets / fallback_for_tools: The skill hides if these are available.
metadata.hermes.config: Declarable non-secret settings that live in config.yaml and inject into the agent's context when the skill loads.

The contract has two directions:

From the skill to Hermes. "I need these env vars. I hide on this OS. I require this toolset." Hermes honors these claims at load time.
From Hermes to the skill. When the skill loads, its declared config and env vars are available to scripts. The agent's prompt is told what is configured. Everything matches.

Missing or wrong frontmatter has predictable failure modes:

No description means no Level 0 entry: the skill never appears in the index.
A typo in requires_toolsets means the skill stays hidden on every environment.
Forgetting required_environment_variables for a script that needs them means the script fails at runtime with a confusing missing-env error.

The frontmatter is small enough that you should write it deliberately, not auto-generate it.

Common Pitfalls

Putting secrets in the frontmatter: Never. The required_environment_variables field is for declaring what the skill needs; secrets live in ~/.hermes/.env or are provided at activation time.
Over-constraining with requires_*: Saying requires_toolsets: [terminal] on a skill that does not actually need the terminal needlessly hides it.

Best Practices

Start with name and description only: Add other fields only when the skill earns them. Most fields are about hiding the skill in some condition; if there is no condition, leave them out.
Treat frontmatter changes as breaking changes: Bumping version and updating a description is harmless. Changing name breaks installs. Changing requires_toolsets changes who sees the skill. Be deliberate.

Summary

Frontmatter is a contract: required fields (name, description) plus optional fields for environment, toolsets, platforms, env vars, and config.
Each field signals something Hermes uses at load time, discovery, or runtime.
Missing or wrong frontmatter has predictable failure modes (invisible skills, missing env vars at runtime).
Add fields deliberately, not by default.

Code Examples

yaml

# Minimal frontmatter: just the required fields
---
name: hello-world
description: Greet the user by name and offer help with the project.
---

# Full frontmatter for a realistic skill
---
name: postgres-explain
description: Analyze a slow Postgres query: run EXPLAIN ANALYZE, identify the bottleneck, suggest an index or rewrite.
version: 2.0.1
author: Data Platform
platforms: [macos, linux]
required_environment_variables:
  - name: PGCONN
    prompt: Postgres connection string (read-only role)
    required_for: full functionality
metadata:
  hermes:
    tags: [postgres, perf, sql]
    category: data
    requires_toolsets: [terminal]
    config:
      - key: postgres.statement_timeout_ms
        description: Statement timeout used when running EXPLAIN ANALYZE
        default: 30000
---