Skip to content
Skills Library
AI & agents · Building & coding

hermes-plugin-development

/hermes-plugin-development

Build, test, release, and list plugins for Hermes Agent (NousResearch/hermes-agent): plugin.yaml manifests, register(ctx) tools and hooks, bundled skills, dashboard and desktop panes, secrets, doctor/validate, catalog SHA pins and PRs, deploy/rollback, and the pitfalls hit shipping real community plugins. Use whenever a task touches a Hermes plugin.

Licence
MIT
Last repository change
11.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
25
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: templates/hello-hermes/__init__.py, templates/hello-hermes/scripts/bump_plugin_version.py, templates/hello-hermes/scripts/measure_schemas.py, templates/hello-hermes/tests/test_plugin.py

What it does and when to use it

Build, test, release, and list plugins for Hermes Agent (NousResearch/hermes-agent): plugin.yaml manifests, register(ctx) tools and hooks, bundled skills, dashboard and desktop panes, secrets, doctor/validate, catalog SHA pins and PRs, deploy/rollback, and the pitfalls hit shipping real community plugins. Use whenever a task touches a Hermes plugin.

Original author description

Build, test, release, and list plugins for Hermes Agent (NousResearch/hermes-agent): plugin.yaml manifests, register(ctx) tools and hooks, bundled skills, dashboard and desktop panes, secrets, doctor/validate, catalog SHA pins and PRs, deploy/rollback, and the pitfalls hit shipping real community plugins. Use whenever a task touches a Hermes plugin.

How it works

  1. 1. Anatomy
  2. 2. Manifest essentials (references/plugin-yaml.md)
  3. 3. Tools (references/tools-and-hooks.md)
  4. 4. Skills, state, secrets
  5. 5. UI surfaces (references/panes.md)
  6. 6. Test (references/testing.md)
  7. 7. Release → catalog (references/release-and-catalog.md)
  8. 8. Deploy to a running Hermes (references/release-and-catalog.md)
  9. 9. Top pitfalls (full table: references/pitfalls.md)
  10. 10. Hackathons and demos
Original SKILL.md headings · 283 lines, 2,245 words
SKILL.md preview
---
name: hermes-plugin-development
description: >-
  Build, test, release, and list plugins for Hermes Agent (NousResearch/hermes-agent):
  plugin.yaml manifests, register(ctx) tools and hooks, bundled skills, dashboard and
  desktop panes, secrets, doctor/validate, catalog SHA pins and PRs, deploy/rollback,
  and the pitfalls hit shipping real community plugins. Use whenever a task touches a
  Hermes plugin.
license: MIT
---
# Hermes plugin development

Field guide distilled from shipping several community Hermes plugins (map/OSINT
dashboard, virtual pets game, live-coding music studio, video tooling, a shared
QEMU screen, a film studio, an embroidery bridge) and from catalog reviews of
those plugins through 10 Nov 2026. Every API and CLI claim here was checked
against hermes-agent source or, where noted, against those reviews; see
`references/verification.md`. Hook names, capabilities, and admission lints were
re-verified against hermes-agent `main` at `acdc8f1ba6` (2026-11-08).
**When this file and the live Hermes source/docs disagree, the source wins.**

Canonical upstream docs (paths inside `NousResearch/hermes-agent`):

| Topic | Path |
|---|---|
| Build a plugin | `website/docs/developer-guide/plugins/index.md` |
| Public plugin API (generated allowlist) | `website/docs/developer-guide/plugins/public-api.md`, `hermes_cli/data/plugin_api.json` |
| Catalog submission | `website/docs/developer-guide/plugins/catalog-submission.md` |
| Catalog admission rules + entry schema | `plugin-catalog/README.md` |
| Dashboard plugins | `website/docs/user-guide/features/extending-the-dashboard.md` |
| Desktop pane SDK | `website/docs/developer-guide/desktop-plugin-sdk.md` |
| Provider guides (model, memory, context engine, image/video, web search, browser, TTS/STT, delegation, terminal, secret source) | `website/docs/developer-guide/*-plugin.md` |
| Desktop-app declarations (`app:` / `requires:`) | `website/docs/developer-guide/plugins/application-declarations.md` |
| `ctx` implementation | `hermes_cli/plugins_context.py` (`PluginContext`, re-exported from `hermes_cli.plugins`) |
| Manifest parser, registrar table, capabilities | `hermes_cli/plugins_manifest.py`, `hermes_cli/plugins_registrars.py`, `hermes_cli/plugin_capabilities.py` |
| Validator / doctor | `hermes_cli/plugin_validate*.py`, `hermes_cli/subcommands/plugins.py` |

