hermes-plugin-development

Design, register, and debug Hermes Agent backend and desktop plugins.

115|9|Updated Aug 5, 2026
One-click install
npx skills add https://github.com/AtlasOmnia/donna-starter --skill hermes-plugin-development-atlasomnia
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hermes-plugin-development
Source: https://github.com/AtlasOmnia/donna-starter/tree/main/skills/hermes-plugin-development
Command: npx skills add https://github.com/AtlasOmnia/donna-starter --skill hermes-plugin-development-atlasomnia

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building plugins for the Hermes Agent involves many failure-prone details: hook registration semantics, YAML manifest wiring, profile detection, token routing, and live deployment verification. This Skill captures proven patterns and debugging workflows so plugins load, fire, and behave correctly the first time. ## Core Features & Use Cases - Plugin architecture guidance: Covers Python backend plugins (tools, hooks, routers, middleware) and JavaScript Hermes Desktop runtime plugins, including the two-surface pattern for Desktop slash commands. - Hook and YAML wiring rules: Enforces provides_hooks manifests, public hook function naming, profile-safe detection, and runtime hook-composition contracts that prevent silent registration failures. - Token router and prefetch patterns: Provides production-hardened designs for tool-surface routing, deterministic read-only prefetch, external model-gateway affinity, and fail-open classifier integration. - Deployment and debugging playbooks: Includes fail-closed policy plugin deployment, live API-server contract validation, public distribution checklists, and debugging checklists for plugins that load but do nothing. - Use Case: You wrote a Hermes plugin whose hooks never fire. This Skill walks you through checking provides_hooks vs hooks, verifying public function names, and adding correctly placed debug prints to confirm invocation. ## Quick Start Ask the agent to help you create a new Hermes backend plugin with a pre_llm_call hook and a valid plugin.yaml manifest.

Frequently Asked Questions about hermes-plugin-development

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a Hermes Agent plugin with hooks?

Create a directory under ~/.hermes/plugins/<name>/ with an __init__.py containing a register(ctx) function and a plugin.yaml manifest. Declare hooks with provides_hooks (not hooks) and register public functions via ctx.register_hook().

Why is my Hermes plugin loaded but its hooks never fire?

The most common cause is declaring hooks: instead of provides_hooks: in plugin.yaml, or naming functions with underscore prefixes that don't match registration names. Also verify the hooks exist in the runtime's live hook registry and add print() statements after docstrings to confirm invocation.

How do I detect the active Hermes profile inside a plugin?

Do not trust HERMES_PROFILE blindly since --profile does not reliably set it. Prefer explicit HERMES_PROFILE or HERMES_ACTIVE_PROFILE when present, otherwise infer from the canonical HERMES_HOME path containing profiles/<name>, and fail disabled when identity is unknown.

Can a Hermes backend plugin open a Desktop UI or TUI modal?

No. Backend plugin slash handlers only return text and cannot open prompt_toolkit modals or Desktop popovers. Desktop UI requires a JavaScript runtime plugin using @hermes/plugin-sdk, optionally bridged with a backend plugin for command inventory.

What is the difference between Hermes backend plugins and Desktop runtime plugins?

Backend plugins are Python packages under ~/.hermes/plugins/ that add tools, hooks, commands, and middleware. Desktop runtime plugins are plain ESM plugin.js files under $HERMES_HOME/desktop-plugins/ that contribute native UI through @hermes/plugin-sdk and hot-reload on file changes.

How do I prepare a Hermes plugin for public GitHub distribution?

Stage a clean tree with source, manifest, sample config, tests, README, LICENSE, and packaging files, excluding caches, credentials, and local profile state. Make config disabled-by-default, document privacy and data egress, and run py_compile, pytest, and a privacy grep before committing.