DocumentHPD · v0.3.1StatusSubmitted to catalog
Plugin idhermes-plugin-devRequiresHermes >=0.21.6
AuthorKyle Durepos (mojomast)Catalog PR#152699

Hermes Plugin Dev

Teach any coding agent to ship Hermes Agent plugins that pass review the first time.

Abstract. One Agent Skill and one Hermes plugin, distilled from shipping real community plugins and from the catalog reviews that followed. Any coding agent can load the skill. Installed into Hermes, it also gives the Hermes agent two small, offline tools to build plugins itself.

1 Scope

Hermes Agent has a powerful plugin system and a reviewed plugin catalog. Getting a plugin from idea to listed means learning a dozen sharp edges the hard way. This repository captures those lessons, each checked against hermes-agent source or the public catalog review threads, in a format every major coding agent can load.

1.1 The tools make no network calls, start no subprocesses, use no git and hold no credentials. They write only into the target folder you name.

1.2 The security preflight is a heuristic, not a proof.

2 Sharp edges

Failure modes listed in the README, each one learned the hard way:

  1. a stray keyword to register_tool and your plugin silently loads with 0 tools
  2. a duplicated YAML key that PyYAML quietly "fixes" for you
  3. an unquoted commit SHA the catalog validator reads as a number
  4. a dashboard API change that won't show up until you restart the gateway
  5. a security scan that fails your plugin because your README mentions a scary command word
  6. a PR that won't open because of a GitHub limit, not your auth
  7. an agent tool that can approve a stranger's device because a lobby message talked it into it
  8. a session token that leaks because authedFetch was handed an absolute asset URL
  9. a loopback "token-gated" viewer that hands the token to anyone who asks
  10. a live pane that starves the Hermes gateway because every poll runs a full capture

3 Contents

Agent Skill
skills/hermes-plugin-development/: a short core guide plus 13 deep-dive references (manifest, ctx API, all 46 hooks, capabilities and isolation, panes, testing, release and catalog, review lessons, pitfalls, hackathons, worked examples).
Template plugin
templates/hello-hermes: a minimal plugin that passes hermes plugins validate and doctor --ci as-is, with a fake-host test, strict-YAML check, version bump script and schema-token meter.
Catalog kit
Catalog entry and PR body templates matching the upstream schema, including the 6-screenshot cap.
Hermes plugin
plugin.yaml + register(ctx) at the repo root: bundles the skill and adds 2 lean tools (190 o200k tokens total).

3.1 Features

  • Bundled hermes-plugin-development skill that any coding agent can load, plus two offline Hermes tools
  • hpd_scaffold: start a plugin from a validated hello-hermes template
  • hpd_check: lint manifests, catalog entries, security preflight, and schema token cost
  • v0.3.1: hpd_check measures schema tokens statically from the AST and never imports the target plugin
  • Import-based measure is only on a user-run CLI: hermes hpd check <dir> --execute
  • Catalog kit and PR body templates, including the 6-screenshot cap
  • No network, subprocesses, or credentials; writes only into the target folder you name

4 Tools

hpd_scaffold(target_dir, name)

Creates a new plugin from the template, renamed, with a catalog entry and PR body stub. Writes only inside target_dir; refuses non-empty dirs; never overwrites.

hpd_check(path, catalog_entry?)

Offline lint, read-only. Never imports or executes the target plugin (v0.3.1 measures schema tokens statically from the AST). It inspects:

  • strict YAML
  • manifest rules
  • provides_tools vs registered (static AST)
  • security preflight
  • static schema token cost
  • catalog entry rules: sha, hosts, category, subdir, at most 6 screenshots

hermes hpd check <dir> [--execute]

A user-run CLI for the same lint. Default is static. --execute imports register() with a fake host, like hermes plugins doctor. Only use it on code you trust.

5 Applications

  1. 5.1 Ask Hermes (or another coding agent with the skill) to scaffold a new plugin from the hello-hermes template
  2. 5.2 Lint a plugin in progress with hpd_check: manifest, tools-vs-register, catalog YAML, security preflight, and o200k schema cost
  3. 5.3 Measure schema tokens without executing the target plugin's code (the v0.3.1 static path)
  4. 5.4 Follow the catalog kit to write a YAML-only catalog entry and PR body that match upstream review rules
  5. 5.5 Walk through the README example of exposing local Ollama models as one composable tool, then checking it
  6. 5.6 Install the skill into Claude Code or another Agent Skills-compatible host using the documented install matrix

6 Measurements

Table 1. Figures from the README and v0.3.1 release notes.
agent tools2
o200k schema tokens190
releasev0.3.1

README badge and text, and the v0.3.1 release notes: 2 tools, 190 o200k tokens, measured with tiktoken o200k_base. Unchanged in v0.3.1. README and release notes say tests cover a malicious __init__.py that is not executed on the tool path, and that pytest plus CI run, but they do not publish a test count.

7 Figures

  • Hermes Plugin Dev: a skill + plugin for building Hermes plugins.

The repository ships a banner only; there are no other screenshots.

8 Appendix A: submission post

No submission video was found for Hermes Plugin Dev, so the X post is embedded instead. If it does not load, open the post on X.

9 Installation

hermes plugins install mojomast/hermes-plugin-dev --ref 796a35e4d893b985f1b61d8e11b5ae7e4118bf6f
hermes plugins enable hermes-plugin-dev

Skill id: hermes-plugin-dev:hermes-plugin-development.

Claude Code (from the README install matrix): /plugin marketplace add mojomast/hermes-plugin-dev then /plugin install hermes-plugin-dev@hermes-plugin-dev.

The security preflight is a heuristic, not a proof.

10 References

Original