Third-party plugins live in **their own repos**. They reach users by
`hermes plugins install owner/repo[/subdir]` or by a catalog entry, never by a
PR into Hermes core.

## 1. Anatomy

```text
my-plugin/
├── plugin.yaml        # manifest (required for native plugins)
├── __init__.py        # def register(ctx) -> None   (required)
├── pyproject.toml     # deps with upper bounds (wins over python_dependencies)
├── skills/<id>/SKILL.md   # optional bundled skills
├── dashboard/         # optional web dashboard tab: manifest.json, dist/index.js, plugin_api.py
├── desktop/plugin.js  # optional desktop/webapp pane via @hermes/plugin-sdk
├── tests/
├── README.md  LICENSE
```

- Hermes discovers `~/.hermes/plugins/<name>/` (one category level allowed).
  Symlinking a checkout there is the normal dev loop.
- Plugin in a subfolder of a bigger repo? Use `subdir:` in the catalog entry and
  `hermes plugins install owner/repo/sub/path`. Keeps evals, art and fixtures
  out of the installed tree.
- A working skeleton that passes `validate` and `doctor`: `templates/hello-hermes/`.

## 2. Manifest essentials (`references/plugin-yaml.md`)

```yaml
manifest_version: 2
api_version: 1
name: my-plugin            # [a-z0-9_-]{1,64}; the catalog key
version: "0.1.0"           # QUOTE IT
description: What it does. Disclosure: network, subprocesses, threads, credentials.
requires_hermes: ">=0.21.6"   # SemVer floor only; ">=0.23.0" if you use Desktop ctx.rest
provides_tools: [my_tool]     # must equal what register() registers
provides_hooks: []
requires_env: []
capabilities: []              # privileged host surfaces; see below
```

- `provides_tools`/`provides_hooks` don't gate loading, but `validate` and
  catalog CI fail if they drift from real registrations.
- Unknown keys are tolerated with a warning; don't rely on invented keys doing anything.
  `provides_middleware` is **not** a manifest field — it is a catalog
  `capabilities:` key that `validate` compares against real middleware
  registrations. Putting it in `plugin.yaml` logs an unknown-field warning.
- Duplicate keys are silently "last one wins" in PyYAML. Test with a strict loader.
- **Privileged surfaces need a declared capability** (`tools.override`,
  `llm.model_override`, `llm.side_question`, `gateway.platform_actions`, …).
  The user consents once at install/enable; undeclared or unconsented is off.
  Probe `ctx.has_capability("<id>")` and degrade gracefully — never crash or
  silently switch behaviour when it is missing. `hermes plugins capabilities`
  prints declared vs granted.
  Details: `references/capabilities-and-isolation.md`.
- `plugins.isolation: host` (a user config, not yours) moves plugins into a
  separate process and refuses a few surfaces outright. Same reference.

## 3. Tools (`references/tools-and-hooks.md`)

Verified signature (`hermes_cli/plugins_context.py`; `plugin.yaml` fields, hook
names and every `register_*` method live in the sibling `plugins_*.py` modules):

```text
ctx.register_tool(name, toolset, schema, handler, check_fn=None, requires_env=None,
                  is_async=False, description="", emoji="", override=False)
```

- **Call with keywords only.** Passing an unsupported kw (e.g. `output_schema`)
  raises `TypeError`, aborts `register()`, and the plugin loads with **0 tools**.
  Filter kwargs against `inspect.signature` (template does this).
- `register()` must be fast and offline. Lazy-import heavy deps in handlers.
- **Lean tool surface.** Every schema is sent on every turn. Prefer a few
  composable tools with an `op` enum over dozens of tiny ones (one plugin went
  from ~70 tools to 11). Measure with tiktoken `o200k_base` before/after and
  report the delta (`templates/hello-hermes/scripts/measure_schemas.py`).
- Return a **JSON string** (`json.dumps`) with
  `{"ok": false, "code": ..., "error": ..., "fix": ...}` so the agent can
  recover. Scrub secrets from those fields. Handlers that return dicts are
  rejected by the host.
- Hook callbacks should accept `**kwargs`; payloads gain fields over time
  (46 hook names at the verified commit — `references/hooks.md`).
