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

> Explore the skill runtime and SKILL.md workflow execution in OpenHuman. Learn how OpenHuman orchestrates, exposes, and logs workflows for seamless capability management.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: architecture
- Published: 2026-08-29

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/runtime/agent/skill_executor/mod.rs), which contains the prompt engineering logic in [`prompt.rs`](https://github.com/tinyhumansai/openhuman/blob/main/prompt.rs) and the main execution loop.

### Discovery, Registry, and Run-Logs

Before execution, the `catalog` module in [`src/openhuman/skills/catalog/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/catalog/mod.rs) discovers locally installed SKILL.md bundles and aggregates remote catalog metadata, while [`src/openhuman/skills/registry.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/registry.rs) manages installation sources. During execution, progress persists in the **run-log** ([`src/openhuman/skills/run_log.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/runtime/mod.rs) to launch workflows programmatically:

```rust
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:

```typescript
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:

```rust
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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/runtime/mod.rs)** – Public façade handling feature-gate logic and re-exports.
- **[`src/openhuman/skills/runtime/run_machinery.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/runtime/run_machinery.rs)** – Core background runner implementing spawn and await helpers.
- **[`src/openhuman/skills/runtime/schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/runtime/schemas.rs)** – JSON-RPC controller definitions and schema generation.
- **[`src/openhuman/skills/runtime/tools.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/runtime/tools.rs)** – Adapter layer translating skill steps into OpenHuman tool calls.
- **[`src/openhuman/skills/runtime/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/runtime/agent/skill_executor/mod.rs)** – Agent executor for internal skill logic.
- **[`src/openhuman/skills/run_log.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/run_log.rs)** – Persistent storage and polling API for execution logs.
- **[`src/openhuman/skills/catalog/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/skills/catalog/mod.rs)** – Discovery engine for local bundles and remote catalogs.
- **[`src/openhuman/skills/registry.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/run_machinery.rs) through `spawn_workflow_run_background` and `await_run_outcome`, while RPC exposure in [`schemas.rs`](https://github.com/tinyhumansai/openhuman/blob/main/schemas.rs) enables cross-language integration.
- **Workflow lifecycle** is tracked in persistent run-logs ([`run_log.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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.