Hermes agent compatibility

Hermes Agent Compatibility

Maintain Socket's deliberate compatibility boundary with Hermes Agent. Start by classifying the requested Socket surface, then choose the narrowest Hermes surface that preserves its real behavior.

Surface Map

Socket surface	Hermes equivalent	Compatibility outcome
SKILL.md workflow	GitHub skill tap or direct GitHub skill install	Export when the workflow is portable instructions plus existing tools.
Codex plugin bundle	None	Do not present .codex-plugin/plugin.json as a Hermes plugin. Keep it as Codex packaging only.
.mcp.json server declaration	mcp_servers entry in ~/.hermes/config.yaml	Translate the transport and required environment, then validate the server in Hermes.
Hook, app, or custom-agent surface	Host-specific decision	Document the limit or build a real Hermes extension only if a concrete behavior needs it.
Runtime integration with tools, hooks, commands, or bundled skills	Python Hermes plugin	Use plugin.yaml plus register(ctx) only when instruction-only or MCP configuration cannot express the behavior.

Maintain the Skill Tap

Socket's Hermes tap is the checked-in root skills/ export. Its authored source remains plugins/agent-portability-skills/skills/; do not edit the export manually.

1. Add or revise the authored skill under plugins/agent-portability-skills/skills/.
2. Use a lowercase hyphenated name that matches the skill directory and a concise, trigger-oriented description.
3. Add metadata.hermes.category and metadata.hermes.tags when they improve Hermes discovery without changing the skill's meaning.
4. Add the skill name to the relevant root skills.sh.json grouping.
5. Run uv run scripts/export_hermes_skills.py and uv run scripts/validate_hermes_compatibility.py.
6. Review the generated root skills/ diff with the authored source. The validator requires an exact mirror so a GitHub tap installs the reviewed content.

Hermes users add the Socket tap with hermes skills tap add gaelic-ghost/socket and install a skill by its root export slug, for example hermes skills install gaelic-ghost/socket/hermes-agent-compatibility.

Translate MCP Deliberately

Do not copy a Socket .mcp.json file into Hermes configuration. Translate each server into mcp_servers.<name> in ~/.hermes/config.yaml:

mcp_servers:
  example_server:
    command: "uv"
    args: ["run", "python", "app/server.py"]
    env:
      EXAMPLE_API_KEY: "set-this-in-your-private-config"
    tools:
      include: [read_status]
      prompts: false
      resources: false

Use url instead of command and args for an HTTP MCP server. Keep secrets out of Socket files and use a narrow tools.include list when the server has mutation-capable tools. Validate with hermes mcp test <name> before asking an agent to depend on the server.

Decide Whether a Hermes Plugin Is Needed

Use a real Python Hermes plugin only when the integration needs a registered tool, hook, slash command, CLI command, or namespaced bundled skill that cannot be represented as a standalone skill or external MCP server. A plugin lives in Hermes's plugin install surface, declares plugin.yaml, and exposes behavior from register(ctx) such as ctx.register_tool, ctx.register_hook, or ctx.register_skill.

Do not add a generic Socket-to-Hermes bridge, copy Codex manifests into a Hermes plugin, or create an adapter template without a concrete package that needs runtime behavior. Those would hide host differences rather than make them maintainable.

Report Compatibility Precisely

State each outcome as one of:

• Hermes skill tap supported: the exported SKILL.md is validated and can be installed through the Socket tap.
• Hermes MCP configuration required: a Socket server declaration has a documented mcp_servers translation but no automatic installation.
• Native Hermes plugin required: the requested runtime behavior needs a separate Python plugin and is not supplied by the Socket Codex bundle.
• Not compatible by design: the surface is Codex-specific and has no Hermes equivalent.

Link claims that depend on Hermes behavior to its official skills, MCP, or plugin documentation. Keep the compatibility matrix and examples in Socket's maintainer documentation rather than duplicating full upstream documentation in this skill.