- Tools that run a model-named script need a `pre_tool_call` approval hook
  (`{"action": "approve", ...}`) and a `provides_hooks` entry. Hooks that fire
  on every call must not police the user's other projects.
- Privileged online actions (pairing, spend, device grants) stay **pane-only**
  or go through that approval prompt — see `references/catalog-review-lessons.md`.
- `override=True` needs the `tools.override` capability granted (or the legacy
  `plugins.entries.<id>.allow_tool_override: true`); otherwise it raises.
- `ctx.call_mcp` is default-deny (per-plugin MCP allowlist).
- `ctx.has_capability(id)` / `ctx.side_question(token, prompt)` sit on the
  capability mixin; treat a missing capability as "feature off", not an error.

## 4. Skills, state, secrets

- `ctx.register_skill(name, path)` makes a read-only skill resolvable as
  `<plugin_name>:<name>` via `skill_view`. Keep skill text in sync with tool names.
  If Hermes Tool Search defers your tools, the skill and a system-prompt section
  should name them and tell the agent to `tool_search` / `skill_view`.
- Persist state with `plugins.plugin_storage.plugin_data_dir(name)` /
  `plugin_db(name)`: profile-aware, survives updates. Never write into the checkout.
- **Secrets:** declare in `requires_env` (or `config_schema` secret), read with
  `agent.secret_scope.get_secret(NAME)`. No `.env` file reads, no raw process-environment
  fallbacks, no vendor CLI/browser/keychain token scraping (catalog rule 11).
  Token files you create yourself: mode `0600`, never logged.
- **Respect user choices.** Never re-enable a layer, feature, companion, or
  setting the user turned off; persist "off" and treat it as authoritative
  across restarts and updates.

## 5. UI surfaces (`references/panes.md`)

- **Dashboard tab:** `dashboard/manifest.json` + an IIFE bundle using
  `window.__HERMES_PLUGIN_SDK__` (don't bundle React; import hooks from `react`,
  not `react/jsx-runtime`). Optional `plugin_api.py` routes mount at
  `/api/plugins/<name>/`. **Never pass an absolute `http(s):` URL to
  `SDK.authedFetch`** — only relative plugin routes, or you leak the session token.
- **An already-mounted `/api/plugins/<name>/` route is not re-mounted.** After
  changing `plugin_api.py`, restart the gateway/dashboard process. The
  `/api/dashboard/plugins/rescan` endpoint is for discovering newly added plugins.
  Enabling the desktop half does not import Python by itself.
- **Desktop pane:** `desktop/plugin.js` importing only `@hermes/plugin-sdk` (and `react`).
  Guest content runs in `SandboxedFrame` (opaque origin). No prototype patching,
  `eval`, app-chunk imports, or core DOM scraping (catalog rule 8). Use `ctx.rest`
  and set `requires_hermes: ">=0.23.0"`.
- Default to **dark mode**. Shared screens need Watch / Shared / Take control.
  Live frames come from a background cache so polling does not starve the
  gateway. Loopback relays are token-gated on every route and bind `127.0.0.1`.

## 6. Test (`references/testing.md`)

```bash
pytest -q                                  # fake ctx, no Hermes needed
hermes plugins doctor <path|id> --ci       # real runtime contracts
hermes plugins validate <path> --install-deps   # same gate as catalog CI
```

- Fake-ctx test asserting registered names == `provides_tools` is the single
  most valuable test.
- No Hermes available? Build a mock host (fake ctx + in-memory pane/session) and
  label results "mock host" vs "verified in Hermes" honestly in the README.
- The install scanner reads **every file, Markdown included**. Merely mentioning the
  superuser command word (su+do), env-dump or filesystem-format commands, or raw
  environment reads trips `sudo_usage`-style findings and can fail `validate`.
  Rephrase docs and strings, or explain the finding in the PR.
- Before asking for a catalog review, also do a **scratch-home catalog install**
  and a live connected-pane test. After a test on a shared host, restore the
  plugin's prior enablement (disable it if it was off).

## 7. Release → catalog (`references/release-and-catalog.md`)

1. Tests + doctor + validate green. Secret-scan the tree.
2. Bump `version` in `plugin.yaml` (and `pyproject.toml`); merge to main.
3. Only if explicitly authorized, tag `vX.Y.Z` at that commit → GitHub release.
   A version bump is not a tag.
