---
name: choose-hermes-agent-workflow
description: Route Hermes Agent work to the correct operator, extension-development, messaging-gateway, Nous services, or Socket compatibility workflow. Use when a request spans surfaces or its extension boundary is unclear.
metadata:
  hermes:
    category: agent-portability
    tags: [hermes, routing, extensions, gateway, nous]
---

# Choose Hermes Agent Workflow

Classify the requested outcome before opening broad documentation or changing configuration.

## Route the Request

| Requested outcome | Use |
| --- | --- |
| Install, update, configure, run, secure, troubleshoot, or use Hermes | `operate-hermes-agent` |
| Create skills, plugins, providers, tools, hooks, desktop/dashboard extensions, or programmatic integrations | `build-hermes-agent-extensions` |
| Run Hermes inside Zed, Xcode, or another ACP client | `operate-acp-agent-integration` plus the client-owning workflow |
| Let Hermes discover, call, or be called by an independently operated peer agent | `operate-a2a-agent-integration` plus gateway operation for inbound service lifecycle |
| Decide between ACP, MCP, TUI gateway, API, terminal, or native host integration | `choose-agent-integration-protocol` |
| Run a messaging gateway, API server, webhook intake, messaging platform, or long-lived remote agent | `operate-hermes-agent-gateway` |
| Use Nous Portal, Tool Gateway, Nous Chat, subscription proxy, or Hermes Cloud | `use-nous-research-services` |
| Export Socket skills, translate Socket MCP, or classify Codex-to-Hermes portability | `hermes-agent-compatibility` |

Use more than one workflow when the request genuinely crosses boundaries. Keep one workflow in charge of each write surface.

## Keep the Three Gateway Terms Separate

- `Hermes messaging gateway`: the long-running Hermes process that connects messaging platforms, webhooks, and the API server.
- `Nous Tool Gateway`: Nous-hosted backends for web, media, browser, and optional cloud terminal tools.
- `TUI gateway`: the JSON-RPC protocol used by Hermes TUI and custom host integrations.
- `ACP`: the editor-to-agent protocol used when Zed, Xcode, or another client launches and renders Hermes through `hermes acp`.
- `A2A`: the peer-agent protocol used when Hermes exchanges discovered messages
  or tasks with independently operated agents.

Never use an unqualified “gateway” in a decision or implementation note when more than one meaning is possible.
Do not describe ACP as a gateway or as a general agent-to-agent protocol.

## Select the Smallest Extension Surface

Prefer, in order:

1. A skill for instructions plus existing tools or commands.
2. MCP for an external tool server.
3. Config-driven backends or shell hooks when Hermes already defines that surface.
4. A standalone Python plugin for registered runtime behavior.
5. A specialized provider, platform, memory, context, browser, search, media, secret, desktop, or dashboard extension only when that exact subsystem owns the behavior.
6. A Hermes core contribution only when the behavior belongs in the upstream product rather than a user, project, or third-party extension.

## Source and State Rules

- Refresh the official Hermes docs for claims that can drift; the project moves quickly.
- Inspect the installed Hermes version and active profile before diagnosing local behavior.
- Keep `~/.hermes/` user state, project `.hermes/` state, standalone plugin source, and the upstream Hermes repository distinct.
- Do not mutate Portal accounts, gateway services, messaging accounts, cloud deployments, or user-home configuration unless the user requested that action.
- Do not describe a Codex or Claude plugin manifest as a Hermes plugin.

## Output Contract

Return:

1. `workflow`: the selected skill or combination.
2. `surface`: the concrete Hermes runtime, configuration, hosted service, or source tree involved.
3. `reason`: why that surface owns the request.
4. `state`: local, project, hosted, or upstream state that may change.
5. `verification`: the narrowest proof needed.

Read [references/workflow-map.md](references/workflow-map.md) when the request crosses multiple Hermes subsystems or uses an ambiguous “gateway,” “plugin,” “cloud,” or “provider” label.