Skip to content

hermes-compatibility.md

Latest commit

 

History

History
319 lines (274 loc) · 16 KB

hermes-compatibility.md

File metadata and controls

319 lines (274 loc) · 16 KB
Raw

Hermes Agent Compatibility

Date checked: 2026-08-10 against published and locally installed Hermes Agent 0.20.0 (2026.8.3), the live machine-readable official docs, and the canonical ACP Registry.

Socket's Hermes compatibility is a durable, explicit compatibility baseline. Every new or materially changed Socket plugin, skill, and MCP declaration must record and validate its Hermes outcome in the same change. This does not turn Socket into a second plugin bundle: Codex-only runtime surfaces remain host-specific unless a concrete native Hermes implementation is designed.

Compatibility Matrix

Socket surface Hermes surface Status
Portable SKILL.md GitHub skill tap export or documented no-export decision Required per changed skill
.codex-plugin/plugin.json None Not compatible by design
Socket .mcp.json Checked-in mcp_servers translation fragments Configuration required
Hooks, apps, and custom agents Host-specific extension decision Not automatically compatible
Runtime tools, hooks, commands, or namespaced skills Python Hermes plugin Separate implementation

Socket Codex plugins are installable distribution bundles; Hermes plugins are Python runtime extensions. Their shared portable unit is the SKILL.md workflow, not either host's plugin manifest.

Hermes Skill Tap

Hermes discovers the root skills/ directory by default after a user adds the Socket tap. The curated set is:

  • build-acp-agent
  • build-hermes-agent-extensions
  • choose-agent-integration-protocol
  • choose-hermes-agent-workflow
  • hermes-agent-compatibility
  • operate-acp-agent-integration
  • operate-a2a-agent-integration
  • operate-hermes-agent
  • operate-hermes-agent-gateway
  • operate-zed-agent
  • use-nous-research-services
  • app-extension-architecture-workflow
  • diagnose-apple-entitlements
  • mailkit-workflow
  • file-provider-and-finder-sync-workflow
  • macos-privacy-permissions-workflow
  • macos-sandbox-file-access-workflow
  • connect-hopper-mcp
  • research-macos-security-control
  • script-hopper-analysis
  • use-ghidra
  • use-hopper
  • choose-swift-language-tooling
  • sourcekit-lsp-workflow
  • swift-compiler-inspection-workflow
  • swift-semantic-indexing-workflow
  • swift-syntax-tooling-workflow
  • choose-model-lab-workflow
  • design-model-experiment
  • prepare-language-model-dataset
  • fine-tune-language-model
  • evaluate-language-model
  • compare-model-checkpoints
  • choose-apple-model-runtime
  • research-model-representations
  • steer-language-model-behavior
  • ablate-refusal-representations
  • evaluate-jailbreak-resilience
  • evaluate-tool-calling-model
  • benchmark-model-runtime
  • python-testing-workflow
  • coordinate-external-agents
  • coordinate-worktrees-and-threads
  • orchestrate-agent-work
  • repository-operations-workflow
  • git-workflow
  • github-collaboration-workflow
  • maintain-github-repository
  • maintain-project-repo
hermes skills tap add gaelic-ghost/socket
hermes skills search portability
hermes skills install gaelic-ghost/socket/hermes-agent-compatibility

The ACP workflows keep source support, package publication, canonical registry publication, and client runtime proof as separate states. Hermes 0.20.0 ships an official acp_registry/agent.json and PyPI ACP extra, but the live canonical ACP Registry did not contain hermes-agent on 2026-08-10. Until an official entry is accepted and published, Zed users should validate hermes acp --check and use Zed's custom-agent command rather than an unrelated launcher.

Custom GitHub taps are community sources and Hermes security-scans skills at install time. Review a finding before using --force; Hermes does not let that flag override a dangerous verdict.

The expanded Hermes set deliberately separates protocol routing, A2A agent-to-agent operation, day-to-day operation, extension development, messaging/API gateway operation, and Nous-hosted services. The compatibility skill remains responsible only for Socket-to-Hermes classification and export decisions.

The currently exported skills are listed in skills.sh.json. Their canonical sources remain in their owning child plugins; root skills/ is a checked-in generated export because the GitHub tap API needs real child directories, not a symlink mirror. Root skills.sh.json supplies Skills Hub grouping labels. The historical Socket inventory is not yet fully exported; the roadmap tracks that migration. New or materially changed skills must either join the generated tap with grouping metadata or document why their workflow is not portable to Hermes.

