Skill Runtime and SKILL.md Workflow Execution in OpenHuman: Architecture and Implementation

OpenHuman treats SKILL.md workflows as first-class, discoverable, and executable capabilities through a feature-gated runtime under the openhuman::skills::runtime package that handles background orchestration, JSON-RPC exposure, and persistent run-logging.

The skill runtime and SKILL.md workflow execution engine in the tinyhumansai/openhuman repository transforms markdown-based workflow definitions into fully operational agents. According to the source code, this system employs a compile-time feature gate to conditionally include the full runtime or a minimal stub facade, ensuring efficient binary sizes while providing robust APIs for spawning, monitoring, and cancelling workflow executions from both Rust and JSON-RPC clients.

Architecture of the Skill Runtime

Feature-Gated Compilation Strategy

The entire runtime is controlled by the skills Cargo feature defined in src/openhuman/skills/mod.rs. When enabled, the compiler includes the full orchestration stack; when disabled, a stub module provides identical public symbols that return disabled-error values. This facade pattern ensures that code depending on openhuman::skills::runtime compiles regardless of feature flags, returning "skill runtime disabled in this build" errors only at runtime when appropriate.

Core Orchestration in run_machinery.rs

The primary execution logic resides in src/openhuman/skills/runtime/run_machinery.rs, which spawns background tasks to drive workflows and monitors cancellation tokens. The module exposes three critical public APIs:

• spawn_workflow_run_background – Accepts a workflow UUID and initiates asynchronous execution immediately.
• spawn_workflow_run_background_with_profile – Launches a workflow with a custom WorkflowProfile for specialized execution contexts.
• await_run_outcome – Blocks until the running workflow completes and returns the final status structure.

RPC Controllers and Schema Definitions

External clients interact with the runtime through JSON-RPC controllers defined in src/openhuman/skills/runtime/schemas.rs. These controllers register methods such as skill_runtime_schemas, all_skill_runtime_controller_schemas, and all_skill_runtime_registered_controllers, exposing start, stop, and inspect operations to the UI, agent harness, or external tools.

Tool Integration and Agent Execution

Workflow steps translate into OpenHuman tool invocations via src/openhuman/skills/runtime/tools.rs. This adapter layer handles argument serialization, timeout enforcement, and sandboxing for Python scripts, Node.js commands, and shell utilities. For steps requiring specialized logic, the runtime launches short-lived agents through src/openhuman/skills/runtime/agent/skill_executor/mod.rs, which contains the prompt engineering logic in prompt.rs and the main execution loop.

Discovery, Registry, and Run-Logs

Before execution, the catalog module in src/openhuman/skills/catalog/mod.rs discovers locally installed SKILL.md bundles and aggregates remote catalog metadata, while src/openhuman/skills/registry.rs manages installation sources. During execution, progress persists in the run-log (src/openhuman/skills/run_log.rs), allowing clients to poll for intermediate states, streaming output, and success or failure outcomes.

Executing SKILL.md Workflows

Starting Workflows from Rust

Use the re-exported functions from src/openhuman/skills/runtime/mod.rs to launch workflows programmatically:

use openhuman::skills::runtime::{
    spawn_workflow_run_background,
    await_run_outcome,
    WorkflowRunStarted,
};

async fn run_skill(workflow_id: String) -> anyhow::Result<()> {
    // Kick off the workflow in the background.
    let started: WorkflowRunStarted = spawn_workflow_run_background(workflow_id).await?;

    // Optionally wait for the final outcome.
    let outcome = await_run_outcome(started.run_id).await?;
    println!("Workflow finished with status: {:?}", outcome.status);
    Ok(())
}

JSON-RPC Client Integration

Frontend applications can invoke the runtime via the core RPC client:

import { coreRpcClient } from "app/src/lib/coreRpcClient";

async function startSkill(workflowId: string) {
  const { run_id } = await coreRpcClient.call(
    "skill_runtime_start",
    { workflow_id: workflowId }
  );

  let completed = false;
  while (!completed) {
    const log = await coreRpcClient.call("skill_run_log_poll", { run_id });
    console.log(log.entries);
    completed = log.finished;
    await new Promise(r => setTimeout(r, 1000));
  }
}

Cancelling Active Workflows

Cancel a running workflow using the operations layer:

use openhuman::skills::runtime::ops::cancel_workflow_run;

async fn cancel(run_id: String) -> anyhow::Result<()> {
    cancel_workflow_run(run_id).await?;
    Ok(())
}

Key Source Files and Responsibilities

• src/openhuman/skills/runtime/mod.rs – Public façade handling feature-gate logic and re-exports.
• src/openhuman/skills/runtime/run_machinery.rs – Core background runner implementing spawn and await helpers.
• src/openhuman/skills/runtime/schemas.rs – JSON-RPC controller definitions and schema generation.
• src/openhuman/skills/runtime/tools.rs – Adapter layer translating skill steps into OpenHuman tool calls.
• src/openhuman/skills/runtime/ops.rs – High-level operations consumed by the UI and external agents.
• src/openhuman/skills/runtime/agent/skill_executor/mod.rs – Agent executor for internal skill logic.
• src/openhuman/skills/run_log.rs – Persistent storage and polling API for execution logs.
• src/openhuman/skills/catalog/mod.rs – Discovery engine for local bundles and remote catalogs.
• src/openhuman/skills/registry.rs – Installation source management for workflow bundles.

Summary

• The skill runtime compiles conditionally via the skills Cargo feature, falling back to a stub implementation when disabled.
• Core execution happens in run_machinery.rs through spawn_workflow_run_background and await_run_outcome, while RPC exposure in schemas.rs enables cross-language integration.
• Workflow lifecycle is tracked in persistent run-logs (run_log.rs), allowing real-time polling of execution state from UI clients.
• The system supports the full workflow lifecycle: discover (catalog), install (registry), run (runtime), monitor (run-log), and cancel (ops).

Frequently Asked Questions

How does OpenHuman handle skill runtime when the feature is disabled?

When the skills Cargo feature is disabled, src/openhuman/skills/runtime/mod.rs compiles a stub module instead of the full runtime. This stub exposes the same public functions—such as spawn_workflow_run_background—but immediately returns errors indicating the runtime is disabled, ensuring API compatibility without bloating the binary.

What is the difference between spawn_workflow_run_background and spawn_workflow_run_background_with_profile?

The standard spawn_workflow_run_background function launches a workflow with default execution parameters, while spawn_workflow_run_background_with_profile accepts a custom WorkflowProfile argument that specifies specialized configurations such as resource constraints, environment variables, or sandboxing levels for that specific run.

How can external applications monitor SKILL.md workflow progress?

External clients poll the run-log via the skill_run_log_poll JSON-RPC method, which queries the persistent log storage in src/openhuman/skills/run_log.rs. This endpoint returns intermediate states, streaming output entries, and a completion flag, enabling real-time progress tracking without maintaining persistent connections.

Where does the runtime handle tool invocation for workflow steps?

Tool integration occurs in src/openhuman/skills/runtime/tools.rs, which defines adapters translating skill workflow steps into OpenHuman tool calls. This module manages argument marshaling, timeout enforcement, and sandboxing for diverse tool types including Python scripts, Node.js processes, and shell commands.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}