mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-08 03:01:47 +00:00
docs(plugins): close the gaps \u2014 image-gen-provider-plugin guide + publishing a skill tap (#20800)
Two pluggable surfaces were mentioned in the interfaces map without a
real authoring guide behind them:
1. **Image-gen backends** — only had 'See bundled examples' pointers.
Now a full developer-guide/image-gen-provider-plugin.md (270 lines)
mirroring the memory/context/model provider docs:
- How discovery works, directory structure, plugin.yaml
- ImageGenProvider ABC with every overridable method
(name, display_name, is_available, list_models, default_model,
get_setup_schema, generate)
- Full authoring walkthrough with a working MyBackendImageGenProvider
- Response-format reference (success_response / error_response)
- Handling b64 vs URL output (save_b64_image helper)
- User overrides at ~/.hermes/plugins/image_gen/<name>/
- Testing recipe + pip distribution
- Reference examples (openai, openai-codex, xai)
2. **Skill taps** — features/skills.md mentioned the CLI commands but
never explained the repo contract for publishing a tap. Added
'Publishing a custom skill tap' section under Skills Hub covering:
- Repo layout (skills/<name>/SKILL.md by default)
- Minimal working example
- Non-default path configuration (taps.json)
- Installing individual skills without subscribing
- Trust-level handling
- Full tap management CLI + in-session /skills tap commands
Wired into:
- website/sidebars.ts: image-gen-provider-plugin added to Extending group
- website/docs/user-guide/features/plugins.md: pluggable interfaces
table + 'What plugins can do' table now link to the real guides
instead of 'See bundled examples'
- website/docs/guides/build-a-hermes-plugin.md: top info map and
inline sub-sections updated, 'Full guide:' line added to
image-gen block, tap section mentions publishing
Verified: docusaurus build SUCCESS, new page renders at
/docs/developer-guide/image-gen-provider-plugin, anchor
#publishing-a-custom-skill-tap resolves from plugins.md +
build-a-hermes-plugin.md. Pre-existing zh-Hans broken links unchanged.
This commit is contained in:
Teknium
GitHub
parent
ad7aad251c
commit
773cf48c50
5 changed files with 413 additions and 7 deletions
|
|
@ -108,7 +108,7 @@ Every `ctx.*` API below is available inside a plugin's `register(ctx)` function.
|
|||
| Gate on env vars | `requires_env: [API_KEY]` in plugin.yaml — prompted during `hermes plugins install` |
|
||||
| Distribute via pip | `[project.entry-points."hermes_agent.plugins"]` |
|
||||
| Register a gateway platform (Discord, Telegram, IRC, …) | `ctx.register_platform(name, label, adapter_factory, check_fn, ...)` — see [Adding Platform Adapters](/docs/developer-guide/adding-platform-adapters) |
|
||||
| Register an image-generation backend | `ctx.register_image_gen_provider(provider)` — see `plugins/image_gen/openai/` for an example |
|
||||
| Register an image-generation backend | `ctx.register_image_gen_provider(provider)` — see [Image Generation Provider Plugins](/docs/developer-guide/image-gen-provider-plugin) |
|
||||
| Register a context-compression engine | `ctx.register_context_engine(engine)` — see [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) |
|
||||
| Register a memory backend | Subclass `MemoryProvider` in `plugins/memory/<name>/__init__.py` — see [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) (uses a separate discovery system) |
|
||||
| Register an inference backend (LLM provider) | `register_provider(ProviderProfile(...))` in `plugins/model-providers/<name>/__init__.py` — see [Model Provider Plugins](/docs/developer-guide/model-provider-plugin) (uses a separate discovery system) |
|
||||
|
|
@ -228,11 +228,11 @@ The table above shows the four plugin categories, but within "General plugins" t
|
|||
| A **gateway channel** (Discord / Telegram / IRC / Teams / etc.) | Platform plugin — `ctx.register_platform()` in `plugins/platforms/<name>/` | [Adding Platform Adapters](/docs/developer-guide/adding-platform-adapters) |
|
||||
| A **memory backend** (Honcho, Mem0, Supermemory, …) | Memory plugin — subclass `MemoryProvider` in `plugins/memory/<name>/` | [Memory Provider Plugins](/docs/developer-guide/memory-provider-plugin) |
|
||||
| A **context-compression strategy** | Context-engine plugin — `ctx.register_context_engine()` | [Context Engine Plugins](/docs/developer-guide/context-engine-plugin) |
|
||||
| An **image-generation backend** (DALL·E, SDXL, …) | Backend plugin — `ctx.register_image_gen_provider()` | See bundled examples in `plugins/image_gen/openai/` and `plugins/image_gen/xai/` |
|
||||
| An **image-generation backend** (DALL·E, SDXL, …) | Backend plugin — `ctx.register_image_gen_provider()` | [Image Generation Provider Plugins](/docs/developer-guide/image-gen-provider-plugin) |
|
||||
| A **TTS backend** (any CLI — Piper, VoxCPM, Kokoro, xtts, voice-cloning scripts, …) | Config-driven — declare under `tts.providers.<name>` with `type: command` in `config.yaml` | [TTS setup](/docs/user-guide/features/tts#custom-command-providers) |
|
||||
| An **STT backend** (custom whisper binary, local ASR CLI) | Config-driven — set `HERMES_LOCAL_STT_COMMAND` env var to a shell template | [Voice Message Transcription (STT)](/docs/user-guide/features/tts#voice-message-transcription-stt) |
|
||||
| **External tools via MCP** (filesystem, GitHub, Linear, Notion, any MCP server) | Config-driven — declare `mcp_servers.<name>` with `command:` / `url:` in `config.yaml`. Hermes auto-discovers the server's tools and registers them alongside built-ins. | [MCP](/docs/user-guide/features/mcp) |
|
||||
| **Additional skill sources** (custom GitHub repos, private skill indexes) | CLI — `hermes skills tap add <repo>` | [Skills Hub](/docs/user-guide/features/skills#skills-hub) |
|
||||
| **Additional skill sources** (custom GitHub repos, private skill indexes) | CLI — `hermes skills tap add <repo>` | [Skills Hub](/docs/user-guide/features/skills#skills-hub) · [Publishing a custom tap](/docs/user-guide/features/skills#publishing-a-custom-skill-tap) |
|
||||
| **Gateway event hooks** (fire on `gateway:startup`, `session:start`, `agent:end`, `command:*`) | Drop `HOOK.yaml` + `handler.py` into `~/.hermes/hooks/<name>/` | [Event Hooks](/docs/user-guide/features/hooks#gateway-event-hooks) |
|
||||
| **Shell hooks** (run a shell command on events — notifications, audit logs, desktop alerts) | Config-driven — declare under `hooks:` in `config.yaml` | [Shell Hooks](/docs/user-guide/features/hooks#shell-hooks) |
|
||||
|
||||
|
|
|
|||
|
|
@ -464,6 +464,119 @@ This uses the stored source identifier plus the current upstream bundle content
|
|||
Skills hub operations use the GitHub API, which has a rate limit of 60 requests/hour for unauthenticated users. If you see rate-limit errors during install or search, set `GITHUB_TOKEN` in your `.env` file to increase the limit to 5,000 requests/hour. The error message includes an actionable hint when this happens.
|
||||
:::
|
||||
|
||||
### Publishing a custom skill tap
|
||||
|
||||
If you want to share a curated set of skills — for your team, your org, or publicly — you can publish them as a **tap**: a GitHub repository other Hermes users add with `hermes skills tap add <owner/repo>`. No server, no registry sign-up, no release pipeline. Just a directory of `SKILL.md` files.
|
||||
|
||||
#### Repo layout
|
||||
|
||||
A tap is any GitHub repo (public or private — private needs `GITHUB_TOKEN`) laid out like this:
|
||||
|
||||
```
|
||||
owner/repo
|
||||
├── skills/ # default path; configurable per-tap
|
||||
│ ├── my-workflow/
|
||||
│ │ ├── SKILL.md # required
|
||||
│ │ ├── references/ # optional supporting files
|
||||
│ │ ├── templates/
|
||||
│ │ └── scripts/
|
||||
│ ├── another-skill/
|
||||
│ │ └── SKILL.md
|
||||
│ └── third-skill/
|
||||
│ └── SKILL.md
|
||||
└── README.md # optional but helpful
|
||||
```
|
||||
|
||||
Rules:
|
||||
- Each skill lives in its own directory under the tap's root path (default `skills/`).
|
||||
- The directory name becomes the skill's install slug.
|
||||
- Each skill directory must contain a `SKILL.md` with standard [SKILL.md frontmatter](#skillmd-format) (`name`, `description`, plus optional `metadata.hermes.tags`, `version`, `author`, `platforms`, `metadata.hermes.config`).
|
||||
- Subdirectories like `references/`, `templates/`, `scripts/`, `assets/` are downloaded alongside `SKILL.md` at install time.
|
||||
- Skills whose directory name starts with `.` or `_` are ignored.
|
||||
|
||||
Hermes discovers skills by listing every subdirectory of the tap path and probing each for `SKILL.md`.
|
||||
|
||||
#### Minimal tap example
|
||||
|
||||
```
|
||||
my-org/hermes-skills
|
||||
└── skills/
|
||||
└── deploy-runbook/
|
||||
└── SKILL.md
|
||||
```
|
||||
|
||||
`skills/deploy-runbook/SKILL.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: deploy-runbook
|
||||
description: Our deployment runbook — services, rollback, Slack channels
|
||||
version: 1.0.0
|
||||
author: My Org Platform Team
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [deployment, runbook, internal]
|
||||
---
|
||||
|
||||
# Deploy Runbook
|
||||
|
||||
Step 1: ...
|
||||
```
|
||||
|
||||
After pushing that to GitHub, any Hermes user can subscribe and install:
|
||||
|
||||
```bash
|
||||
hermes skills tap add my-org/hermes-skills
|
||||
hermes skills search deploy
|
||||
hermes skills install my-org/hermes-skills/deploy-runbook
|
||||
```
|
||||
|
||||
#### Non-default paths
|
||||
|
||||
If your skills don't live under `skills/` (common when you're adding a `skills/` subtree to an existing project), edit the tap entry in `~/.hermes/.hub/taps.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"taps": [
|
||||
{"repo": "my-org/platform-docs", "path": "internal/skills/"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The `hermes skills tap add` CLI defaults new taps to `path: "skills/"`; edit the file directly if you need a different path. `hermes skills tap list` shows the effective path per tap.
|
||||
|
||||
#### Installing individual skills directly (without adding a tap)
|
||||
|
||||
Users can also install a single skill from any public GitHub repo without adding the whole repo as a tap:
|
||||
|
||||
```bash
|
||||
hermes skills install owner/repo/skills/my-workflow
|
||||
```
|
||||
|
||||
Useful when you want to share one skill without asking the user to subscribe to your whole registry.
|
||||
|
||||
#### Trust levels for taps
|
||||
|
||||
New taps are assigned `community` trust by default. Skills installed from them run through the standard security scan and show the third-party warning panel on first install. If your org or a widely-trusted source should get higher trust, add its repo to `TRUSTED_REPOS` in `tools/skills_hub.py` (requires a Hermes core PR).
|
||||
|
||||
#### Tap management
|
||||
|
||||
```bash
|
||||
hermes skills tap list # show all configured taps
|
||||
hermes skills tap add myorg/skills-repo # add (default path: skills/)
|
||||
hermes skills tap remove myorg/skills-repo # remove
|
||||
```
|
||||
|
||||
Inside a running session:
|
||||
|
||||
```
|
||||
/skills tap list
|
||||
/skills tap add myorg/skills-repo
|
||||
/skills tap remove myorg/skills-repo
|
||||
```
|
||||
|
||||
Taps are stored in `~/.hermes/.hub/taps.json` (created on demand).
|
||||
|
||||
## Bundled skill updates (`hermes skills reset`)
|
||||
|
||||
Hermes ships with a set of bundled skills in `skills/` inside the repo. On install and on every `hermes update`, a sync pass copies those into `~/.hermes/skills/` and records a manifest at `~/.hermes/skills/.bundled_manifest` mapping each skill name to the content hash at the time it was synced (the **origin hash**).
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue