Build a Hermes Plugin

Build a maintainable Hermes plugin with a clear manifest, precise tool schemas, safe handlers, lifecycle hooks, and a verification path. This guide focuses on the public implementation contract; the official Hermes documentation remains the source of truth as interfaces evolve.

How the interface works

Choose the correct extension surface before writing code: a general plugin is for custom tools, hooks, slash commands, skills, or CLI subcommands; specialized providers and gateway adapters have separate contracts.

A directory plugin normally begins with plugin.yaml, a register(ctx) entry point, schemas that tell the model when to call each tool, and handlers that perform the work.

Keep schemas narrow and descriptive. Handlers should accept args plus **kwargs, catch operational errors, and return JSON strings so failures remain visible to the model.

Use requires_env for credentials or dependencies, and never put secret values in the manifest, examples, or source control. Distribution can use a local plugin directory or a Python package entry point.

Practical checklist

• Create the plugin in an isolated test profile or temporary HERMES_HOME.
• Declare only the tools, hooks, commands, and bundled assets the plugin actually provides.
• Validate every input again inside the handler; the schema guides the model but is not a security boundary.
• Exercise success, invalid-input, missing-credential, and provider-failure paths.
• Enable the plugin through Hermes and confirm its tools or commands appear in a fresh session.

Common pitfalls

• Using the general plugin API for a specialized backend that has its own provider ABC.
• Returning a Python dict instead of the required JSON string from a tool handler.
• Omitting **kwargs, which makes handlers brittle as host context evolves.
• Letting exceptions escape or writing vague schema descriptions such as “does stuff.”

Verification steps

1. Run the plugin tests and import it in a clean environment.
2. Open hermes plugins or the relevant tool picker and confirm discovery and setup metadata.
3. Call each tool with valid and invalid arguments; inspect the returned JSON.
4. Restart or start a fresh Hermes session, then verify the registered surface is available.

Official reference

https://hermes-agent.nousresearch.com/docs/developer-guide/plugins