Porting Hermes Agent Skills to OpenCode Requires Removing Decorators and Remapping Schemas

The assumption that switching frameworks requires a complete rewrite of agent logic overlooks a key advantage: existing skills already validated in production can serve as a foundation. What typically changes isn’t the task execution itself, but how the wrapper communicates with the agent. The real challenge lies in adapting the interface layer while preserving the proven functionality beneath.

The transition process hinges on three critical steps: extracting the logic, aligning schemas, and implementing the new wrapper. However, even with these adjustments, behavioral drift remains a risk, as OpenCode’s agentic loop differs from Hermes’ design.

Breaking Down the Migration

Extracting the Core Logic
The first task is to separate the function’s implementation from Hermes-specific decorators. This means locating the raw Python method that performs the action, stripping away any framework dependencies. If the original skill relied on Hermes’ state manager, those references must be replaced with OpenCode’s context handling system. For example, a weather-checking skill would need its internal state references rewritten to use OpenCode’s session-based approach instead.

Schema Alignment
OpenCode enforces stricter requirements for tool descriptions. Docstrings must explicitly define the tool’s purpose, usage context, and parameter constraints. Unlike Hermes, which might tolerate ambiguous inputs, OpenCode’s LLM agent requires precise instructions to avoid misinterpreting arguments. A poorly formatted docstring could lead the agent to hallucinate incorrect parameters, triggering failures during execution.

Wrapper Implementation
The next step is to encase the extracted logic in OpenCode’s tool format. This involves defining a function with a clear docstring and type hints, mirroring the structure OpenCode expects. For instance, a ported weather function would look like this:

def get_weather_data(city: str):
    """
    Retrieves real-time weather information for a specified location.
    Use Case: User requests current conditions in a city.
    Args:
        city (str): Name of the city (e.g., "Paris" or "New York").
    Returns:
        str: Weather description and temperature.
    """
    # Insert ported logic here
    return f"The weather in {city} is currently sunny with a high of 22°C."

Validation and Edge-Case Testing
This phase is where many migrations fail. A skill that worked in Hermes may behave unpredictably in OpenCode due to differences in prompt engineering and tool invocation triggers. To mitigate this, test with edge cases—such as malformed inputs or ambiguous queries—to ensure the agent correctly interprets the ported parameters. If the agent misreads a schema, it may either ignore the tool or pass incorrect arguments, leading to runtime errors.

Alternative Approaches: HarnessRouter as a Bridge

Instead of direct porting, tools like HarnessRouter (available under Apache-2 license on GitHub) offer a unified interface for multiple agent frameworks, including Hermes, OpenCode, and others like Codex and Claude Code. HarnessRouter implements the Unified Harness Protocol (UHP), an open standard that standardizes sessions, streaming, file handling, cancellation, and error recovery. This means a single API can route requests across frameworks without requiring per-framework rewrites. For teams managing multiple agent systems, HarnessRouter eliminates the need to remap schemas repeatedly, reducing maintenance overhead.

Weighing the Trade-offs

The effort required for a direct port varies. Simple API wrappers may take as little as ten minutes to adapt, while skills with complex state management or multi-step dependencies could demand a full rewrite. Behavioral drift—where a reliable skill in Hermes fails in OpenCode—is the primary risk, often stemming from differences in how each framework structures prompts and tool calls.

For most teams, preserving battle-tested logic is preferable to rebuilding from scratch. However, when skills involve intricate workflows or framework-specific integrations, evaluating alternatives like HarnessRouter may prove more efficient in the long run. The decision ultimately depends on whether the skill’s complexity justifies a rewrite or if a targeted port offers a faster path to consistency.