The complete cybersecurity-skills inventory is portable guidance and is exported under the Cybersecurity Skills grouping. Its Codex manifest and icon remain host-specific packaging metadata. The initial plugin ships no MCP server, hook, app, custom agent, or native Hermes runtime surface, so no mcp_servers translation or Python Hermes plugin is required.

The complete model-lab-skills inventory is portable guidance and is exported under the Model Lab Skills grouping. Its deterministic Python helpers operate on caller-supplied local manifests, JSONL results, and model artifacts; they do not require a host API, MCP server, hook, app, custom agent, or native Hermes plugin.

The exported Hopper and Ghidra workflows are portable guidance. Hopper's GUI, Python SDK, and HopperMCPServer remain operator-local runtime surfaces. The Hopper MCP profile is therefore private user configuration, not a Socket .mcp.json declaration or a native Hermes plugin.

The exported Swift language-tooling workflows are portable guidance. They resolve and invoke operator-installed Swiftly or Xcode tools but bundle no compiler, SourceKit service, language server, MCP declaration, hook, or native Hermes runtime. Hermes skill-tap support therefore preserves their real instruction contract without presenting the Codex plugin manifest as portable.

The exported Swift package extension workflow is likewise portable guidance. It resolves operator-installed Swiftly and Xcode tools and plans SwiftPM plugin, macro, trait, generated-source, and permission work without bundling a compiler, plugin runtime, MCP server, or native Hermes extension.

The exported F# web-framework workflows are portable instruction contracts. They use the operator's .NET SDK and project dependencies but bundle no runtime, framework package, MCP server, hook, or native Hermes extension. The cloud deployment routing workflow and Dockerized-service release/deployment workflow are also portable guidance: they route Azure work to Microsoft's official Azure Skills plugin and define a clean-CI, exact-digest release contract, but do not claim that Azure MCP, provider credentials, or production deployment adapters are automatically installed or configured in Hermes.

The exported Python workflows are portable guidance. They guide uv-managed agent services, FastAPI services, FastMCP services, and tests while relying on operator-installed Python tooling and project dependencies. They package no MCP server, credentials, hook, app, or native Hermes runtime surface.

The exported repository workflows are portable guidance. They use the operator's git and, for GitHub work, authenticated gh CLI. They distinguish read-only inspection from pushing, merging, tagging, deletion, settings changes, publishing, and release actions; those mutations still need explicit authority or a repository-owned release contract. The host-neutral coordinator workflows accompany them so a Hermes agent can record worktree, branch, write, validation, and handoff ownership. codex-gui-worktree-workflow remains Codex-specific because its thread association and managed-worktree state have no Hermes equivalent.

A named autonomous git-steward remains a future native Hermes-plugin decision. The current tap provides reusable workflow instructions, not a registered runtime role, slash command, credential store, or additional GitHub authority.

The exported macOS platform-security workflows are portable instruction contracts. Public app permission, sandbox file-access, and entitlement diagnosis remain in Apple Dev Skills; exact-build private-control research remains in Reverse Engineering Skills; defensive host investigation remains in Cybersecurity Skills. Hermes does not receive a TCC database tool, permission grant service, privileged helper, protection bypass, or native runtime plugin from this work.

Maintainer Workflow

  1. Classify each changed surface before editing: portable skill, translated MCP, native Hermes-plugin candidate, or Codex-only by design.

  2. For each portable skill, edit the canonical child-plugin source, use a lowercase hyphenated directory and matching frontmatter name, provide a trigger-oriented description, and add it to the Hermes export inventory and skills.sh.json. Add metadata.hermes.category and metadata.hermes.tags when discovery benefits.

  3. For each changed .mcp.json, update its matching checked-in translation and hermes-mcp/index.yaml entry. A Codex manifest alone never satisfies this requirement.

  4. For a runtime-only surface, record either its concrete native Hermes plugin design or the reason it remains host-specific; do not add a packaging shim.

  5. Regenerate and validate:

    just repo-sync
just repo-validate

  6. Run the root metadata validator and relevant tests before review.

The focused validator fails for malformed frontmatter, wrong names, missing descriptions, stale generated content, grouping drift, machine-local metadata paths, invalid maintained MCP examples, or an unaccounted Socket MCP declaration. It warns, without blocking, when a description exceeds 240 characters.

MCP Translation