4. On **your fork** of hermes-agent, branch `catalog/<name>-vX.Y.Z`, add or edit
   **only** `plugin-catalog/<name>.yaml`: full 40-hex `sha` (quoted), quoted
   `version`, capabilities matching the pin, images on GitHub raw hosts pinned
   to the same sha and returning HTTP 200. At most **6 screenshots** (the
   validator refuses 7). Never invent a self-referential SHA.
5. `python scripts/validate_plugin_catalog.py plugin-catalog/<name>.yaml`.
6. Open the PR from the fork (`templates/catalog/PR_BODY.md`). Every SHA bump is a new PR.

**PR gotchas:** contributors without write access may have at most **5 open PRs**
on NousResearch/hermes-agent. Over that, `CreatePullRequest` fails with a
permissions error from the CLI, API and GitHub-App integrations alike, even
though your auth is fine. Close or land one, or open it in the web UI from
the compare link once a slot is free. Closing a PR to free a slot is not a
review verdict; resubmit later. Reviewers may approve and then come back
after a full-tree re-read — answer point-by-point with old → new sha.

## 8. Deploy to a running Hermes (`references/release-and-catalog.md`)

Get the owner's OK first. Back up the checkout and record the current HEAD as
the **rollback SHA**. Check out the target, install deps if changed, restart only
what's needed (gateway for `plugin_api.py`/hook changes), then `hermes plugins
doctor <id>` and exercise one real tool. On failure: check out the rollback SHA,
restart, re-run doctor. After a live test on a shared host, surgically restore
only the enablement you changed.

## 9. Top pitfalls (full table: `references/pitfalls.md`)

| Symptom | Fix |
|---|---|
| Plugin loads with 0 tools | Unsupported kw to `register_tool` raised in `register()`. Filter kwargs. |
| validate: declared tools mismatch | Make `provides_tools` identical to registrations. |
| Catalog validator: "sha 0 must be 40 hex" | Quote the sha; an all-digit sha parses as an int. |
| Dashboard API change has no effect | Route already mounted; restart the gateway. |
| Key works in shell, not in plugin | Declare `requires_env`; read via `get_secret`. |
| `CreatePullRequest` permission error | 5-open-PR cap or not from a fork; free a slot. |
| Context bloat / slow turns | Fewer composable tools; measure o200k. |
| validate security scan fails on docs | Scanner reads Markdown too; reword risky command words. |
| Agent grants pairing / spend | Keep it pane-only (`unsupported_online`) or require Hermes approval. |
| Session token sent to another host | Never pass an absolute URL to `authedFetch`. |
| Anyone on the LAN drives the viewer | Token on every route; bind loopback; allowlist `nav`. |
| Chat timeouts while the pane is open | Background frame cache; cap fps. |
| validate: `no core override` / `private import` | Patch through hooks/middleware/ctx, not `setattr` on Hermes modules; import only `public-api.md` names. |
| Feature silently off after install | Capability not declared/consented; declare it in `capabilities:` and probe `has_capability`. |
| `register_platform`/approval/Telegram plugin fails to load | User runs `plugins.isolation: host`; those surfaces need `in_process`. |
| Loader logs `unknown manifest field: provides_middleware` | It is a catalog `capabilities:` key, not a `plugin.yaml` field. |

## 10. Hackathons and demos

See `references/hackathon-submission.md`: open catalog PR (needn't be merged),
demo video under 90 s posted on X tagging the organiser, submission form.
Shoot in dark mode; start videos on a finished hero frame. Never post or
submit on someone's behalf without their explicit yes.

## Companion tools (when installed as the hermes-plugin-dev Hermes plugin)

- `hpd_scaffold(target_dir, name)`: copy `templates/hello-hermes` into a new or empty
  folder, renamed, with a catalog entry and PR body stub.
- `hpd_check(path, catalog_entry?)`: offline lint covering strict YAML, manifest rules,
  `provides_tools` vs registered (from a static AST parse), security preflight,
  static o200k schema tokens, core-override rebinds, imports outside the public
  API, and catalog entry rules (including the 6-screenshot cap). It never
  imports the target plugin.
- `hermes hpd check <dir> [--execute]`: user-run CLI for the same lint. Default
  is static. `--execute` imports `register()` with a fake host, like
  `hermes plugins doctor` — only on code you trust.

Then run `hermes plugins doctor` and `validate` in a terminal for the
authoritative gate. Other agents can call `hpd_core.check` or
`python hpd_cli.py check <dir>`.

## Files in this skill

| Path | Purpose |
|---|---|
| `references/plugin-yaml.md` | Manifest fields |
| `references/tools-and-hooks.md` | `ctx` API, schema design, skills, secrets, storage |
| `references/hooks.md` | Every hook name + payload notes |
| `references/capabilities-and-isolation.md` | Capability ids, consent, `plugins.isolation` |
| `references/panes.md` | Dashboard and desktop panes, relays, dark mode, frame cache |
| `references/testing.md` | Fake ctx, mock host, doctor, validate, scanner, live gate |
| `references/release-and-catalog.md` | Versioning, tags, catalog entry, PRs, deploy, rollback |
| `references/catalog-review-lessons.md` | Review contracts from Nov 2026 catalog threads |
| `references/pitfalls.md` | Symptom → cause → fix |
| `references/hackathon-submission.md` | Demo + submission playbook |
| `references/worked-examples.md` | Public plugin repos to study |
| `references/verification.md` | What was verified against source, and what wasn't |
| `references/security-boundaries.md` | SSRF, secrets, path confinement, honest clients |
| `templates/hello-hermes/` | Minimal plugin that passes validate + doctor |
| `templates/catalog/` | Catalog entry + PR body templates |

## Catalog security and live acceptance (mandatory)

Read [security boundaries](references/security-boundaries.md) and
[catalog review lessons](references/catalog-review-lessons.md) before
implementation. Apply the review contracts in panes, tools-and-hooks,
release-and-catalog, testing and verification references. All tool boundaries
serialize JSON strings; UI authentication stays inside SDK transports; URL,
file and subprocess boundaries fail closed. Untrusted feed text is data, not
instructions. Privileged account actions stay in the pane. Run security
preflight plus adversarial tests and actual connected-pane/online acceptance
before a conditional merge. Never infer posting, tagging or deployment
permission from this guide.
Files in this package (25)
  • SKILL.md 17 KB
  • references/capabilities-and-isolation.md 5 KB
  • references/catalog-review-lessons.md 12 KB
  • references/hackathon-submission.md 2 KB
  • references/hooks.md 5 KB
  • references/panes.md 7 KB
  • references/pitfalls.md 7 KB
  • references/plugin-yaml.md 5 KB
  • references/release-and-catalog.md 6 KB
  • references/security-boundaries.md 5 KB
  • references/testing.md 4 KB
  • references/tools-and-hooks.md 10 KB
  • references/verification.md 8 KB
  • references/worked-examples.md 2 KB
  • templates/catalog/PR_BODY.md 2 KB
  • templates/catalog/plugin-catalog-entry.yaml 2 KB
  • templates/hello-hermes/LICENSE 1 KB
  • templates/hello-hermes/README.md 1 KB
  • templates/hello-hermes/__init__.py 2 KB
  • templates/hello-hermes/plugin.yaml 1 KB
  • templates/hello-hermes/pyproject.toml 1 KB
  • templates/hello-hermes/scripts/bump_plugin_version.py 2 KB
  • templates/hello-hermes/scripts/measure_schemas.py 1 KB
  • templates/hello-hermes/skills/hello-hermes/SKILL.md 1 KB
  • templates/hello-hermes/tests/test_plugin.py 3 KB

Versions

The database has no other skills named hermes-plugin-development.

Database snapshot: 13.11.2026 · package version 622b0ffdb543 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 96hermes-plugin-inspection
    Use when asked to count or health-check Hermes plugins.
  • 90hermes-extend
    Use when extending Hermes Agent - writing or installing Hermes skills (SKILL.md format, ~/.hermes/skills, agent-created skills, skill_manage, curator, skills.write_approval), installing and managing plugins (catalog, plugins.enabled, auto-update, pinned refs), choosing a memory…
  • 96hermes-agent-factory
    Use when creating or cloning a Hermes agent profile.
  • 100hermes-agent-compatibility
    Audit Socket-to-Hermes compatibility across Agent Skills, Codex plugins, MCP, hooks, apps, agents, and Hermes extension systems. Use for skill exports, config translations, and Hermes adapter decisions.
  • 90hermes-tweet
    Guides agents through safe Hermes Tweet X/Twitter plugin setup, read workflows, and explicit action gating. Use when installing Hermes Tweet, checking its Hermes Agent integration, or choosing read versus action tools.
  • 86hermes-box-diagnosis
    Use when hermes-agent loops or its memory is full.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.