Socket .mcp.json files are Codex declarations, not portable Hermes config. Every declared Socket MCP configuration, including each new or changed one, is translated under hermes-mcp/, with the complete inventory and setup status in hermes-mcp/index.yaml. Copy the chosen fragment's mcp_servers mapping into the operator's private ~/.hermes/config.yaml and complete any listed setup first. The checked-in fragments never require a machine-local path.

Hermes config has this shape:

mcp_servers:
  socket_example_stdio:
    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
  socket_example_http:
    url: "https://example.invalid/mcp"
    tools:
      include: [read_docs]
      prompts: false
      resources: true

The checked-in example YAML demonstrates optional filtering fields, while the per-plugin fragments preserve each Socket server's actual name and transport. Replace placeholders in private configuration, never in Socket. The translations do not add filtering where no direct safety/namespace reason exists. Configure required secrets through the explicit env mapping or Hermes process environment, then reload MCP configuration with /reload-mcp and test the enabled server before use.

An external local server such as Hopper does not join this translation inventory unless Socket begins distributing a portable launcher. Its operator profile belongs in private Codex and Hermes configuration and must use the installed server command plus a deliberately small tool allowlist.

Socket declaration Checked-in Hermes translation Status
Apple Dev Skills Xcode bridges apple-dev-skills.yaml Manual Xcode setup required
Cloud Inference Runpod API and docs servers cloud-inference-skills.yaml Ready; API server needs RUNPOD_API_KEY
Professional Dice server professional-skills.yaml Ready; basic public search needs no credential

When a Native Hermes Plugin Is Required

Write a dedicated general Python Hermes plugin only when a concrete Socket feature needs runtime registration: a tool handler, plugin lifecycle hook, slash command, CLI command, or namespaced skill bundle. A real plugin has its own plugin.yaml and register(ctx) entry point.

Hermes now documents multiple specialized extension systems in addition to the general plugin API: messaging platform adapters, model providers, memory providers, context engines, secret sources, image and video providers, web search providers, browser providers, desktop plugins, and dashboard plugins. Config-driven TTS, STT, MCP, and shell hooks plus drop-in gateway hooks are separate again. Select the subsystem that owns the behavior; do not hide these contracts behind one generic Socket bridge.

Do not add a generic Socket bridge or boilerplate plugin merely to mirror Codex packaging. Instruction workflows remain skills; external tool servers remain MCP. A native plugin is a separate implementation and distribution decision.

The concrete, prioritized future work is in the Hermes native Python plugin adapter plan. It classifies each candidate as a tool, hook, slash command, CLI command, bundled read-only skill, platform/backend provider, or no adapter, and names the required configuration and test shape before any implementation begins.

Verification and Limits

This release validates the repository shape and generated tap without mutating a user's Hermes home. It does not claim that every Socket child plugin, MCP server, hook, app, or custom agent runs in Hermes; the required outcome is an explicit, validated compatibility classification, not a fictional universal runtime.

  • Hermes skill tap supported: the skill is in root skills/ and passes the Hermes validator.
  • Hermes MCP configuration required: a translation is documented, but the operator configures and tests it in Hermes.
  • Native Hermes plugin required: runtime Python registration is needed.
  • Not compatible by design: it is a Codex-only or other host-specific surface.

Authoritative References

  • Hermes Skills System covers GitHub taps, root skills/, skills.sh.json, and frontmatter.
  • Hermes Creating Skills covers the skill-versus-tool decision and custom tap publishing.
  • Hermes MCP covers stdio and HTTP server configuration.
  • Hermes MCP Config Reference defines mcp_servers transport, environment, filtering, and timeout fields.
  • Hermes Plugins defines plugin discovery, general and specialized plugin categories, and Python runtime extensions.
  • Hermes plugin developer guide maps general plugins, provider plugins, platform adapters, config-driven extensions, desktop/dashboard plugins, and programmatic integration choices.
  • Hermes Programmatic Integration distinguishes ACP, TUI gateway JSON-RPC, and the OpenAI-compatible API server.
  • Hermes ACP Editor Integration documents the ACP toolset, shared Hermes state, health checks, sessions, and editor launch paths.
  • ACP Registry is the publication source of truth; a source-owned manifest alone is not a published registry entry.
  • Nous Portal distinguishes Portal inference, managed Tool Gateway routes, Nous Chat, and subscription-backed services.
  • Agent Skills is the shared progressive-disclosure skill format that keeps Socket's exported SKILL.md workflows portable.